When a client sends you a message, the WhatsApp Business API client will send an HTTPS POST request notification to the Webhook URL with the details that are described in this manual.
Webhooks user-defined HTTP callbacks that are triggered by specific events. Whenever a trigger occurs, the WhatsApp Business API client will see the event, collect the data, and immediately send a notification (HTTP request) to the WhatsApp URL specified in the application settings, updating the status of the messages sent or indicating when you receive a message.
It is important that your Webhook returns an HTTPS 200 OK response to notifications. Otherwise, the WhatsApp Business API client will consider this notification a failure and retry after a delay.
Configuring notification settings
webhooks: provide the URL for your Webhook. MANDATORY when using Webhooks. If the Webhook URL is not defined, callbacks are removed.
Whenever possible, names will be kept constant across functions. (For example, all timestamps are calledtimestamp).
Notification Webhook Format
All possible fields of notification Webhooks are shown below.
Example
POST / { "contacts": [ { "profile": { "name": "sender-profile-name" }, "wa_id": "wa-id-of-contact" } ], "messages": [ "context": { "from": "sender-wa-id-of-context-message", "group_id": "group-id-of-context-message", "id": "message-id-of-context-message", "mentions": [ "wa-id1", "wa-id2" ] }, "from": "sender-wa-id", "group_id": "group-id", "id": "message-id", "timestamp": "message-timestamp", "type": "audio | document | image | location | system | text | video | voice", # Se houver algum erro, o campo de erros (matriz) estará presente. # O campo de erros pode ser retornado como parte de qualquer evento de retorno de chamada. "errors": [ { ... } ], "audio": { "file": "absolute-filepath-on-coreapp", "id": "media-id", "link": "link-to-audio-file", "mime_type": "media-mime-type", "sha256": "checksum" } "document": { "file": "absolute-filepath-on-coreapp", "id": "media-id", "link": "link-to-document-file", "mime_type": "media-mime-type", "sha256": "checksum", "caption": "document-caption" } "image": { "file": "absolute-filepath-on-coreapp", "id": "media-id", "link": "link-to-image-file", "mime_type": "media-mime-type", "sha256": "checksum", "caption": "image-caption" } "location": { "address": "1 Hacker Way, Menlo Park, CA, 94025", "latitude": latitude, "longitude": longitude, "name": "location-name" } "system": { "body": "system-message-content" } "text": { "body": "text-message-content" } "video": { "file": "absolute-filepath-on-coreapp", "id": "media-id", "link": "link-to-video-file", "mime_type": "media-mime-type", "sha256": "checksum" } "voice": { "file": "absolute-filepath-on-coreapp", "id": "media-id", "link": "link-to-audio-file", "mime_type": "media-mime-type", "sha256": "checksum" } ] }
Notification errors
When there are out of band errors that occur in the normal operation of the application, the errors matrix will provide a description of the error. This type of error can be caused by temporary network connectivity errors, invalid credentials, management controllers with unavailable status, and so on. If you receive an error, see Error and status messages for more information.
The errors object
The errors object contains the following parameters:
Incoming message notifications
You receive a notification when your company receives a message. The object sectionmessages below shows all the information that can be received about an incoming message.
When a media message is received, the WhatsApp Business API client downloads the media file. A notification is sent to your Webhook when the media file is downloaded. This message contains information that identifies the media object and allows you to find and retrieve the object. Use the media endpoint with the media id to retrieve it.
Example: Incoming message with image
{
"messages":[{
"from":"16315551234",
"id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"image":{
"file":"/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
"id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
"mime_type":"image/jpeg",
"sha256":"29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db"
"caption": "Check out my new phone!"},
"timestamp":"1521497954",
"type":"image"
}]
}
Users can respond to a specific message on WhatsApp. For your company to understand the context of a message response, we included the object context. This context objects provides the id of the message to which your client responded and the ID of the original WhatsApp message sender.
System messages are generated when an event occurs, for example, an user added/removed another user or left a group, etc. See the system object section below for more information.
