Retornos de chamada do Status do WhatsApp
Quando você envia uma mensagem pelo WhatsApp usando a Messages API do Vonage, a Vonage entrega callbacks de status para a URL do webhook que você configurou sempre que o status de uma mensagem mudar — por exemplo, quando for enviada, entregue ou lida.
A Vonage recebe atualizações de status da Meta (provedora subjacente do WhatsApp) e as converte em um formato consistente de resposta antes de encaminhá-las para o seu aplicativo. Isso significa que a carga útil que o seu webhook recebe pode diferir da carga útil bruta do webhook da Meta.
Para obter uma visão geral dos callbacks de status em todos os canais, consulte Callbacks de status da Messages API.
Retornos de chamada de status de mensagens
A Vonage envia uma chamada de retorno de status para a URL do seu webhook sempre que uma mensagem do WhatsApp passa para um novo estado. São suportados os seguintes status:
| Status | Descrição |
|---|---|
submitted |
A Vonage recebeu a mensagem e a encaminhou para o WhatsApp. |
delivered |
A mensagem foi entregue no dispositivo do destinatário. |
read |
O destinatário abriu a mensagem (é necessário que os confirmadores de leitura estejam ativados). |
rejected |
A mensagem foi rejeitada pela Vonage ou pelo WhatsApp. Uma error O objeto está incluído na carga útil. |
undeliverable |
A Vonage não conseguiu se conectar ao WhatsApp para enviar a mensagem. |
Carga útil da chamada de retorno de status
O exemplo a seguir mostra o conjunto completo de campos que podem aparecer em uma resposta de status do WhatsApp. Nem todos os campos estão presentes em todas as respostas — por exemplo, error está incluído apenas para rejected ou undeliverable status, workflow só é incluída quando a mensagem foi enviada como parte de um fluxo de trabalho, e profile / whatsapp.recipient são incluídos apenas quando estiverem disponíveis no WhatsApp:
{
"to": "447700900001",
"from": "447700900001",
"channel": "whatsapp",
"status": "submitted",
"usage": {
"currency": "EUR",
"price": "0"
},
"profile": {
"name": "Jane Smith",
"username": "janesmith123"
},
"whatsapp": {
"recipient": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
},
"waba_id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"pricing": {
"type": "regular",
"pricing_model": "CBP",
"category": "service"
},
"conversation": {
"id": "1234567890",
"origin": {
"type": "marketing"
}
}
},
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"timestamp": "2025-02-03T12:14:25Z",
"error": {
"type": "https://developer.vonage.com/api-errors/messages#1000",
"title": "1000",
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
},
"client_ref": "abc123",
"workflow": {
"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
"items_number": "1",
"items_total": "2"
}
}
Para obter uma lista completa dos campos de status, consulte o Campos de retorno de chamada de status seção da referência da Messages API.
Callbacks de erro
Quando uma mensagem é rejeitada ou não pode ser entregue, o callback inclui um error objeto:
{
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"status": "rejected",
"channel": "whatsapp",
"error": {
"type": "https://developer.vonage.com/api-errors/messages#1000",
"title": 1000,
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
}
Retornos de chamada para mensagens recebidas
Quando um usuário do WhatsApp envia uma mensagem para o seu número do WhatsApp Business, a Vonage encaminha a mensagem para a URL do seu webhook de entrada.
Você deve configurar uma URL de webhook de entrada no seu Painel da API da Vonage ou por meio da API do aplicativo para receber mensagens recebidas.
Conteúdo da mensagem recebida
A seguir, um exemplo de retorno de chamada para uma mensagem de texto recebida:
{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2025-02-03T12:14:25Z",
"profile": {
"name": "Jane Smith",
"username": "janesmith123"
},
"context_status": "available",
"context": {
"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
"message_from": "447700900000"
},
"provider_message": "Message delivered",
"message_type": "text",
"text": "Hello from Vonage!",
"whatsapp": {
"sender": {
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.11815799212886844830",
"wa_id": "447700900000"
},
"referral": {
"body": "Check out our new product offering",
"headline": "New Products!",
"source_id": "212731241638144",
"source_type": "post",
"source_url": "https://fb.me/2ZulEu42P",
"media_type": "image",
"image_url": "https://example.com/image.jpg",
"video_url": "https://example.com/video.mp4",
"thumbnail_url": "https://example.com/thumbnail.jpg",
"ctwa_clid": "1234567890"
}
},
"_self": {
"href": "https://api-eu.vonage.com/v1/messages/aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}
}
Para obter uma lista completa dos campos das mensagens recebidas, consulte o Campos de mensagens recebidas seção da referência da Messages API.
Campos obsoletos
Os seguintes campos estão programados para serem descontinuados:
| Campo | Notas |
|---|---|
whatsapp.conversation |
Será descontinuado na API de webhooks versão 23.0 e posteriores, exceto para conversas no ponto de entrada gratuito. |
pricing.billable |
Será descontinuado em uma versão futura. Use whatsapp.pricing em vez disso. |
usage.price |
Será definido como "0" a partir de 1º de julho de 2025, de acordo com o modelo de precificação por mensagem (PMP). |