Webhook
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 que 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.
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.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" } ] }
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
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 |
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.{
"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": "[email protected]",
"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"
}
]
}
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.{
"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"
}
}]
}
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.{
"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"
}]
}
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"}]}
A Positus segue os padrões de API exatamente igual ao padrão oficial do Facebook / WhatsApp. A documentação completa e atualizada pode ser encontrada no link abaixo: