whatsapp.phone_number.quality_updated

Use whatsapp.phone_number.quality_updated para processar este evento em seu endpoint de webhook.

Gatilhos

Ocorre quando a qualidade, o limite de mensagens ou o status de conexão da conta de um número de telefone comercial do WhatsApp são atualizados. Inscreva-se em whatsapp.phone_number.quality_updated ao configurar seu endpoint de webhook. Mantenha o messagingLimit do número de telefone separado de whatsappBusinessManagerMessagingLimit, que descreve o limite compartilhado do portfólio de negócios proprietário. Níveis de exemplo não são padrões de conta. Leia qualityUpdateEvent para alterações de qualidade ou nível. Quando uma atualização de conta aciona este evento, updateEvent identifica ACCOUNT_OFFBOARDED ou ACCOUNT_RECONNECTED.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. A estrutura a seguir mostra uma variante de 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.quality_updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPhoneNumber": {
    "id": "<ID>",
    "phoneNumber": "<PHONE_NUMBER>",
    "displayPhoneNumber": "<DISPLAY_PHONE_NUMBER>",
    "wabaId": "<WABA_ID>",
    "qualityRating": "<QUALITY_RATING>",
    "messagingLimit": "<MESSAGING_LIMIT>",
    "whatsappBusinessManagerMessagingLimit": "<WHATSAPP_BUSINESS_MANAGER_MESSAGING_LIMIT>",
    "qualityUpdateEvent": "<QUALITY_UPDATE_EVENT>"
  }
}

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.quality_updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	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 específico do evento `whatsappPhoneNumber`.

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 se aplica quando o 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.
`qualityRating`	string	Não	Classificação de qualidade. Um dos seguintes: `GREEN`, `YELLOW`, `RED` ou `UNKNOWN`. Veja também Classificação de qualidade do número de telefone. `GREEN`: Alta qualidade. `YELLOW`: Qualidade média. `RED`: Baixa qualidade. `UNKNOWN`: Qualidade desconhecida.
`messagingLimit`	string	Não	Os limites de mensagens determinam o número máximo de conversas iniciadas pela empresa que cada número de telefone pode iniciar em um período móvel de 24 horas. Consulte também Limites de Mensagens. `TIER_NOT_SET`: Limite desconhecido. `TIER_50`: 50 conversas iniciadas pela empresa em um período móvel de 24 horas. `TIER_250`: 250 conversas iniciadas pela empresa em um período móvel de 24 horas. `TIER_1K`: 1 mil conversas iniciadas pela empresa com clientes únicos em um período móvel de 24 horas. `TIER_10K`: 10 mil conversas iniciadas pela empresa com clientes únicos em um período móvel de 24 horas. `TIER_100K`: 100 mil conversas iniciadas pela empresa com clientes únicos em um período móvel de 24 horas. `TIER_UNLIMITED`: Número ilimitado de conversas iniciadas pela empresa em um período móvel de 24 horas.
`whatsappBusinessManagerMessagingLimit`	string	Não	O limite de mensagens do portfólio de negócios proprietário. A partir de 7 de outubro de 2025, os limites de mensagens passarão a ser calculados e definidos com base no portfólio de negócios, sendo compartilhados por todos os números de telefone comerciais dentro de cada portfólio. Consulte também a referência do webhook phone_number_quality_update. `TIER_NOT_SET`: O número de telefone comercial ainda não foi usado para enviar mensagens. `TIER_50`: Limite de mensagens de 50 conversas iniciadas pela empresa em um período móvel de 24 horas. `TIER_250`: Limite de mensagens de 250 conversas iniciadas pela empresa em um período móvel de 24 horas. `TIER_2K`: Limite de mensagens de 2.000 conversas iniciadas pela empresa em um período móvel de 24 horas. `TIER_10K`: Limite de mensagens de 10.000 conversas iniciadas pela empresa em um período móvel de 24 horas. `TIER_100K`: Limite de mensagens de 100.000 conversas iniciadas pela empresa em um período móvel de 24 horas. `TIER_UNLIMITED`: O número de telefone comercial possui maior taxa de transferência com conversas iniciadas pela empresa ilimitadas.
`qualityUpdateEvent`	string	Não	Indica o tipo de evento de atualização da qualidade do número de telefone do WhatsApp quando uma notificação é enviada a você. `ONBOARDING`: Geralmente quando o limite de mensagens muda de `TIER_NOT_SET` para outro nível. `UPGRADE`: Nível do limite de mensagens atualizado (upgrade). `DOWNGRADE`: Nível do limite de mensagens reduzido (downgrade). `FLAGGED`: O status Sinalizado (Flagged) ocorre quando a classificação de qualidade atinge um nível baixo. Se a qualidade das mensagens melhorar para um estado alto ou médio e se mantiver assim por 7 dias, seu status retornará para Conectado. Se a classificação de qualidade não melhorar, seu status ainda retornará para Conectado, mas você será colocado em um nível inferior de limite de mensagens. Saiba mais na documentação de Classificação de Qualidade do Número de Telefone. `UNFLAGGED`: O status do número de telefone muda de `FLAGGED` para `CONNECTED`.
`updateEvent`	string	Não	Atualização de conta que disparou a alteração do número de telefone. Os valores conhecidos são `ACCOUNT_OFFBOARDED` e `ACCOUNT_RECONNECTED`.

Exemplo

O seguinte JSON é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos. Leia qualityRating e qualityUpdateEvent de whatsappPhoneNumber. messagingLimit descreve o nível do número de telefone; whatsappBusinessManagerMessagingLimit descreve o limite do portfólio de negócios proprietário.

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_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",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

Após verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe tarefas lentas de forma assíncrona.

HTTP/1.1 200 OK

Para orientações passo a passo dos cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

whatsapp.phone_number.quality_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