Skip to main content
Para conferir o catálogo completo derivado do schema, veja todos os exemplos.

O que é

Gerencie eventos de análise, atualização e exclusão de contas comerciais, além de exclusão de número de telefone, análise de nome de exibição, qualidade e atualizações de nome de usuário comercial (Business Username). Encaminhe cada payload pelo seu type exato do evento: eventos de conta usam whatsappBusinessAccount, enquanto eventos de número de telefone usam whatsappPhoneNumber.

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. Verifique 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 requisições entregues na URL do seu 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.
Para configuração de endpoint, validação de assinatura e comportamento de novas tentativas, consulte Configurar webhooks.

Exclusão de conta

Use whatsapp.business_account.deleted para processar um evento de exclusão de conta do WhatsApp Business. Leia whatsappBusinessAccount.id para identificar a WABA afetada.

Requisição

Resposta

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

Explicação

Os campos de remoção aparecem diretamente dentro de whatsappBusinessAccount quando disponíveis. Os valores conhecidos de removedReason incluem: Preserve valores desconhecidos de motivo e iniciador. Elimine entregas duplicadas pelo id do evento e tolere campos de remoção omitidos.

Qualificação para tarifa internacional de autenticação

A partir de 1º de junho de 2024, estamos introduzindo uma nova tarifa internacional de autenticação. Esta 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 mais informações, consulte Qualificação para tarifa internacional de autenticação . Um webhook whatsapp.business_account.updated será disparado se a sua empresa for considerada qualificada 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

Resposta

Confirme a entrega após aceitar o evento de forma durável.
Se uma mensagem for cobrada com a tarifa internacional de autenticação, o whatsappMessage.pricingCategory nos webhooks whatsapp.message.updated será definido como authentication_international. Veja um exemplo:

Explicação

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

Atualização do local principal da empresa

O seu local principal da empresa é o país onde a sua empresa está sediada. Ele aparecerá no Gerenciador de Negócios no campo Local principal da empresa a partir de 1º de maio de 2024. Se a Meta conseguir determinar o país onde a sua empresa está sediada, dispararemos um webhook whatsapp.business_account.updated com o código de dois dígitos do país. Veja um exemplo:

Requisição

Resposta

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

Explicação

Encaminhe 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 comercial para uma WABA quando o Portfólio empresarial ou o limite de registro de números de telefone da WABA correspondente é alterado. A YCloud faz a entrega como whatsapp.business_account.updated com updateEvent=BUSINESS_CAPABILITY_UPDATE. O webhook ocorre no nível da WABA: whatsappBusinessAccount.id é o ID da WABA da entrada do webhook da Meta. A Meta relata atualmente 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. O valor 0 é válido. Aqui está um exemplo de uma atualização de limite de números de telefone da WABA:

Requisição

Resposta

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

Explicação

Encaminhe o evento por type, deduplique-o por id e atualize apenas o campo de limite incluído no payload.

Violação de conta

Ao receber um evento whatsapp.business_account.updated com whatsappBusinessAccount.updateEvent definido como ACCOUNT_VIOLATION, inspecione whatsappBusinessAccount.violationType para identificar a violação de política relatada. Consulte Violações de aplicação de políticas da Meta para obter tipos e descrições de violações. A Meta pode atualizar esta lista ao longo do tempo. Aqui está um exemplo:

Requisição

Resposta

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

Explicação

Encaminhe o evento por type, deduplique-o por id e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.

Restrição de conta

Se as contas do WhatsApp Business 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 que aumentam gradualmente em duração. Para o Envio Direto de Utilidade, consulte Notificações de Envio Direto para obter um payload de ACCOUNT_RESTRICTION da YCloud. Consulte o documento Webhook para restrição de conta da Meta para tipos de violação e detalhes de restrição específicos do Envio Direto. Aqui está um exemplo:

Requisição

Resposta

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

Explicação

Encaminhe o evento por type, deduplique-o por id e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.

Restrição de Envio Direto de utilidade

Você recebe whatsapp.business_account.updated quando a Meta restringe o Envio Direto de utilidade após o uso indevido repetido da categoria. Este exemplo mostra uma restrição de sete dias.

Requisição

Resposta

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

Explicação

