Webhook
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.
webhooks: provide the URL for your Webhook. MANDATORY when using Webhooks. If the Webhook URL is not defined, callbacks are removed.
Name | object content |
messages | Notifications of incoming messages |
statuses | Message status updates |
errors | Serious errors outside the band |
Whenever possible, names will be kept constant across functions. (For example, all timestamps are calledtimestamp).
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" } ] }
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.
Example
POST / { "errors": [ { "code": <error-code>, "title": "<error-title>", "details": "<error-description>", "href": "location for error detail" }, { ... } ] }
The errors object
The errors object contains the following parameters:
Name of field | Description | Type |
code | Error code | Numeric |
title | Error title | String |
details | Optional. Error details provided, if available/applicable | String |
href | Optional. Error location details | String |
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.
{"contacts": [ {"profile": {"name": "Kerry Fisher"},"wa_id": "16315551234"} ],"messages":[{"from": "16315551234","id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf","timestamp": "1518694235","text": {"body": "Hello this is an answer"},"type": "text"}]}
{"contacts": [ {"profile": {"name": "Kerry Fisher"},"wa_id": "16315551234"} ],"messages":[{"from":"16315551234","id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf","location":{"address":"Main Street Beach, Santa Cruz, CA","latitude":38.9806263495,"longitude":-131.9428612257,"name":"Main Street Beach","url":"https://foursquare.com/v/4d7031d35b5df7744"},"timestamp":"1521497875","type":"location"}]}
{"contacts": [ {"profile": {"name": "Kerry Fisher"},"wa_id": "16315551234"} ],"messages": [{"contacts": [{"addresses": [{"city": "Menlo Park","country": "United States","country_code": "us","state": "CA","street": "1 Hacker Way","type": "WORK","zip": "94025"}],"birthday": "2012-08-18","contact_image": "/9j/4AAQSkZJRgABAQEAZABkAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCABgAGADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD1NLloxyc0j3bNUHDGgoCMVNkBbhutvVqc9yGHNZ3kOW4Wn/ZnQZzSsgLLXAA61Xn1O2t4zLcyJHGvV3OAKMADmvOviLq9m11a2bO/l2xLzoqnliF2j9f1NTLRXHGHM7Hb2vivSL+8e0s7yKaVeyHg/Q9D+FXWuHPOzivFodT0WZkeF44bheVdE2EH+Rr2+zuVuNPt7gqh86JX+TkcjPFTCdy6lNQ2dyr5+G5WpRe4HTFWWSOQfwioZbCIn5XNaXRmQPegjmqrKLh+...","emails": [{"email": "kfish@fb.com","type": "WORK"}],"ims": [{"service": "AIM","user_id": "kfish"}],"name": {"first_name": "Kerry","formatted_name": "Kerry Fisher","last_name": "Fisher"},"org": {"company": "Facebook"},"phones": [{"phone": "+1 (940) 555-1234","type": "CELL"},{"phone": "+1 (650) 555-1234","type": "WORK","wa_id": "16505551234"}],"urls": [{"url": "https://www.facebook.com","type": "WORK"}]}],"from": "16505551234","id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR","timestamp": "1537248012","type": "contacts"}]}
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.
{"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"}]}
{"messages":[{"from":"16315551234","id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf","timestamp":"1522189546","type":"document","document":{"caption":"80skaraokesonglistartist","file":"/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33","id":"fc233119-733f-49c-bcbd-b2f68f798e33","mime_type":"application/pdf","sha256":"3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e"}}]}
{"messages":[{"from": "16315551234","id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf","timestamp": "1521827831","type": "voice","voice": {"file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2","id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2","mime_type": "audio/ogg; codecs=opus","sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"}}]}
{"messages":[{"from": "16315551234","id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf","timestamp": "1521827831","type": "sticker","sticker": {"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683","metadata": {"sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2","sticker-pack-name" : "Happy New Year","sticker-pack-publisher" : "Kerry Fisher","emojis": ["🐥", "😃"],"ios-app-store-link" : "https://apps.apple.com/app/id3133333","android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example","is-first-party-sticker" : 0 | 1 # integer},"mime_type": "image/webp","sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"}}]}
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.
{"contacts": [ {"profile": {"name": "Kerry Fisher"},"wa_id": "16315551234"} ],"messages":[{"context":{"from":"16315558011","id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"},"from":"16315551234","id":"gBGGFlA5FpafAgkOuJbRq54qwbM","text":{"body":"Yes, count me in!"},"timestamp":"1521499915","type":"text"}]}
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.
{"messages": [{"from": "16506448470","group_id": "16315558032-1530825318","id": "ACELFjFVWAMqFTCCUxgDM3N5cy0xNjMxNTU1ODAzMi0xNTMwODI1MzE4QGcudXMtMTUzMDgyNTU4NzI5OS1hZGQtMBGGFlBkSEcP","system": {"body": "+1 (650) 387-5246 added +1 (650) 644-8470","group_id": "16315558032-1530825318","operator": "16503875246","type": "group_user_joined","users": ["16506448470"]},"timestamp": "1530825587","type": "system"}]}
For example, the following system messages were received (1) when an user joined a group and (2) when an administrator added an icon to the group.
Message received: {"messages":[{"from":"12345678901","group_id":"16315558011-1521728362","id":"gBEGkYiEB1VXAglK1ZEqA1YKPrU","system":{"body":"+1 (234) 567-8901 was added"},"timestamp":"1521739514","type":"system"}]}Message received: {"messages":[{"from":"16315558011","group_id":"16315558011-1521728362","id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf","system":{"body":"+1 (631) 555-8011 changed this group's icon"},"timestamp":"1521745780","type":"system"}]}
Positus follows exactly the same API standards Facebook/WhatsApp. The complete and updated documentation can be found n the link below:
