> For the complete documentation index, see [llms.txt](https://docs.pt.posit.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pt.posit.us/integracao/webhook.md).
# Webhook
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.
{% hint style="info" %}
É 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.
{% endhint %}
## 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 |
{% hint style="info" %}
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`.
{% endhint %}
### 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](https://developers.facebook.com/docs/whatsapp/api/errors/) para obter mais informações.
**Exemplo**
```
POST / { "errors": [ { "code": , "title": "", "details": "", "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 |
### Notificações de mensagens de entrada
Você recebe uma notificação quando sua empresa recebe uma mensagem. A [seção do objeto `messages`](https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound#messages_object) 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](https://developers.facebook.com/docs/whatsapp/api/media) 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 com 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`](https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound#systemobj) 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
{% hint style="info" %}
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:
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pt.posit.us/integracao/webhook.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.