Veja a seguir o exemplo de um SMS que você recebeu de um cliente:
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "contacts": [ { "profile": { "name": "<WHATSAPP_USER_NAME>" }, "wa_id": "<WHATSAPP_USER_ID>" } ], "messages": [ { "from": "<WHATSAPP_USER_PHONE_NUMBER>", "id": "<WHATSAPP_MESSAGE_ID>", "timestamp": "<WEBHOOK_SENT_TIMESTAMP>", "text": { "body": "<MESSAGE_BODY_TEXT>" }, "type": "text" } ] }, "field": "messages" } ] } ] }
Veja a seguir o exemplo de uma mensagem de reação recebida de um cliente. Você não receberá este webhook se a mensagem à qual o cliente reagiu tiver mais de 30 dias.
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": PHONE_NUMBER, "phone_number_id": PHONE_NUMBER_ID }, "contacts": [{ "profile": { "name": "NAME" }, "wa_id": PHONE_NUMBER }], "messages": [{ "from": PHONE_NUMBER, "id": "wamid.ID", "timestamp": TIMESTAMP, "reaction": { "message_id": "MESSAGE_ID", "emoji": "EMOJI" }, "type": "reaction" }] }, "field": "messages" }] }] }
Para as reações, o valor timestamp
indica quando o cliente enviou a reação, não quando o webhook foi gerado.
Quando uma mensagem com mídia é recebida, a Plataforma do WhatsApp Business baixa a mídia. Uma notificação é enviada ao seu Webhook quando a mídia é baixada.
A notificação de Webhook contém informações que identificam o objeto de mídia e possibilitam que você o encontre e o recupere. Use os pontos de extremidade de mídia para recuperar a mídia.
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": PHONE_NUMBER, "phone_number_id": PHONE_NUMBER_ID }, "contacts": [{ "profile": { "name": "NAME" }, "wa_id": "WHATSAPP_ID" }], "messages": [{ "from": PHONE_NUMBER, "id": "wamid.ID", "timestamp": TIMESTAMP, "type": "image", "image": { "caption": "CAPTION", "mime_type": "image/jpeg", "sha256": "IMAGE_HASH", "id": "ID" } }] }, "field": "messages" }] }] }
Quando receber uma figurinha, você verá esta notificação:
{ "object": "whatsapp_business_account", "entry": [ { "id": "ID", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": "PHONE_NUMBER_ID" }, "contacts": [ { "profile": { "name": "NAME" }, "wa_id": "ID" } ], "messages": [ { "from": "SENDER_PHONE_NUMBER", "id": "wamid.ID", "timestamp": "TIMESTAMP", "type": "sticker", "sticker": { "mime_type": "image/webp", "sha256": "HASH", "id": "ID" } } ] }, "field": "messages" } ] } ] }
É possível receber uma notificação de retorno de chamada de mensagem desconhecida. Por exemplo, um cliente poderia enviar uma mensagem não compatível, como uma mensagem temporária. Nesse caso, avisaríamos a ele que esse tipo de mensagem não é aceito.
Veja a seguir o exemplo de uma mensagem não compatível que você recebeu de um cliente.
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": "PHONE_NUMBER_ID" }, "contacts": [{ "profile": { "name": "NAME" }, "wa_id": "WHATSAPP_ID" }], "messages": [{ "from": "PHONE_NUMBER", "id": "wamid.ID", "timestamp": "TIMESTAMP", "errors": [ { "code": 131051, "details": "Message type is not currently supported", "title": "Unsupported message type" }], "type": "unknown" }] } "field": "messages" }], }] }
Veja a seguir o exemplo de uma mensagem de localização que você recebeu de um cliente:
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": "PHONE_NUMBER_ID" }, "contacts": [{ "profile": { "name": "NAME" }, "wa_id": "WHATSAPP_ID" }], "messages": [{ "from": "PHONE_NUMBER", "id": "wamid.ID", "timestamp": "TIMESTAMP", "location": { "latitude": LOCATION_LATITUDE, "longitude": LOCATION_LONGITUDE, "name": LOCATION_NAME, "address": LOCATION_ADDRESS, } }] }, "field": "messages" }] }] }
Veja a seguir o exemplo de uma mensagem de contato que você recebeu de um cliente:
{ "object":"whatsapp_business_account", "entry":[{ "id":"WHATSAPP_BUSINESS_ACCOUNT_ID", "changes":[{ "value":{ "messaging_product":"whatsapp", "metadata": { "display_phone_number":"PHONE_NUMBER", "phone_number_id":"PHONE_NUMBER_ID" }, "contacts": [{ "profile":{ "name":"NAME" }, "wa_id":"WHATSAPP_ID" }], "messages":[{ "from":"PHONE_NUMBER", "id":"wamid.ID", "timestamp":"TIMESTAMP", "contacts":[{ "addresses":[{ "city":"CONTACT_CITY", "country":"CONTACT_COUNTRY", "country_code":"CONTACT_COUNTRY_CODE", "state":"CONTACT_STATE", "street":"CONTACT_STREET", "type":"HOME or WORK", "zip":"CONTACT_ZIP" }], "birthday":"CONTACT_BIRTHDAY", "emails":[{ "email":"CONTACT_EMAIL", "type":"WORK or HOME" }], "name":{ "formatted_name":"CONTACT_FORMATTED_NAME", "first_name":"CONTACT_FIRST_NAME", "last_name":"CONTACT_LAST_NAME", "middle_name":"CONTACT_MIDDLE_NAME", "suffix":"CONTACT_SUFFIX", "prefix":"CONTACT_PREFIX" }, "org":{ "company":"CONTACT_ORG_COMPANY", "department":"CONTACT_ORG_DEPARTMENT", "title":"CONTACT_ORG_TITLE" }, "phones":[{ "phone":"CONTACT_PHONE", "wa_id":"CONTACT_WA_ID", "type":"HOME or WORK>" }], "urls":[{ "url":"CONTACT_URL", "type":"HOME or WORK" }] }] }] }, "field":"messages" }] }] }
Quando o cliente clica em um botão de resposta rápida em um modelo de mensagem interativa, a resposta é enviada. Veja abaixo o exemplo de um formato de retorno de chamada.
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": PHONE_NUMBER, "phone_number_id": PHONE_NUMBER_ID }, "contacts": [{ "profile": { "name": "NAME" }, "wa_id": "WHATSAPP_ID" }], "messages": [{ "context": { "from": PHONE_NUMBER, "id": "wamid.ID" }, "from": "16315551234", "id": "wamid.ID", "timestamp": TIMESTAMP, "type": "button", "button": { "text": "No", "payload": "No-Button-Payload" } }] }, "field": "messages" }] }] }
A notificação de webhook a seguir é recebida quando o usuário clica em um item de uma mensagem de lista enviada por você:
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": "PHONE_NUMBER_ID", }, "contacts": [ { "profile": { "name": "NAME" }, "wa_id": "PHONE_NUMBER_ID" } ], "messages": [ { "from": PHONE_NUMBER_ID, "id": "wamid.ID", "timestamp": TIMESTAMP, "interactive": { "list_reply": { "id": "list_reply_id", "title": "list_reply_title", "description": "list_reply_description" }, "type": "list_reply" }, "type": "interactive" } ] }, "field": "messages" } ] } ] }
A notificação de webhook a seguir é recebida quando o usuário clica em um botão Responder enviado por você:
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": PHONE_NUMBER_ID, }, "contacts": [ { "profile": { "name": "NAME" }, "wa_id": "PHONE_NUMBER_ID" } ], "messages": [ { "from": PHONE_NUMBER_ID, "id": "wamid.ID", "timestamp": TIMESTAMP, "interactive": { "button_reply": { "id": "unique-button-identifier-here", "title": "button-text", }, "type": "button_reply" }, "type": "interactive" } ] }, "field": "messages" } ] } ] }
Você obtém o webhook a seguir quando uma conversa é iniciada depois que o usuário clica em um anúncio com uma chamada para ação Clique para o WhatsApp:
{ "object": "whatsapp_business_account", "entry": [ { "id": "ID", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": "PHONE_NUMBER_ID" }, "contacts": [ { "profile": { "name": "NAME" }, "wa_id": "ID" } ], "messages": [ { "referral": { "source_url": "AD_OR_POST_FB_URL", "source_id": "ADID", "source_type": "ad or post", "headline": "AD_TITLE", "body": "AD_DESCRIPTION", "media_type": "image or video", "image_url": "RAW_IMAGE_URL", "video_url": "RAW_VIDEO_URL", "thumbnail_url": "RAW_THUMBNAIL_URL", "ctwa_clid": "CTWA_CLID" }, "from": "SENDER_PHONE_NUMBERID", "id": "wamid.ID", "timestamp": "TIMESTAMP", "type": "text", "text": { "body": "BODY" } } ] }, "field": "messages" } ] } ] }
Uma mensagem de consulta de produtos é recebida quando o cliente solicita mais informações sobre um item. Isso acontece quando:
A notificação de webhook para uma mensagem de consulta de produto tem a seguinte aparência:
{ "object": "whatsapp_business_account", "entry": [ { "id": "ID", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE_NUMBER", "phone_number_id": "PHONE_NUMBER_ID", }, "contacts": [ { "profile": { "name": "NAME" }, "wa_id": "PHONE_NUMBER_ID" } ], "messages": [ { "from": "PHONE_NUMBER", "id": "wamid.ID", "text": { "body": "MESSAGE_TEXT" }, "context": { "from": "PHONE_NUMBER", "id": "wamid.ID", "referred_product": { "catalog_id": "CATALOG_ID", "product_retailer_id": "PRODUCT_ID" } }, "timestamp": "TIMESTAMP", "type": "text" } ] }, "field": "messages" } ] } ] }
A notificação de webhook para um pedido realizado tem a seguinte aparência:
{ "object": "whatsapp_business_account", "entry": [ { "id": "8856996819413533", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "16505553333", "phone_number_id": "phone-number-id", }, "contacts": [ { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" } ], "messages": [ { "from": "16315551234", "id": "wamid.ABGGFlCGg0cvAgo6cHbBhfK5760V", "order": { "catalog_id": "the-catalog_id", "product_items": [ { "product_retailer_id":"the-product-SKU-identifier", "quantity":"number-of-item", "item_price":"unitary-price-of-item", "currency":"price-currency" }, ... ], "text":"text-message-sent-along-with-the-order" }, "context": { "from": "16315551234", "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o" }, "timestamp": "1603069091", "type": "order" } ] }, "field": "messages" } ] } ] }
Quando o usuário altera o número de telefone no WhatsApp, você recebe uma notificação de mensagem do sistema:
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": PHONE_NUMBER, "phone_number_id": PHONE_NUMBER_ID }, "messages": [{ "from": PHONE_NUMBER, "id": "wamid.ID", "system": { "body": "NAME changed from PHONE_NUMBER to PHONE_NUMBER", "new_wa_id": NEW_PHONE_NUMBER, "type": "user_changed_number" }, "timestamp": TIMESTAMP, "type": "system" }] }, "field": "messages" }] }] }
A Plataforma do WhatsApp Business envia notificações para informar o status das mensagens trocadas entre você e os usuários. Quando a mensagem é enviada com sucesso, você recebe uma notificação confirmando que ela foi enviada, entregue e lida. A ordem dessas notificações no seu app pode não refletir o momento real do status da mensagem. Veja o registro de data e hora para determinar o momento, se for necessário.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID>", "status": "sent", "timestamp": "<WEBHOOK_SENT_TIMESTAMP>", "recipient_id": "<WHATSAPP_USER_ID>", "conversation": { "id": "<CONVERSATION_ID>", "expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP>", "origin": { "type": "<CONVERSATION_CATEGORY>" } }, "pricing": { "billable": <IS_BILLABLE?>, "pricing_model": "CBP", "category": "<CONVERSATION_CATEGORY>" } } ] }, "field": "messages" } ] } ] }
Para conversas com ponto de entrada gratuito, origin.type
e pricing.category
são definidos como referral_conversion
. Além disso, pricing.billable
é definido como false
.
A notificação a seguir será recebida quando a mensagem da empresa for entregue como parte de uma conversa iniciada pelo usuário (caso a interação não tenha sido originada em um ponto de entrada gratuito):
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID>", "status": "sent", "timestamp": "<WEBHOOK_SENT_TIMESTAMP>", "recipient_id": "<WHATSAPP_USER_ID>", "conversation": { "id": "<CONVERSATION_ID>", "origin": { "type": "<CONVERSATION_CATEGORY>" } }, "pricing": { "billable": <IS_BILLABLE?>, "pricing_model": "CBP", "category": "<CONVERSATION_CATEGORY>" } } ] }, "field": "messages" } ] } ] }
Para conversas com ponto de entrada gratuito, origin.type
e pricing.category
são definidos como referral_conversion
. Além disso, pricing.billable
é definido como false
.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID>", "status": "read", "timestamp": "<WEBHOOK_SENT_TIMESTAMP>", "recipient_id": "<WHATSAPP_USER_ID>" } ] }, "field": "messages" } ] } ] }
No momento, a API de Nuvem não é compatível com atualizações de status de webhook para mensagens excluídas. Se um usuário excluir uma mensagem, você receberá um webhook com um código de erro para um tipo de mensagem não compatível:
{ "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": PHONE_NUMBER, "phone_number_id": PHONE_NUMBER }, "contacts": [{ "profile": { "name": "NAME" }, "wa_id": PHONE_NUMBER }], "messages": [{ "from": PHONE_NUMBER, "id": "wamid.ID", "timestamp": TIMESTAMP, "errors": [{ "code": 131051, "details": "Message type is not currently supported", "title": "Unsupported message type" }], "type": "unsupported" }] }, "field": "messages" }] }] }
Há outros comportamentos do usuário que podem acionar essa mesma mensagem de erro.
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID>", "status": "failed", "timestamp": "<WEBHOOK_SENT_TIMESTAMP>", "recipient_id": "<WHATSAPP_USER_ID>", "errors": [ { "code": <ERROR_CODE>, "title": "<ERROR_TITLE>", "message": "<ERROR_MESSAGE>", "error_data": { "details": "<ERROR_DETAILS>" }, "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/" } ] } ] }, "field": "messages" } ] } ] }