Webhooks da Meta

Plataforma do WhatsApp Business

Webhooks for WhatsApp Business Accounts

Receba notificações em tempo real quando houver alterações na sua conta do WhatsApp Business (WABA, pelas iniciais em inglês) fazendo uma assinatura no nível da conta. Para configurar os Webhooks em contas do WhatsApp Business:

  1. Configure o ponto de extremidade e os Webhooks. Essas são as mesmas etapas usadas para configurar os Webhooks para Páginas do Facebook.
  2. Cadastre o aplicativo na sua conta do WhatsApp Business. É necessário cadastrar um aplicativo que seja de propriedade da sua empresa. Os aplicativos compartilhados com a sua empresa não poderão receber notificações de webhooks.
  3. Verifique se o aplicativo concluiu a análise do aplicativo e solicitou a permissão whatsapp_business_management.

GET, POST, and DELETE calls to /{whats-app-business-account-id}/subscribed_apps are now subject to Business Use Case Rate Limits.

Set up Your Endpoint and Webhooks

Follow our Webhooks Getting Started guide to create your endpoint and configure your webhook endpoint. When you configure your endpoint, make sure to choose WhatsApp Business Account and subscribe to individual WhatsApp Business Account (WABA) fields.

Available Subscription Fields

Campos de assinatura disponíveis

Nome do campo Descrição

account_review_update

Uma notificação é enviada quando a análise de uma conta do WhatsApp Business é concluída.

account_update

Uma notificação é enviada quando uma alteração é implementada na sua conta do WhatsApp Business. Essa alteração pode incluir uma atualização do número de telefone, uma violação das políticas, o banimento de uma conta do WhatsApp Business, entre outros.

business_capability_update

Uma notificação é enviada quando um recurso é atualizado. Isso pode incluir uma alteração no número máximo de telefones que uma WABA pode ter ou o número de conversas por telefone.

message_template_status_update

Uma notificação é enviada quando o modelo de mensagem é aprovado, rejeitado ou desativado.

messages

Uma notificação é enviada quando a sua empresa recebe uma mensagem de um cliente, quando você envia uma mensagem a um cliente, quando a mensagem é entregue ao cliente e quando a mensagem é lida.

phone_number_name_update

Uma notificação é enviada quando o nome associado a um número de telefone é aprovado ou rejeitado.

phone_number_quality_update

Uma notificação é enviada quando há uma atualização do status de qualidade de um número de telefone.

security

Você receberá uma notificação nos seguintes casos:

  • Ao solicitar a desativação do código de confirmação em duas etapas
  • Quando o código de confirmação em duas etapas é desativado
  • Quando o código de confirmação em duas etapas é atualizado

    • Acesse a referência de Webhooks sobre contas do WhatsApp Business para mais informações sobre cada campo de carga e a referência de Webhooks sobre a API de Nuvem do WhatsApp para mais informações sobre os diferentes tipos de notificações messages que você pode receber.

    Subscribe Your App

    You need to subscribe your app to webhooks on a given WABA. We only send notifications if your webhooks-configured app is subscribed to webhooks on a given WABA, and only if the app has permission to edit that WABA.

    Create a Subscription

    Request

    To subscribe your app to webhooks on a WABA, send a POST request to the WABA > Subscribed Apps endpoint.

    curl -X POST 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

    Response

    Upon success:

    {
  "success": "true"
}

    Get Subscribed Apps

    To get a list of apps subscribed to webhooks on a WABA, send a GET request to the WABA > Subscribed Apps endpoint.

    Request

    curl 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

    Response

    A successful response will list the subscribed apps:

    {
  "data": [
    {
      "whatsapp_business_api_data": {
        "link": "<APP_1_URL>",
        "name": "<APP_1_NAME>",
        "id": "<APP_1_ID>"
      }
    },
    {
      "whatsapp_business_api_data": {
        "link": "<APP_2_URL>",
        "name": "<APP_2_NAME>",
        "id": "<APP_2_ID>"
      }
    },
    ...
  ]
}

    Delete a subscription

    To unsubscribe your app from webhooks on a WABA, send a DELETE request to the subscribed_apps endpoint.

    Request

    curl -X DELETE 'https://graph.facebook.com/<AP_VERSION>/<WHATSAPP_BUSINESS_ACCOUNT_ID>/subscribed_apps' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

    Response

    A successful response will read:

    {
  "success": "true"
}

    Subscribe with Graph API Explorer

    If you don't want to subscribe your app with direct API calls, you can easily do it with Graph API Explorer.

    Replace the me?fields=id,name query with <WHATSAPP_BUSINESS_ACCT_ID>/subscribed_apps. It will subscribe the app you use to send the POST request in Graph Explorer.

    Your app must have permission to edit the WhatsApp business account in order to successfully subscribe.

    Example Webhook payload:

    [
  {
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "0",
        "time": 1602782939,
        "changes": [
          {
            "field": "phone_number_name_update",
            "value": {
              "display_phone_number": "16505551111",
              "decision": "APPROVED",
              "requested_verified_name": "WhatsApp",
              "rejection_reason": null
            }
          }
        ]
      }
    ]
  }
]

    Enabling mTLS on a WhatsApp Business Account

    Enabling and disabling mTLS is not supported at the Business Phone Number or WABA level. It is only available for object Webhook subscriptions.

    You can enable Mutual TLS (mTLS) on the webhooks you receive from WhatsApp for added security.

    You must verify the callback URL before enabling mTLS. If you have more than one application accessing WhatsApp Cloud API, you will need to enable mTLS for each application.

    mTLS toggle for WhatsApp Business accounts