Use whatsappBusinessAccount.id para identificar a WABA afetada e pausar seu fluxo de trabalho de Envio Direto de utilidade. Leia violationType para obter o motivo, restrictions[].restrictionType para a capacidade afetada e restrictions[].expiration para a expiração, quando fornecida. Uma análise bem-sucedida de um modelo não remove automaticamente uma restrição no nível da conta. Consulte Restrições e notificações de Envio Direto.

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

Resposta

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

Explicação

Encaminhe o evento por type, deduplique-o por id e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.

Restabelecimento de conta

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

Requisição

Resposta

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

Explicação

Encaminhe o evento por type, deduplique-o por id e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.

Análise da conta comercial

Use whatsapp.business_account.reviewed quando uma conta do WhatsApp Business tiver sido analisada.

Requisição

Resposta

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

Explicação

Identifique a WABA com id. Leia decision para saber a decisão da análise (APPROVED ou REJECTED) e accountReviewStatus para saber o status de análise da conta quando fornecido. Não encaminhe este evento como whatsapp.business_account.updated.

Exclusão de número de telefone

Use whatsapp.phone_number.deleted quando um número de telefone comercial do WhatsApp for excluído.

Requisição

Resposta

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

Explicação

Use whatsappPhoneNumber.id para identificar o número de telefone excluído e wabaId para associá-lo à respectiva conta. Este é um evento de número de telefone; não o trate como exclusão de toda a WABA.

Análise do nome de exibição do número de telefone

Use whatsapp.phone_number.name_updated quando o nome de exibição de um número de telefone comercial for aprovado ou rejeitado.

Requisição

Resposta

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

Explicação

Leia decision e os campos de status do nome fornecidos. newNameStatus descreve a nova solicitação de nome de exibição, requestedVerifiedName identifica o último nome solicitado e rejectionReason descreve uma rejeição, quando presente. A análise do nome de exibição é separada de uma atualização de Nome de Usuário Comercial.

Atualização de qualidade do número de telefone

Use whatsapp.phone_number.quality_updated para alterações no status relacionado à qualidade de um número de telefone comercial.

Requisição

Resposta

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

Explicação

Leia qualityRating (GREEN, YELLOW ou RED) e qualityUpdateEvent para entender a atualização. messagingLimit é o nível do número de telefone; whatsappBusinessManagerMessagingLimit é o limite do portfólio empresarial proprietário. Mantenha esses campos separados e atualize apenas os valores fornecidos no evento.

Nome de usuário comercial ativado

Use whatsapp.phone_number.business_username_updated para sincronizar o nome de usuário comercial de um número de telefone.

Requisição

Resposta

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

Explicação

businessUsername é o nome de usuário ativo sem um @ inicial. Leia businessUsernameStatus e businessUsernameUpdatedAt com o id do número de telefone. Não confunda esse valor com o nome de exibição verificado.

Solicitação de nome de usuário comercial reservada

Um nome de usuário comercial ativo pode continuar em uso enquanto uma solicitação de substituição estiver reservada.

Requisição

Resposta

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

Explicação

Neste exemplo, businessUsername permanece acme.support enquanto requestedBusinessUsername é acme.help. O status reserved descreve a solicitação pendente, não a ativação da substituição. Aceite o valor legado de pending_review ao ler eventos mais antigos; novas gravações usam reserved.

Nome de usuário comercial revogado

O tipo de evento permanece whatsapp.phone_number.business_username_updated. businessUsernameContext é uma string opcional. Um valor de revoked descreve uma notificação de revogação; ele é separado de businessUsernameStatus.

Requisição

Resposta

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

Explicação

A YCloud atualiza o nome de usuário atual e o status da Meta antes de gerar este evento. Ela inclui revoked apenas quando o nome de usuário retornado por uma consulta atual bem-sucedida à Meta corresponder ao nome de usuário na notificação de revogação. Se a notificação se referir ao nome de usuário A, mas a Meta agora retornar B, um evento emitido conterá B e omitirá o contexto obsoleto de revoked. O contexto também é omitido quando a notificação não tem contexto. Avisos históricos exibidos no console não são reproduzidos neste campo. Uma notificação simulada upstream não substitui o nome de usuário ou o status retornado pela Meta.