Webhooks

As contas do WhatsApp Business e os respectivos ativos são objetos no gráfico social do Facebook. Quando um evento é disparado para um desses objetos, o Facebook envia uma notificação para a URL de webhook especificada no painel do app do Facebook.

No caso de cadastros incorporados, você pode usar os webhooks para receber notificações sobre alterações a WABAs, números de telefone, modelos de mensagem e mensagens enviadas aos seus telefones.

Você precisa assinar individualmente cada WABA para a qual deseja receber Webhooks. Depois de obter a identificação da WABA, assine seu app com a identificação para começar a receber Webhooks.

Confira Webhooks para contas do WhatsApp Business para saber mais sobre como assinar os Webhooks.

Assinar uma conta do WhatsApp Business

Primeiro, configure o produto Webhooks para seu app:

1. Carregue o app no Painel de Apps e adicione o produto Webhooks, caso ainda não tenha feito isso.
2. No menu à esquerda, clique no produto Webhooks.
3. Selecione WhatsApp Business Account no menu suspenso e clique em Subscribe to this object.
4. Adicione a URL de retorno de chamada e o token de verificação. Depois, verifique e salve as alterações.

Para saber mais, consulte Como configurar o produto Webhooks.

Depois de configurar os webhooks no painel, envie uma solicitação POST ao ponto de extremidade subscribed_apps da conta do WhatsApp Business para a qual você deseja receber webhooks.

Insira o token de acesso do usuário do sistema no cabeçalho da solicitação precedido por Authorization: Bearer. Consulte Instalar apps e gerar tokens para obter ajudar na geração do token de acesso de usuário do sistema.

Sintaxe da solicitação

POST https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Exemplo de solicitação

curl -X POST \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Exemplo de resposta

{
   "success" : true
}

Agora, o app (identificado pelo token de acesso do usuário do sistema) recebe notificações de webhooks descrevendo as alterações à conta do WhatsApp Business.

Repita esse processo nas outras WABAs sobre as quais você quer receber notificações de webhooks. Se você assinar seu app para webhooks de várias WABAs, todas as notificações serão enviadas à URL de retorno de chamada especificada no painel do produto Webhooks do Painel de Apps.

Se você quiser usar uma URL de retorno de chamada específica para cada WABA, será necessário criar apps separados. Além disso, você precisa realizar a consulta acima em cada WABA usando o token de acesso do usuário de cada app. Caso você queira usar um único app, é possível substituir a URL de retorno de chamada na assinatura de webhooks de cada WABA. Consulte Como substituir a URL de retorno de chamada.

Obter todas as assinaturas de uma WABA

Para obter a lista dos apps inscritos em webhooks de uma WABA, envie uma solicitação GET ao ponto de extremidade subscribed_apps da WABA:

Sintaxe da solicitação

GET https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Uma resposta bem-sucedida inclui uma matriz de apps que assinaram a WABA com as propriedades link, nome e ID de cada um.

Exemplo de solicitação

curl \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Exemplo de resposta

{
  "data" : [
    {
      "whatsapp_business_api_data" : {
        "id" : "67084...",
        "link" : "https://www.facebook.com/games/?app_id=67084...",
        "name" : "Jaspers Market"
      }
    },
    {
      "whatsapp_business_api_data" : {
        "id" : "52565...",
        "link" : "https://www.facebook.com/games/?app_id=52565...",
        "name" : "Jaspers Fresh Finds"
      }
    }
  ]
}

Cancelar a assinatura da WABA

Para cancelar a assinatura do app dos webhooks em uma conta do WhatsApp Business, envie uma solicitação DELETE ao ponto de extremidade subscribed_apps da WABA.

Sintaxe da solicitação

DELETE https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Exemplo de solicitação

curl -X DELETE \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Exemplo de resposta

{
   "success" : true
}

Substituir a URL de retorno de chamada

Consulte Substituições de webhook.

Configurar notificações

É possível configurar webhooks para receber notificações quando houver alterações nas suas contas assinadas do WhatsApp Business. Veja os tipos de notificação que você pode assinar:

Campos de assinatura disponíveis

Consulte a documentação Webhooks para contas do WhatsApp Business para saber mais.

Formato de webhooks

Você receberá as notificações no seguinte formato geral:

{
  "object": "whatsapp_business_account",
  "entry": [
    { // entry object, containing changes
      "changes": [
        { // changes object, containing value
          "value": {
            // value object
          }
        }
      ]
    }
  ]
}

Veja mais detalhes sobre cada campo:

• object
• entry
• changes
• value

Exemplos

Atualizações de número de telefone

Atualização de nome recebida

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

Atualização de qualidade recebida

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243062,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "16505551111",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

Atualizações da WABA

Número de sandbox atualizado para conta verificada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505551111",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

Conta do WhatsApp Business banida

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "January 31, 2021"
            }
          }
        }
      ]
    }
  ]
}

Análise da conta do WhatsApp Business concluída

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

Atualizações no modelo de mensagem

Aprovado

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "APPROVED",
              "message_template_id": 1234567, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null 
         }
       }
      ]
    }
  ]
}