API de Gerenciamento do WhatsApp Business

Componentes de Webhooks

Os Webhooks têm um campo de matriz de nível superior que indica o que está sendo comunicado. A matriz é formada por objetos JSON com campos detalhados, que são relevantes ao Webhook.

Os webhooks da API de Gerenciamento do WhatsApp Business podem conter os objetos a seguir:

ParâmetroDescrição

object

O objeto que foi assinado.


Para o cadastro incorporado, será sempre whatsapp_business_account.

entry

O objeto com os detalhes da alteração que disparou a chamada de webhooks.

O objeto entry

ParâmetroDescrição

id

Identificação das contas do WhatsApp Business às quais esse webhook pertence.

time

Horário da entrada.

changes

Mudanças que dispararam a chamada de webhooks. Confira o objeto changes.

changes

ParâmetroDescrição (clique na seta da coluna da esquerda para ver os valores compatíveis)

field

Contém o tipo de notificação que você está recebendo no webhook.

Valores compatíveis

  • account_alerts
  • account_review_update
  • account_update
  • business_capability_update
  • message_template_quality_update
  • message_template_status_update
  • phone_number_name_update
  • phone_number_quality_update
  • security
  • template_category_update

value

Contém detalhes das mudanças relacionadas ao field especificado. Confira o objeto value.

value

ParâmetroDescrição (clique na seta da coluna da esquerda para ver os valores compatíveis)

ban_info

Adicionado aos webhooks quando uma conta tiver sido banida. O objeto inclui estas duas propriedades:

  • waba_ban_state com as opções:
    • DISABLE
    • REINSTATE
    • SCHEDULE_FOR_DISABLE
  • waba_ban_date

current_limit

Contém o limite de nível atual da conta.

Valores compatíveis

  • TIER_50
  • TIER_250
  • TIER_1K
  • TIER_10K
  • TIER_100K
  • TIER_UNLIMITED

decision

Usado caso uma decisão sobre as contas ou os números de telefone tenha sido tomada.

Valores compatíveis

  • APPROVED
  • REJECTED

display_phone_number

Inclui o número de telefone de exibição da conta empresarial que disparou a notificação.

event

Será usado quando ocorrer um evento em uma conta específica do WhatsApp Business (WABA, pelas iniciais em inglês). Clique na seta da coluna da esquerda para ver os valores compatíveis.

Atualizações do nome de exibição

  • APPROVED: a análise foi aprovada. Caso a empresa não tenha conseguido baixar o certificado, ela poderá usar o nome de exibição baixando o certificado agora.
  • DEFERRED: a análise foi adiada, e a empresa pode usar o nome de exibição baixando o certificado.
  • REJECTED: a análise foi rejeitada devido ao motivo fornecido. Caso a empresa não tenha conseguido baixar o certificado, ela precisará solicitar novamente a análise do nome de exibição para ter acesso ao certificado. Se a empresa já estiver usando o certificado, a rejeição da análise não afetará a operação. Entretanto, a análise precisa ser aprovada para que a empresa aumente os limites de conta e mensagens.

Atualização da qualidade do modelo de mensagem

Pontuação de qualidade anterior:


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

Nova pontuação de qualidade:


  • GREEN
  • RED
  • UNKNOWN
  • YELLOW

Atualizações de status do modelo de mensagem

  • APPROVED
  • DISABLED
  • IN_APPEAL
  • PENDING
  • REINSTATED
  • REJECTED
  • FLAGGED

Atualizações de número de telefone

  • DOWNGRADE
  • FLAGGED
  • ONBOARDING
  • UNFLAGGED
  • UPGRADE

Atualização de categoria do modelo

Categorias anteriores:


  • MARKETING
  • OTP
  • TRANSACTIONAL

Novas categorias:


  • AUTHENTICATION
  • MARKETING
  • UTILITY

Código de confirmação em duas etapas

  • PIN_CHANGED: o código de confirmação em duas etapas foi atualizado (apenas na API de Nuvem)
  • PIN_RESET_REQUEST: solicitação para desabilitar o código de confirmação em duas etapas
  • PIN_RESET_SUCCESS: o código de confirmação em duas etapas está desabilitado

Atualizações da WABA

  • ACCOUNT_RESTRICTION: usado para informar que uma restrição entrou em vigor quando uma WABA violar as políticas da Plataforma do WhatsApp Business.
  • DISABLED_UPDATE
  • VERIFIED_ACCOUNT

max_daily_conversation_per_phone

Sempre presente quando field=business_capability_update.


Indica o número de modelos de mensagem que você pode enviar com cada número de telefone comercial da sua conta do WhatsApp Business que tenha um nome de exibição aprovado. Consulte Limites de mensagens.

max_phone_numbers_per_business

Inclui o número máximo de números de telefone que podem pertencer a uma empresa.


Quando field=business_capability_update, o webhook terá max_phone_numbers_per_business ou max_phone_numbers_per_waba.

max_phone_numbers_per_waba

Inclui o limite máximo de números de telefone que podem pertencer a uma WABA.


Quando field=business_capability_update, o webhook terá max_phone_numbers_per_business ou max_phone_numbers_per_waba.

reason

