Quando o cliente enviar uma mensagem a você, o cliente da API do WhatsApp Business enviará uma notificação de solicitação HTTP POST à URL do Webhook com os detalhes que estão descritos neste manual.
Webhooks são retornos de chamada de HTTP definidos pelo usuário e são acionados por eventos específicos. Sempre que ocorrer um evento de acionamento, o cliente da API do WhatsApp Business verá o evento, coletará os dados e imediatamente enviará uma notificação (solicitação HTTP) ao URL do WhatsApp especificado nas configurações do aplicativo, atualizando o status das mensagens enviadas ou indicando quando você receber uma mensagem.
É importante que seu Webhook retorne uma resposta HTTPS 200 OK às notificações. Caso contrário, o cliente da API do WhatsApp Business considerará essa notificação uma falha e tentará novamente após um atraso.
Definir configurações de notificações #
Webhooks: forneça o URL para seu Webhook. OBRIGATÓRIO quando você estiver usando Webhooks. Se a URL do Webhook não estiver definida, os retornos de chamada serão removidos.
| Nome | Conteúdo do objeto |
| messages | Notificações de mensagens de entrada |
| statuses | Atualizações de status das mensagens |
| errors | Erros sérios fora da banda |
Sempre que possível, os nomes serão mantidos constantes nas funções. (Por exemplo, todos os registros de data e hora são denominados timestamp).
Formato do Webhook de notificações #
Todos os campos possíveis do Webhook de notificações são mostrados abaixo.
Exemplo
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" } ] }Erros de notificações #
Quando houver erros fora da banda que ocorrerem na operação normal do aplicativo, a matriz errors fornecerá uma descrição do erro. Esse tipo de erro pode ser provocado por erros de conectividade de rede temporários, credenciais inválidas, controladores de gerenciamento com status indisponível e assim por diante. Se você receber um erro, consulte Mensagens de erro e status para obter mais informações.
Exemplo
POST / { "errors": [ { "code": <error-code>, "title": "<error-title>", "details": "<error-description>", "href": "location for error detail" }, { ... } ] }O objeto errors contém os seguintes parâmetros:
| Nome do campo | Descrição | Tipo |
| code | Código de erro | Numérico |
| title | Título do erro | Cadeia de caracteres |
| details | Opcional. Detalhes do erro fornecidos, se disponíveis/aplicáveis | Cadeia de caracteres |
| href | Opcional. Detalhes da localização do erro. | Cadeia de caracteres |
Notificações de mensagens de entrada #
Você recebe uma notificação quando sua empresa recebe uma mensagem. A seção do objeto messages abaixo apresenta todas as informações que podem ser recebidas sobre uma mensagem de entrada.
Exemplo: Mensagem recebida Text #
{ "contacts": [ { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" } ], "messages":[{ "from": "16315551234", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "timestamp": "1518694235", "text": { "body": "Hello this is an answer" }, "type": "text" }]} Exemplo: Mensagem de localização estática recebida #
{ "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" }]} Exemplo: Mensagem com contatos recebida #
{ "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" } ]}Notificações de mensagens de mídia de entrada #
Quando a mensagem com mídia é recebida, o cliente da API do WhatsApp Business baixa a mídia. Uma notificação é enviada ao seu Webhook quando a mídia é baixada. Essa mensagem contém informações que identificam o objeto de mídia e possibilitam que você encontre e recupere o objeto. Use o ponto de extremidade de mídia com o id da mídia para recuperá-la.
Exemplo: Mensagem com imagem recebida #
{ "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" }]} Exemplo: Mensagem com documento recebida #
{ "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"} }]}Exemplo: Mensagem de voz recebida #
{ "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"} }]}Exemplo: Mensagem com figurinha recebida #
{ "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" } }]}Respostas de entrada a mensagens enviadas #
Os usuários podem responder a uma mensagem específica no WhatsApp. Para que a empresa entenda o contexto da resposta a uma mensagem, incluímos o objeto context. Esse objeto context fornece o id da mensagem à qual o cliente respondeu e o ID do WhatsApp do remetente da mensagem original.
Exemplo: Cliente respondeu à sua mensagem #
{ "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" }]}Mensagens de entrada do sistema #
As mensagens de sistema são geradas quando algum evento acontece, por exemplo, um usuário adicionou/removeu outro usuário ou saiu de um grupo, etc. Veja a seção do objeto system a seguir para mais informações.
{ "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" } ]}Por exemplo, as mensagens do sistema a seguir foram recebidas (1) quando um usuário entrou em um grupo e (2) quando um administrador adicionou um ícone ao grupo.
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"}]}Documentação Oficial WhatsApp Business API #
A Positus segue exatamente o padrão oficial de API do Facebook / WhatsApp. A documentação completa e atualizada pode ser encontrada no link abaixo:
