Send Messages

Send Event

Sends a calendar event message to a chat. Users can tap on the event to view details, add it to their calendar, or join a call.

POST
https://api.wawp.net/v2/send/event?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890&event.description=Discussing+Q1+Roadmap&event.endTime=1735923600&event.extraGuestsAllowed=true&event.location.name=Meeting+Room+A&event.name=Team+Meeting+%F0%9F%93%85&event.startTime=1735920000&instance_id=YOUR_INSTANCE_ID&reply_to=false_111...AAAA

Authentication Required

Login to swap the placeholders with your real Instance ID and Access Token.

Log In
Test /v2/send/event endpoint
POST
POST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Use "reply_to" to maintain conversation context.

  • Handle distinct message types (text, image, video) appropriately.

  • Implement a robust retry mechanism for failed sends.

Orchestrating Time: Mastering the WhatsApp Event Engine

The /v2/send/event endpoint introduces a sophisticated way to manage time and attendance directly within a chat. Instead of sending a plain text reminder that a user might forget, "Event Messages" create a professional, structured calendar object. These objects allow users to view duration, location, and description in a dedicated UI and, most importantly, add the event to their local mobile calendar (Google Calendar, iCal, etc.) with a single tap.

Send Event.png

🏗️ The Event Lifecycle Architecture

An Event message is more than a notification; it's a persistent state-object within the chat:

  1. Timestamp Precision: The engine uses Unix timestamps (in seconds) to define the startTime and endTime. Wawp validates that the end time occurs after the start time and handles the translation of these timestamps into the recipient's local phone time zone automatically.
  2. Metadata Aggregation: The event.name, event.description, and event.location.name are aggregated into a native WhatsApp Event packet. This packet is interactive—users can click it to expand a "Full Details" view that remains accessible even after the chat has moved on.
  3. Guest Management: The extraGuestsAllowed flag is a structural signal. If true, it signals to the user that the event is open for broader participation, often used in webinars or community gatherings.

🛡️ Strategic Best Practices for Event Engagement

1. The "Call-to-Action" Description

The event.description is your most valuable text field.

  • Deep Linking: If the event is a virtual meeting (Zoom, Google Meet, WhatsApp Call), include the join link directly in the description. Most mobile OSs will recognize the URL and make it clickable within the event details view.
  • Engagement: Use the description to provide a high-level agenda. Since the event persists at the top of the chat or in the "Media/Links/Docs" section, it acts as a permanent reference point for the user.

2. Timezone Integrity

One of the biggest causes of missed appointments is timezone confusion.

  • The Global Standard: Wawp expects Unix timestamps in UTC. Never send timestamps in a local format without first normalizing them to the UTC epoch.
  • User Experience: Because Wawp hands the UTC timestamp to the WhatsApp network, the recipient's phone will automatically display the time in their local time (e.g., if you send an event for 3 PM UTC, a user in London sees 3 PM, while a user in New York sees 10 AM).

3. Location Clarity (Physical vs. Virtual)

  • Physical Events: Use the event.location.name for the room number or building name.
  • Virtual Events: Set the location name to "💻 Virtual Meeting" or "🎥 Live Stream." This provides instant visual context before the user even opens the details.

🧩 Advanced Use Cases

Automated Webinar Onboarding

When a user signs up for a webinar via a bot, trigger a /v2/send/event immediately. This allows the user to click "Add to Calendar" while their intent is high. Combine this with the reply_to parameter to link the event card to their "Successful Registration" text message.

Service Appointment Booking

For hair salons, doctors, or repair services, send an event card as soon as the appointment is confirmed. The professional look of an Event card significantly increases the "Perceived Quality" of the service and reduces the rate of "No-Shows" by integrating with the user's primary planning tool (their calendar).

