WhatsApp: message received | Swarmhit Developers

A new message in a chat, the number's own included (is_sender): message_received.

Header Parameters

X-LG-Signature*string

base64url(HMAC-SHA256(raw body, your webhook's signing secret)), the secret being the whsec_… shown in the console. Verify it over the raw bytes before parsing, and refuse the event when it does not match.

X-LG-Event-Id*string

The event id, also event_id in the body: the same on every retry of the event. Deduplicate on it.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

event*string

The event's name: message_received, message_delivered, message_read, message_edited, message_deleted, message_reaction or gateway.message_failed.

account_id*string

The WhatsApp number (wa_…).

account_type?string

Always WHATSAPP.

account_info?

The number itself.

chat_id*string

The chat (wac_…), as GET /whatsapp/api/v1/chats/{id} takes it.

timestamp?|

When the message was sent (UTC, ISO 8601); null when WhatsApp gave no time.

Formatdate-time

message_id*string

The message (wam_…), as GET /whatsapp/api/v1/messages/{id} takes it: the same id on all of a message's events.

provider_chat_id?string

The chat's WhatsApp JID: …@s.whatsapp.net or …@lid for a person, …@g.us for a group.

provider_message_id?string

WhatsApp's own id for the message.

is_group?boolean

true when the chat is a group.

is_sender?boolean

true when the number itself sent the message (through the API or from any of its devices).

message?|

The message's text (or a file's caption); null when there is none.

sender?|

Who sent it (the number itself when is_sender); null when WhatsApp named no sender.

attendees?array<>

One-to-one chats: the person and the number. Empty for a group (read GET /chats/{id}/attendees).

attachments?array<>

The message's files (image, video, audio, voice note, document, sticker, contact, location); empty when there are none. Download one with GET /whatsapp/api/v1/messages/{id}/attachments/{attachmentId}.

quoted?

Present when the message replies to another: the message it quotes.

is_forwarded?boolean

true when the message was forwarded from another chat.

mentions?

Who the message mentions (a group's @someone): each JID mapped to its phone number, or to the JID itself when it is not a phone number. Absent when nobody is mentioned.

subject?string

Groups: the group's name.

event_id*string

The event's id, also in the X-LG-Event-Id header: the same on every retry of the event, so deduplicate on it. A random UUID, or ev_… for an event about one thing (a message, a connection) noticed twice.

emitted_at*string

When Swarmhit wrote the event (UTC, ISO 8601), not when it was delivered. A retry keeps it: for statuses, keep the one with the newest emitted_at.

Formatdate-time

livemode?boolean

true for an event of a live account, false for a sandbox account's (sent to your sandbox webhook).

Response Body

Example Requests

POST/WhatsappMessageReceived

Header Parameters

Request Body

Response Body

200

Request Bodyapplication/json

Header Parameters