message.received
Sent for every message a customer writes to one of your numbers. Use it to answer customers or to keep your own record of the chat. data is the Message.
Called Message received in the app. Part of the plan feature webhooks.messages. To subscribe over the API, the key needs messages:read.
What’s in data. Every event wraps it in the same envelope.
id string · uuid
contact_id string · uuid
number_id string · uuid · nullable
The number it was sent from or to. null if that number was removed.
direction string
One of incoming outgoing.
type string
The kind of message: text, image, video, audio, document, sticker, template, interactive, button_reply, list_reply, flow_reply, location, contact, reaction or unsupported. More values may be added.
status string
pending (accepted, not yet with WhatsApp), sent, delivered,
read or failed for outgoing messages; received for incoming
ones.
text object · nullable
The text. For location, contact, reaction, reply and flow messages it’s a readable summary.
Show 1 child attributesHide child attributes
text.body string
media object · nullable
The file the message carries, or a template’s header file.
Show 4 child attributesHide child attributes
media.url string
Where to download it, /v1/messages/{id}/media.
media.mime_type string · nullable
media.filename string · nullable
media.caption string · nullable
template object · nullable
The template it was sent with.
Show 3 child attributesHide child attributes
template.id string · uuid · nullable
template.name string
template.language string · nullable
interactive object · nullable
Reply buttons or a link button the message offered.
Show 5 child attributesHide child attributes
interactive.type string
One of buttons cta_url.
interactive.body string
interactive.buttons array of objects
Show 2 child attributesHide child attributes
Each item:
interactive.buttons[].id string
1 to 256 characters.
interactive.buttons[].title string
1 to 20 characters.
interactive.url string · nullable
interactive.display_text string · nullable
reply_to_message_id string · uuid · nullable
The message it quotes.
whatsapp_message_id string · nullable
WhatsApp’s ID for the message, once WhatsApp has it.
error object · nullable
Why the message failed.
Show 2 child attributesHide child attributes
error.code integer
WhatsApp’s error code, or 0 if it isn’t known.
error.message string
sent_by object · nullable
Who sent an outgoing message. null for incoming ones.
Show 3 child attributesHide child attributes
sent_by.type string
Who or what it was: a team member, an API key, the chatbot, the AI, an automation, a broadcast, the WhatsApp Business app or Soosh itself. More values may be added.
One of user api_key bot ai automation broadcast whatsapp_app system.
sent_by.id string · uuid · nullable
The person, key or broadcast. null for actors without one, such as the chatbot.
sent_by.name string
broadcast_id string · uuid · nullable
The broadcast that sent it.
created_at string · date-time
updated_at string · date-time
Handling it
Section titled “Handling it”- Answer with any
2xxwithin 10 seconds. Do the work after. - Check the signature first. Verify webhooks has the code.
- Subscribe with
POST /v1/webhooks,events: ["message.received"].