Motivo da rejeição do modelo. Valores possíveis:


  • ABUSIVE_CONTENT: conteúdo marcado como abusivo.
  • INCORRECT_CATEGORY: categoria marcada como incorreta. Consulte Criar e gerenciar modelos.
  • INVALID_FORMAT: conteúdo duplicado ou exemplos ausentes.
  • NONE: padrão, definido quando o modelo é aprovado.
  • SCAM: conteúdo marcado como fraude.

rejection_reason

Se uma solicitação tiver sido rejeitada, esse campo exibirá o motivo da rejeição.

requested_verified_name

Esse campo exibe o nome enviado para verificação.

restriction_info

enumeração

Será usado para relatar restrições impostas a uma WABA específica quando essa conta violar as políticas da Plataforma do WhatsApp Business.


Esse campo inclui uma lista de tipos de restrição e as respectivas datas de expiração. Confira os tipos de restrição possíveis:


  • RESTRICTED_ADD_PHONE_NUMBER_ACTION
  • RESTRICTED_BIZ_INITIATED_MESSAGING
  • RESTRICTED_CUSTOMER_INITIATED_MESSAGING

As datas de expiração são fornecidas no formato DateTime.

requester

O número de identificação do usuário que solicitou a desabilitação ou já desabilitou/atualizou o código de confirmação em duas etapas.

Exemplos

Atualização de status do modelo de mensagem

Modelo 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 
         }
       }
      ]
    }
  ]
}

Modelo rejeitado

{
  "object": "whatsapp_business_account"
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "REJECTED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "<REJECTION_REASON>"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ]
}

Modelo com desabilitação agendada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "FLAGGED",
              "message_template_id": TEMPLATE-ID, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null,
              "disable_info": {
                  "disable_date": "DATE",
              }
         }
       }
      ]
    }
  ]
}

Modelo pausado

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10908...",
      "time": 1661885238,
      "changes": [
        {
          "value": {
            "event": "PAUSED",
            "message_template_id": 6048...,
            "message_template_name": "welcome",
            "message_template_language": "en_US",
            "reason": "NONE",
            "other_info": {
              "title": "SECOND_PAUSE",
              "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Modelo de mensagem com exclusão pendente

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10310...",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "PENDING_DELETION",
            "message_template_id": 1137...,
            "message_template_name": "<MY_TEMPLATE_NAME>",
            "message_template_language": "en_US",
            "reason": "NONE"            
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Atualização de categoria do modelo

Modelo com categoria alterada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<ID>",
      "time": <TIME>,
      "changes": [
        {
          "field": "template_category_update",
          "value": {            
            "message_template_id": <MESSAGE_TEMPLATE_ID>,
            "message_template_name": "<MESSAGE_TEMPLATE_NAME>",
            "message_template_language": "<MESSAGE_TEMPLATE_LANGUAGE",
            "previous_category": "<PREVIOUS_CATEGORY>",
            "new_category": "<NEW_CATEGORY>"
          }
        }
      ]
    }
  ]
}

Atualização da qualidade do modelo de mensagem

Modelo com classificação de qualidade alterada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "field": "message_template_quality_update",
          "value": {
            "previous_quality_score": "<PREVIOUS_QUALITY_SCORE>",
            "new_quality_score": "<NEW_QUALITY_SCORE>",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>"
          }
        }
      ]
    }
  ]
}

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"
            }
          }
        }
      ]
    }
  ]
}

Conta do WhatsApp Business com violações da política

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "VIOLATION_TYPE"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

Conta do WhatsApp Business restrita depois de violações da política

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
               {"restriction_type": 
                 "RESTRICTED_BIZ_INITIATED_MESSAGING" | 
                 "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION" | 
                 "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", 
                 "expiration": TIMESTAMP}
                 ]
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

Conta do WhatsApp Business desabilitada

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "DISABLED_UPDATE",
            "ban_info": {
              "waba_ban_state": 
               "SCHEDULE_FOR_DISABLE" | 
               "DISABLE" | 
               "REINSTATE",
               "waba_ban_date": TIMESTAMP
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

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"
          }
        }
      ]
    }
  ]
}

Conta do WhatsApp Business restrita devido a violações da política

{
  "field": "account_update",
  "value": {
    "phone_number": "PHONE_NUMBER",
    "event": "ACCOUNT_RESTRICTION",
    "restriction_info": [
      {
        "restriction_type": "RESTRICTION_ADD_PHONE_NUMBER_ACTION",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      }
    ]
  }
}

Conta do WhatsApp Business excluída

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "ACCOUNT_DELETED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

Conta do WhatsApp Business removida do parceiro

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "PARTNER_REMOVED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

Atualizações de recursos para empresas

{
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
        "time": TIMESTAMP,
        "changes": [
          {
            "field": "business_capability_update",
            "value": {
              "max_daily_conversation_per_phone": NUMBER,
              "max_phone_numbers_per_business": NUMBER
            }
          }
        ]
      }
    ]
  }

Alertas de contas

Aumento do limite de mensagens negado

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "CRITICAL",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_FAILED",
            "alert_description": "Based on your activity, limits cannot be increased for your business <BUSINES_NAME>. Contact support for more information."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Aumento do limite de mensagem negado, é necessário mais uso

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
            "alert_description": "Limits cannot be increased for your business <BUSINES_NAME>. Use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Aumento do limite de mensagem negado, são necessárias mais informações

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO",
            "alert_description": "Additional verification is required for your business <BUSINESS_NAME>. Go to Security Center in Meta for Business to complete identity verification. To continue without completing additional verification, your business can use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}