🛠️ Common Pitfalls and Solutions

  • Seconds vs. Milliseconds: A common technical error is sending JS Date.now() (which is milliseconds) instead of the required Unix seconds. This will result in an event scheduled thousands of years in the future. Always divide by 1000.
  • Short Durations: While WhatsApp allows very short events, we recommend a minimum duration of 15 minutes to ensure the calendar block is visually significant enough for the user to notice.
  • The "Overlapping" Conflict: WhatsApp doesn't prevent you from sending overlapping events, but your system should. If a session is already busy, consider using a poll first to find an available slot before sending the final Event card.

Summary of Capabilities:

  • Deliver interactive, native-style WhatsApp Event cards with one-tap calendar integration.
  • Full support for Unix-timestamp based scheduling with automatic timezone normalization.
  • High-fidelity metadata support for event names, descriptions, and custom locations.
  • Structural signaling for guest permissions via the extraGuestsAllowed flag.
  • Seamless integration with conversational threads via the reply_to parameter.
  • Persistent UI presence within the chat, acting as a permanent reference for scheduled activities.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object
string

Unique ID of the WhatsApp session

Example:
string

API access token

Example:
string

Recipient's WhatsApp number

Example:
string

Name of the event (e.g. Team Meeting 📅)

Example:
string

Discussing Q1 Roadmap

Example:
number

Start time (Unix timestamp in seconds)

Example:
number

End time (Unix timestamp in seconds)

Example:
string

Meeting Room A

Example:
boolean

Whether extra guests are allowed

Example:
string—

The ID of the message you are replying to

Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/send/event";
3const params = new URLSearchParams({
4  "instance_id": "YOUR_INSTANCE_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "chatId": "201234567890",
9  "event.name": "Team Meeting 📅",
10  "event.description": "Discussing Q1 Roadmap",
11  "event.startTime": "1735920000",
12  "event.endTime": "1735923600",
13  "event.location.name": "Meeting Room A",
14  "event.extraGuestsAllowed": "true",
15  "reply_to": "false_111...AAAA"
16};
17
18fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
19  method: "POST",
20  headers: { "Content-Type": "application/json" },
21  body: JSON.stringify(body)
22})
23  .then(async (response) => {
24    if (response.ok) {
25      const data = await response.json();
26      console.log("Success:", data);
27      return data;
28    }
29    
30    // Error Handling
31    if (response.status === 400) {
32      console.error("Error 400: Bad Request - Missing Required Parameter(s)");
33    }
34    if (response.status === 400) {
35      console.error("Error 400: Bad Request - Invalid Number (Egypt)");
36    }
37    if (response.status === 400) {
38      console.error("Error 400: Bad Request - Invalid Number (Saudi Arabia)");
39    }
40    if (response.status === 400) {
41      console.error("Error 400: Bad Request - Invalid Number (Unknown)");
42    }
43    if (response.status === 400) {
44      console.error("Error 400: Bad Request (XML Format)");
45    }
46    if (response.status === 400) {
47      console.error("Error 400: Bad Request (Plain Text)");
48    }
49    if (response.status === 401) {
50      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
51    }
52    if (response.status === 401) {
53      console.error("Error 401: Unauthorized (XML Format)");
54    }
55    if (response.status === 404) {
56      console.error("Error 404: Not Found - Session Does Not Exist");
57    }
58    if (response.status === 404) {
59      console.error("Error 404: Not Found (XML Format)");
60    }
61    if (response.status === 429) {
62      console.error("Error 429: Too Many Requests - Rate Limit Exceeded");
63    }
64    if (response.status === 500) {
65      console.error("Error 500: Internal Server Error - Unexpected Failure");
66    }
67    if (response.status === 500) {
68      console.error("Error 500: Internal Server Error (HTML)");
69    }
70    if (response.status === 502) {
71      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
72    }
73    if (response.status === 502) {
74      console.error("Error 502: Bad Gateway (XML Format)");
75    }
76
77    const errorText = await response.text();
78    console.error(`Error ${response.status}: ${errorText}`);
79  })
80  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 80, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Message Sent Successfully
Type:
application/json
object *
string *
object *
number *
boolean *
string *
string *
number *
string *
string *
string *
boolean *
number *
boolean *
boolean *
boolean *
boolean *
boolean *
array *
array *
array *
boolean *
array *

