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.
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.
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.
O objeto errors
O objeto errors contém os seguintes parâmetros:
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.
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"
}]
}
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.
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.
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 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:
