Exemplos de webhook de conta do WhatsApp Business atualizada

Para o catálogo completo derivado do esquema, consulte todos os exemplos.

O que é

Processe eventos de atualização de conta do WhatsApp Business.

Antes de começar

Crie um endpoint HTTPS público na sua aplicação.
Configure um endpoint de webhook da YCloud para os tipos de evento necessários.
Armazene o segredo de assinatura do endpoint com segurança.
Torne o processamento de eventos idempotente.

Como funciona

A YCloud envia uma requisição HTTP POST quando o evento ocorre. Valide a assinatura, registre o evento de forma durável, retorne uma resposta 2xx e processe tarefas lentas de forma assíncrona.

Requisição

Os cenários abaixo mostram as requisições entregues na sua URL de webhook. Trate o id do evento como o identificador de entrega e use type para rotear o payload.

Resposta

Retorne um status 2xx após aceitar o evento.

HTTP/1.1 200 OK

Para configuração do endpoint, validação de assinatura e comportamento de tentativas, consulte Configurar webhooks.

Elegibilidade para tarifa internacional de autenticação

A partir de 1º de junho de 2024, introduziremos uma nova tarifa internacional de autenticação. Essa tarifa será aplicada nos seguintes países:

1º de junho de 2024 – Indonésia (código de chamada do país +62, código do país ID)
1º de julho de 2024 – Índia (código de chamada do país +91, código do país IN)

Para obter mais informações, consulte Elegibilidade para tarifa internacional de autenticação. Um webhook whatsapp.business_account.updated será acionado se a sua empresa for considerada elegível para tarifas internacionais. O webhook incluirá os horários de início para cada país que possuir uma tarifa internacional de autenticação.

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Se uma mensagem for faturada com a tarifa internacional de autenticação, o campo whatsappMessage.pricingCategory nos webhooks whatsapp.message.updated será definido como authentication_international. Aqui está um exemplo:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Atualização da localização principal da empresa

Sua localização principal da empresa é o país onde sua empresa está sediada. Ela aparecerá no Gerenciador de Negócios no campo Localização Principal da Empresa a partir de 1º de maio de 2024. Se a Meta conseguir determinar o país onde sua empresa está sediada, dispararemos um webhook whatsapp.business_account.updated com o código de dois dígitos do país. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Atualização do limite de registro de números de telefone

A Meta envia uma atualização de capacidade de negócios para uma WABA quando o limite de registro de números de telefone do Business Portfolio ou da WABA correspondente é alterado. A YCloud a entrega como whatsapp.business_account.updated com updateEvent=BUSINESS_CAPABILITY_UPDATE. O webhook está no nível da WABA: whatsappBusinessAccount.id é o ID da WABA a partir da entrada de webhook da Meta. Atualmente, a Meta informa maxPhoneNumbersPerBusiness e maxPhoneNumbersPerWaba em atualizações separadas. Não os trate como mutuamente exclusivos: processe cada campo de forma independente e aceite ambos se uma atualização futura os incluir juntos. Um valor de 0 é válido. Aqui está um exemplo de uma atualização do limite de números de telefone da WABA:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e atualize apenas o campo de limite incluído no payload.

Violação da conta

As contas do WhatsApp Business receberão inicialmente um aviso com informações sobre a política violada. Consulte também Violações de Políticas da Plataforma WhatsApp Business
. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SPAM"
  }
}

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Restrição da conta

Se as contas comerciais violarem repetidamente os Termos de Serviço do WhatsApp Business ou categorias de políticas de alto risco, como envio de spam, conteúdo adulto, venda de álcool e tabaco, drogas, jogos de azar e suplementos não seguros, elas poderão começar a sofrer restrições de mensagens com duração gradualmente maior. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
    ]
  }
}

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Conta desativada

As contas do WhatsApp Business podem ser desativadas se a empresa não fizer alterações após vários avisos e limites ou bloqueios de recursos. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Restauração da conta

Você pode recorrer da decisão de banimento da conta do WhatsApp Business para restabelecê-la. Uma vez aprovada, o status de revisão da conta muda para APPROVED. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova o trabalho lento ou propenso a falhas para um processador assíncrono.

Primeiros passos

Guias

Endpoints

Webhooks

Exemplos de webhook de conta do WhatsApp Business atualizada

O que é

Antes de começar

Como funciona

Requisição

Resposta

Elegibilidade para tarifa internacional de autenticação

Requisição

Resposta

Explicação

Atualização da localização principal da empresa

Requisição

Resposta

Explicação

Atualização do limite de registro de números de telefone

Requisição

Resposta

Explicação

Violação da conta

Requisição

Resposta

Explicação

Restrição da conta

Requisição

Resposta

Explicação

Conta desativada

Requisição

Resposta

Explicação

Restauração da conta

Requisição

Resposta

Explicação

​O que é

​Antes de começar

​Como funciona

​Requisição

​Resposta

​Elegibilidade para tarifa internacional de autenticação

​Requisição

​Resposta

​Explicação

​Atualização da localização principal da empresa

​Requisição

​Resposta

​Explicação

​Atualização do limite de registro de números de telefone

​Requisição

​Resposta

​Explicação

​Violação da conta

​Requisição

​Resposta

​Explicação

​Restrição da conta

​Requisição

​Resposta

​Explicação

​Conta desativada

​Requisição

​Resposta

​Explicação

​Restauração da conta

​Requisição

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Requisição

Resposta

Elegibilidade para tarifa internacional de autenticação

Requisição

Resposta

Explicação

Atualização da localização principal da empresa

Requisição

Resposta

Explicação

Atualização do limite de registro de números de telefone

Requisição

Resposta

Explicação

Violação da conta

Requisição

Resposta

Explicação

Restrição da conta

Requisição

Resposta

Explicação

Conta desativada

Requisição

Resposta

Explicação

Restauração da conta

Requisição

Resposta

Explicação