Assinaturas de notificações do WhatsApp

Os webhooks do sistema são acionados quando ocorre um evento em uma conta WABA ou em um número de telefone. Agora você pode se inscrever nesses webhooks para receber notificações sobre alterações nas configurações da sua conta do WhatsApp Business. Existem muitos tipos de notificação, como atualizações de Account, alterações nos modelos de mensagem, atualizações de números de telefone e quando você receber uma mensagem de um cliente.

Essas notificações podem ser recebidas de duas maneiras:

  • Por meio de Webhooks - receber notificações por meio de uma URL de webhook personalizada
  • Via Slack - receber notificações em um canal específico dentro do seu espaço de trabalho do Slack.

Para criar uma assinatura, você pode enviar uma solicitação para o Criar um endpoint de assinatura da API do Channel Manager.

Criar uma assinatura de notificações do WhatsApp com webhooks

Para receber atualizações por meio de webhook, você deve primeiro criar uma URL de webhook personalizada configurada para aceitar solicitações POST; consulte nosso Webhooks guia, caso não saiba como proceder. Em seguida, você pode enviar uma solicitação ao endpoint de assinaturas com os seguintes parâmetros para criar a assinatura:

{
    "type": "webhook",
    "whatsapp_subscribe_types": "account_alerts,account_update",
    "vonage_subscribe_types": "vonage_number_onboarded",
    "webhook": {
      "url": "https://example.com/webhook"
    }
}

Aqui:

  • url deve conter a URL do seu webhook personalizado.
  • whatsapp_subscribe_types é um parâmetro opcional no qual você pode listar contatos específicos do WhatsApp tipos de notificação que você deseja receber por meio da sua assinatura. Caso isso não esteja incluído, a assinatura abrangerá todos os tipos de assinatura.
  • vonage_subscribe_types é um parâmetro opcional no qual você pode listar números específicos da Vonage tipos de notificação que você deseja receber por meio da sua assinatura. Caso isso não esteja incluído, a assinatura abrangerá todos os tipos de assinatura.

Você pode encontrar um exemplo completo de código no Criar uma assinatura de notificações do WhatsApp com webhooks trecho de código.

Escopo da chave de API para assinaturas

Use seu chave API principal credenciais ao acessar a API de assinaturas.

As chaves de API secundárias também funcionam para criar, listar e excluir assinaturas. No entanto, cada assinatura é armazenada associada à chave de API principal. Isso significa que todas as chaves de API secundárias da mesma Account compartilham o mesmo conjunto de assinaturas:

  • Se uma chave de API secundária criar uma assinatura, outras chaves de API secundárias poderão exibi-la.
  • Qualquer chave de API secundária associada à mesma chave de API principal pode excluí-la.

Os limites de assinatura também são aplicados no nível da chave API principal.

Exemplos de webhooks

Este exemplo mostra uma atualização de status de modelo; conforme indicado no event campo, o modelo foi rejeitado:

{
    "notification_id": "id",
    "timestamp": "2023-02-21T15:34:39Z",
    "channel": "whatsapp",
    "whatsapp": {
        "waba_info": {
            "waba_id": "<WABA_ID>",
            "solution_id": "<WABA_SOLUTION_ID>", // if present
            "api_key": "<WABA_API_KEY>"
        },
        "notification_type": "message_template_status_update",
        "notification_value": {
            "event": "REJECTED",
            "message_template_id": "<TEMPLATE_ID>",
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "<REJECTION_REASON>"
        }
    }
}

Neste exemplo, o webhook indica uma atualização na Account em que um número de telefone foi adicionado:

{
    "notification_id": "id",
    "timestamp": "2023-02-21T15:34:39Z",
    "channel": "whatsapp",
    "whatsapp": {
        "waba_info": {
            "waba_id": "<WABA_ID>",
            "solution_id": "<WABA_SOLUTION_ID>", // if present
            "api_key": "<WABA_API_KEY>"
        },
        "whatsapp_number_info": {
            "phone_number": "<PHONE_NUMBER>",
            "api_key": "<NUMBER_API_KEY>"
        },
        "notification_type": "account_update",
        "notification_value": {
            "phone_number": "<PHONE_NUMBER>",
            "event": "PHONE_NUMBER_ADDED"
        }
    }
}

O notification_value O objeto mostrado nos exemplos de cargas úteis de webhooks é um repasse do value objeto nas cargas úteis do webhook Meta.

Crie uma assinatura de notificações do WhatsApp para o Slack

Para receber notificações pelo Slack, você pode enviar uma solicitação ao subscriptions ponto de extremidade com os seguintes parâmetros:

{
    "type": "slack",
    "whatsapp_subscribe_types": "account_alerts,account_update,message_template_status_update",
    "slack": {
      "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    }
}

Aqui:

  • O url Esse campo deve conter uma URL de webhook de entrada criada para o seu espaço de trabalho do Slack. Consulte o Documentação sobre webhooks do Slack para obter mais informações sobre como configurar essa URL.
  • whatsapp_subscribe_types é um parâmetro opcional no qual você pode listar tipos de notificação que você deseja receber por meio da sua assinatura. Caso isso não esteja incluído, a assinatura abrangerá todos os tipos de assinatura.

Você pode encontrar um exemplo completo de código no Crie uma assinatura de notificações do WhatsApp para o Slack trecho de código.

Exemplo de notificação

Assim que sua assinatura for criada, você começará a receber atualizações no canal do Slack especificado, por exemplo:

An example Slack notification showing a WhatsApp account update

Tipos de notificação

  • Existem muitos valores possíveis para whatsapp_subscribe_types, exibido tanto nas notificações do webhook quanto nas do Slack. Você pode ver a lista completa dos tipos de notificação e suas descrições na Documentação do Meta WhatsApp.
  • Atualmente, há apenas um valor possível para vonage_subscribe_types, que é vonage_number_onboarded.

Listar todas as assinaturas

Para listar todas as suas assinaturas atuais, envie uma solicitação GET para o subscriptions ponto de extremidade; exemplos de código podem ser encontrados no Listar assinaturas de notificações existentes trecho de código.

Excluir uma assinatura

Para excluir uma assinatura, envie uma solicitação DELETE com o ID exclusivo da assinatura que você deseja excluir. Exemplos de código podem ser encontrados no Excluir uma assinatura trecho de código.

Leitura complementar