whatsapp.phone_number.business_username_updated

Use whatsapp.phone_number.business_username_updated para processar este evento no endpoint do seu webhook.

Gatilhos

Ocorre quando o Business Username de um número de telefone comercial do WhatsApp é atualizado. Inscreva-se em whatsapp.phone_number.business_username_updated ao configurar o endpoint do seu webhook.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. A estrutura a seguir mostra uma variante do payload. Os valores entre colchetes angulares são marcadores de posição; seus tipos estão listados em Parâmetros. Campos opcionais e outras variantes são descritos abaixo.

{
  "id": "<ID>",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPhoneNumber": {
    "id": "<ID>",
    "wabaId": "<WABA_ID>",
    "phoneNumber": "<PHONE_NUMBER>",
    "businessUsername": "<BUSINESS_USERNAME>",
    "businessUsernameStatus": "<BUSINESS_USERNAME_STATUS>",
    "businessUsernameContext": "<BUSINESS_USERNAME_CONTEXT>"
  }
}

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do evento. Tamanho mínimo: `6`. Tamanho máximo: `128`.
`type`	string	Sim	Sempre `whatsapp.phone_number.business_username_updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (data e hora)	Sim	O momento em que este evento foi criado, formatado em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`whatsappPhoneNumber`	object	Não	Payload do `whatsappPhoneNumber` específico do evento.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objeto, Obrigatório aplica-se quando seu objeto pai estiver presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

whatsappPhoneNumber

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Não	ID do número de telefone.
`phoneNumber`	string	Não	Número de telefone no formato E.164.
`displayPhoneNumber`	string	Não	Número de telefone de exibição.
`wabaId`	string	Não	ID da conta do WhatsApp Business.
`businessUsername`	string	Não	Business Username ativo para este número de telefone. O valor é um nome de usuário simples sem `@`.
`businessUsernameStatus`	string	Não	Status do Business Username para um número de telefone comercial do WhatsApp. `not_set`: Não existe Business Username ativo ou pendente. `active`: Um Business Username está ativo. `reserved`: O Business Username solicitado foi reservado pela Meta e ainda pode estar em análise. `pending_review`: Valor legado de compatibilidade para uma solicitação em análise. Novas gravações usam `reserved`. Se existir um nome de usuário ativo enquanto uma nova solicitação estiver reservada ou em análise, `businessUsernameStatus` será `reserved`, `businessUsername` conterá o nome de usuário ainda ativo e `requestedBusinessUsername` conterá o nome de usuário solicitado.
`requestedBusinessUsername`	string	Não	Último Business Username solicitado que ainda está em análise. Esse valor pode coexistir com um `businessUsername` ativo enquanto a nova solicitação estiver pendente.
`businessUsernameContext`	string	Não	Contexto opcional para esta notificação de nome de usuário. `revoked` é exibido apenas quando o nome de usuário retornado por uma consulta recente bem-sucedida à Meta corresponde a esta notificação de revogação. É omitido em revogações obsoletas ou em notificações sem contexto. Este campo não expõe avisos históricos de páginas.
`businessUsernameUpdatedAt`	string (data e hora)	Não	O momento em que o status do Business Username foi atualizado pela última vez.

Exemplo

O JSON a seguir é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos.

Nome de usuário comercial revogado e substituído

{
  "id": "evt_business_username_revoked_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "wabaId": "whatsapp-business-account-id",
    "phoneNumber": "+12025550124",
    "businessUsername": "autogenerated_name",
    "businessUsernameStatus": "active",
    "businessUsernameContext": "revoked"
  }
}

Evento de nome de usuário comercial de número de telefone do WhatsApp atualizado

Exemplo de payload quando um nome de usuário comercial de número de telefone do WhatsApp se torna ativo

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+12025550124",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

Evento de nome de usuário comercial de número de telefone do WhatsApp reservado

Exemplo de payload quando um número de telefone do WhatsApp tem uma solicitação de nome de usuário comercial reservada

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+12025550124",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

Depois de verificar a assinatura e aceitar o evento de forma durável, retorne uma resposta 2xx. Processe tarefas lentas de forma assíncrona.

HTTP/1.1 200 OK

Para orientações detalhadas de cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

whatsapp.phone_number.business_username_updated

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappPhoneNumber

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​whatsappPhoneNumber

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

whatsappPhoneNumber

Exemplo