Example

{
"_data": {
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
  "viewed": false,
  "body": "BASE64_IMAGE_DATA",
  "type": "image",
  "t": 1759108866,
  "from": {
    "server": "c.us",
    "user": "111111111111",
    "_serialized": "111111111111@c.us"
    },
  "to": {
    "server": "c.us",
    "user": "000000000000",
    "_serialized": "000000000000@c.us"
    },
  "ack": 0,
  "isNewMsg": true,
  "star": false,
  "kicNotified": false,
  "caption": "Here's your requested image.",
  "deprecatedMms3Url": "https://example.com/media-url",
  "directPath": "/media/direct/path/example",
  "mimetype": "image/jpeg",
  "filehash": "FILE_HASH_PLACEHOLDER",
  "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
  "size": 192487,
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "mediaKeyTimestamp": 1759108865,
  "streamable": false,
  "mediaHandle": null,
  "isFromTemplate": false,
  "pollInvalidated": false,
  "isSentCagPollCreation": false,
  "latestEditMsgKey": null,
  "latestEditSenderTimestampMs": null,
  "mentionedJidList": {
    },
  "groupMentions": {
    },
  "isEventCanceled": false,
  "eventInvalidated": false,
  "isVcardOverMmsDocument": false,
  "isForwarded": false,
  "isQuestion": false,
  "questionReplyQuotedMessage": null,
  "questionResponsesCount": 0,
  "readQuestionResponsesCount": 0,
  "labels": {
    },
  "hasReaction": false,
  "disappearingModeInitiator": "chat",
  "disappearingModeTrigger": "chat_settings",
  "productHeaderImageRejected": false,
  "lastPlaybackProgress": 0,
  "isDynamicReplyButtonsMsg": false,
  "isCarouselCard": false,
  "parentMsgId": null,
  "callSilenceReason": null,
  "isVideoCall": false,
  "callDuration": null,
  "callCreator": null,
  "callParticipants": null,
  "isCallLink": null,
  "callLinkToken": null,
  "isMdHistoryMsg": false,
  "stickerSentTs": 0,
  "lastUpdateFromServerTs": 0,
  "invokedBotWid": null,
  "bizBotType": null,
  "botResponseTargetId": null,
  "botPluginType": null,
  "botPluginReferenceIndex": null,
  "botPluginSearchProvider": null,
  "botPluginSearchUrl": null,
  "botPluginSearchQuery": null,
  "botPluginMaybeParent": false,
  "botReelPluginThumbnailCdnUrl": null,
  "botMessageDisclaimerText": null,
  "botMsgBodyType": null,
  "requiresDirectConnection": false,
  "bizContentPlaceholderType": null,
  "hostedBizEncStateMismatch": false,
  "senderOrRecipientAccountTypeHosted": false,
  "placeholderCreatedWhenAccountIsHosted": false,
  "galaxyFlowDisabled": false,
  "links": {
    }
  },
"mediaKey": "MEDIA_KEY_PLACEHOLDER",
"id": {
  "fromMe": true,
  "remote": "000000000000@c.us",
  "id": "MSG_ID_123456",
  "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
"ack": 0,
"hasMedia": true,
"body": "Here's your requested image.",
"type": "image",
"timestamp": 1759108866,
"from": "111111111111@c.us",
"to": "000000000000@c.us",
"deviceType": "android",
"isForwarded": false,
"forwardingScore": 0,
"isStatus": false,
"isStarred": false,
"fromMe": true,
"hasQuotedMsg": false,
"hasReaction": false,
"vCards": {
  },
"mentionedIds": {
  },
"groupMentions": {
  },
"isGif": false,
"links": {
  }
}
Bad Request - Missing Required Parameter(s)
Unauthorized - Invalid or Missing Access Token
Not Found - Session Does Not Exist
Too Many Requests - Rate Limit Exceeded
Internal Server Error - Unexpected Failure
Bad Gateway - Connection Failed to Upstream
Previous TopicSend List Message
Next TopicSend Voice

Command Palette

Search for a command to run...