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 seutype 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 HTTPPOST 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 oid do evento como o identificador de entrega e use type para rotear o payload.
Resposta
Retorne um status2xx 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
Usewhatsapp.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 dewhatsappBusinessAccount 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)
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.whatsappMessage.pricingCategory nos webhooks whatsapp.message.updated será definido como authentication_international.
Veja um exemplo:
Explicação
Encaminhe o evento portype, 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 webhookwhatsapp.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 portype, 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 comowhatsapp.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 portype, deduplique-o por id e atualize apenas o campo de limite incluído no payload.
Violação de conta
Ao receber um eventowhatsapp.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 portype, 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 deACCOUNT_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 portype, 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ê recebewhatsapp.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
UsewhatsappBusinessAccount.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 portype, 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 paraAPPROVED.
Aqui está um exemplo:
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma durável.Explicação
Encaminhe o evento portype, deduplique-o por id e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.
Análise da conta comercial
Usewhatsapp.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 comid. 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
Usewhatsapp.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
UsewhatsappPhoneNumber.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
Usewhatsapp.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
Leiadecision 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
Usewhatsapp.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
LeiaqualityRating (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
Usewhatsapp.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 permanecewhatsapp.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 incluirevoked 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.
