Substituições de webhook

Apenas na API de Nuvem.

Webhooks de mensagens são enviados à URL de retorno de chamada definida em seu app, mas é possível substituir isso configurando uma URL de retorno de chamada alternativa em sua conta do WhatsApp Business (WABA) ou número de telefone comercial.

Quando um webhook de mensagens é acionado, primeiro verificaremos se o número de telefone comercial associado à mensagem tem uma URL de retorno de chamada alternativa. Se tiver, enviaremos o webhook à URL de retorno de chamada alternativa. Se não houver, verificaremos se a WABA associada ao número de telefone tem uma URL de retorno de chamada alternativa e enviaremos para lá. Se a WABA também não tiver alternativa, faremos o fallback para a URL de retorno de chamada do app.

Requisitos

Antes de configurar uma URL de retorno de chamada alternativa, verifique se o seu app está inscrito nos webhooks da WABA e verifique se o seu ponto de extremidade de retorno de chamada alternativa pode receber e processar webhooks de mensagens corretamente.

Definir retorno de chamada alternativa da WABA

Use o ponto de extremidade POST /<WABA_ID>/subscribed_apps para definir uma URL de retorno de chamada alternativa em uma WABA.

Sintaxe da solicitação

POST /<WABA_ID>/subscribed_apps

Corpo da publicação

{
  "override_callback_uri":"<WABA_ALT_CALLBACK_URL>",
  "verify_token":"<WABA_ALT_CALLBACK_URL_TOKEN>"
}

Parâmetros do corpo

Resposta

Caso a solicitação seja bem-sucedida:

{
  "success": true
}

Exemplo de solicitação

curl -X POST \
'https://graph.facebook.com/v19.0/102290129340398/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...' \
-H 'Content-Type: application/json' \
-d '
{
  "override_callback_uri":"https://my-waba-alternate-callback.com/webhook",
  "verify_token":"myvoiceismypassport?"
}'

Exemplo de resposta

{
  "success": true
}

Obter retorno de chamada alternativa da WABA

Use o ponto de extremidade GET /<WABA_ID>/subscribed_apps para obter uma lista de todos os apps inscritos em webhooks na WABA. A resposta deve incluir a propriedade e o valor override_callback_uri.

Exemplo de resposta

{
  "data" : [
    {
      "whatsapp_business_api_data" : {
        "id" : "670843887433847",
        "link" : "https://www.facebook.com/games/?app_id=67084...",
        "name" : "Lucky Shrub"
      },
      "override_callback_uri" : "https://my-waba-alternate-callback.com/webhook"
    }
  ]
}

Excluir retorno de chamada alternativa da WABA

Use o ponto de extremidade POST /<WABA_ID>/subscribed_apps para inscrever seu app para webhooks na WABA, como você faria normalmente (ou seja, sem quaisquer parâmetros de publicação no corpo). Essa ação removerá a URL do ponto de extremidade alternativo da WABA, e os webhooks de mensagens da WABA voltarão a ser enviados para a URL de retorno de chamada definida no Painel de Apps.

Definir retorno de chamada alternativa de número de telefone

Use o ponto de extremidade POST /<BUSINESS_PHONE_NUMBER_ID> para definir uma URL de retorno de chamada alternativa no número de telefone comercial.

Sintaxe da solicitação

POST /<BUSINESS_PHONE_NUMBER_ID>

Corpo da publicação

{
  "webhook_configuration": {
    "override_callback_uri": "<PHONE_ALT_CALLBACK_URL>",
    "verify_token": "<PHONE_ALT_CALLBACK_URL_TOKEN>"
  }
}

Parâmetros do corpo

Resposta

Caso a solicitação seja bem-sucedida:

{
  "success": true
}

Exemplo de solicitação

curl 'https://graph.facebook.com/v19.0/106540352242922' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "webhook_configuration": {
    "override_callback_uri": "https://my-phone-alternate-callback.com/webhook",
    "verify_token": "myvoiceismypassport?"
  }
}'

Exemplo de resposta

{
  "success": true
}

Obter retorno de chamada alternativa de número de telefone

Use o ponto de extremidade GET /<BUSINESS_PHONE_NUMBER_ID> e solicite o campo webhook_configuration para verificar se o número de telefone comercial tem uma URL de retorno de chamada alternativa.

Sintaxe da solicitação

GET /<BUSINESS_PHONE_NUMBER_ID>
  ?fields=webhook_configuration

Resposta

Caso a solicitação seja bem-sucedida:

{
  "webhook_configuration": {
    "phone_number": "<PHONE_ALT_CALLBACK_URL>",
    "whatsapp_business_account": "<WABA_ALT_CALLBACK_URL>",
    "application": "<APP_CALLBACK_URL>"
  },
  "id": "106540352242922"
}

Observe que whatsapp_business_account só será incluído se a WABA associada ao número de telefone comercial também tiver uma URL de retorno de chamada alternativa definida.

Exemplo de solicitação

curl 'https://graph.facebook.com/v17.0/106540352242922?fields=webhook_configuration' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

{
  "webhook_configuration": {
    "phone_number": "https://my-phone-alternate-callback.com/webhook",
    "whatsapp_business_account": "https://my-waba-alternate-callback.com/webhook",
    "application": "https://my-production-callback.com/webhook"
  },
  "id": "106540352242922"
}

Excluir retorno de chamada alternativa de número de telefone

Para excluir a URL de retorno de chamada alternativa de um número de telefone comercial, use o ponto de extremidade POST /<BUSINESS_PHONE_NUMBER_ID> com o conjunto de propriedades override_callback_uri para uma string vazia:

{
  "webhook_configuration": {
    "override_callback_uri": "",
  }
}