Integração · WhatsApp Business Account

Campos de webhook do app Meta

Os 33 campos exibidos no app HookCloud Partner, explicados individualmente: finalidade, gatilhos, dados, destino, cuidados e tratamento disponível. A conferência de 19/10/2026 encontrou 30 assinados e 3 não assinados. A inscrição, a elegibilidade do número, a inicialização do recurso e a entrega ao seu sistema são etapas distintas.

Aplicativo e conferência das assinaturas

Aplicativo Meta: HookCloud Partner
1046505108355448
Versão Graph de referência: v26.0
Estado da conferência: Conferido no Meta Developers: 30 campos assinados e 3 não assinados
Conferência registrada: 2026-10-19T21:39:29.935Z

Conferência somente de leitura no app HookCloud Partner em 19/10/2026. Todos os seletores de versão exibiam v26.0; nos campos não assinados, a versão selecionada não ativa a entrega. O estado pertence ao app da HookCloud e pode mudar após esta data. Inscrição não comprova elegibilidade, inicialização nem entrega de cada recurso para um número.

Catálogo atualizado em 2026-10-19. O estado registrado descreve a conferência acima; esta página não consulta o painel Meta em tempo real.

30 · Assinado no app3 · Não assinado no app0 · Não confirmado

Assinatura no app não comprova entrega ao parceiro nem habilitação de um recurso. Confira o destino e o comportamento de cada campo abaixo. “Não confirmado” indica ausência de evidência suficiente nesta conferência.

De onde vem o evento e para onde ele vai

Callback alternativo do número

Para campos compatíveis, a Meta verifica primeiro o callback alternativo do número comercial associado ao evento.

Callback alternativo da WABA

Quando não existe callback alternativo do número, a Meta consulta o callback alternativo da Messaging account/WABA.

Callback padrão do app

É o destino de fallback dos campos compatíveis e o destino documentado para os campos que não aceitam override. A lista oficial inclui todos os quatro campos group_*, além de messages, message_echoes, calls, messaging_handovers, standby, smb_message_echoes, smb_app_state_sync, history e account_settings_update. A lista oficial de overrides também inclui consumer_profile, que não aparece entre os 33 campos exibidos nesta conferência do app e não integra este catálogo.

Tratamento pelo HookCloud Partner

A entrega original pela Meta e o tratamento interno do Partner são etapas distintas. Consulte o comportamento de cada campo; não presuma repasse bruto ou importação automática.

Leia o contrato antes de escolher o parser. Os nomes dos campos Meta em changes[].field e os nomes de eventos HookCloud são identificadores diferentes. Veja as assinaturas e o processamento do receptor.

Regras para processar os eventos

Nos quadros de payload, caminhos como metadata.phone_number_id e state_sync[] são relativos a entry[].changes[].value. Caminhos iniciados por object ou entry[] referem-se ao envelope completo. Todos os campos descritos são condicionais ao tipo de evento; não exija sua presença em todo POST.
Percorra todos os itens de entry[] e changes[] e selecione o contrato por changes[].field. Um payload válido pode não conter messages[].
Uma inscrição permite receber o tipo de evento quando a Meta o produz; não habilita, sozinha, recursos como chamadas, grupos, pagamentos ou sincronização.
Campos de webhook não são permissões OAuth nem comprovação de Advanced Access.
Compatibilidade com callback alternativo não comprova que a rota esteja configurada nem que a entrega tenha ocorrido.
Eventos originais da Meta e eventos normalizados emitidos pelo HookCloud possuem contratos diferentes; confirme o tratamento e o tipo recebido.
Salve ou enfileire o evento e responda HTTP 200 rapidamente. Processe alterações de forma idempotente e trate lotes, repetições e ordem de chegada.
Identifique o ativo correto e não use nomes de contato, nome de template ou posição no lote como única chave.
Contratos públicos não confirmados permanecem explicitamente sem esquema interno documentado.
Os payloads desta página explicam o formato original da Meta. Quando o destino for administrativo, implemente no seu sistema o contrato normalizado HookCloud indicado no item, e não um parser à espera do evento bruto.
Prefira eventos e cache. Consultas GET diretas à Meta devem ser controladas, agrupadas e feitas somente quando necessárias; não faça polling por cliente ou uma consulta por evento recebido.

Catálogo de campos Meta

Busque pelo nome do campo, caminho do payload, comportamento ou recurso. Abra cada item para consultar finalidade, gatilho, entrega, ação recomendada e limites. O filtro de assinatura descreve o app da HookCloud; não altera sua configuração.

33 campos no catálogo

account_alertsAlertas da contaAssinado no appConta e capacidade

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Alertas sobre limites de mensagens, foto de perfil e status de conta comercial oficial (OBA).

Quando a Meta pode emitir

A Meta decide ou solicita informação sobre limites, altera o reconhecimento OBA ou remove a foto comercial.

Como chega à sua integração

Segundo a regra de roteamento da Meta, este campo é entregue ao callback padrão do app HookCloud Partner, e não ao callback alternativo do número. O sistema do assinante deve usar somente os eventos normalizados que a HookCloud declara emitir para esse caso; a seleção do campo no app não garante retransmissão do evento bruto.

O que a HookCloud Partner faz

O evento chega ao callback administrativo da HookCloud. O Partner interpreta apenas os casos suportados, relacionando a WABA e o número à instância correta. Não há encaminhamento genérico do JSON Meta original para o assinante. Mudanças de estado confirmadas podem produzir os eventos HookCloud documentados, como hookcloud.instance.health_updated e hookcloud.customer.risk_updated; não existe correspondência de um evento HookCloud para cada POST da Meta. A descrição e a severidade são tratadas conservadoramente: um alerta isolado não prova banimento.

Como ler o payload

Campo / caminho	Significado e uso
`entity_type`	Tipo do ativo ao qual o alerta se refere; determina como interpretar entity_id.
`entity_id`	Identificador do ativo afetado; não presumir que seja sempre o ID do número.
`alert_info.alert_severity`	Severidade atribuída ao alerta pela Meta.
`alert_info.alert_status`	Estado do alerta conforme o evento produzido pela Meta.
`alert_info.alert_type`	Tipo do alerta, usado para selecionar a interpretação.
`alert_info.alert_description`	Descrição do alerta e, quando fornecida, orientação sobre a causa ou ação.

O que implementar no seu sistema

Leia alert_info antes de criar um alerta operacional; associe entity_type e entity_id ao ativo correto.

Limites e cuidados deste campo

Um alerta não comprova banimento; interprete tipo, severidade e descrição.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Alertas da conta ↗

account_review_updateAnálise da contaAssinado no appConta e capacidade

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Resultado da análise da conta WhatsApp contra políticas da Meta, entregue pela Messaging account associada.

Quando a Meta pode emitir

A análise da conta resulta em aprovação, rejeição, decisão pendente ou decisão adiada.

Como chega à sua integração

O que a HookCloud Partner faz

O evento chega ao callback administrativo da HookCloud. O Partner interpreta apenas os casos suportados, relacionando a WABA e o número à instância correta. Não há encaminhamento genérico do JSON Meta original para o assinante. Mudanças de estado confirmadas podem produzir os eventos HookCloud documentados, como hookcloud.instance.health_updated e hookcloud.customer.risk_updated; não existe correspondência de um evento HookCloud para cada POST da Meta. A análise da conta WhatsApp é separada da verificação empresarial. APPROVED não apaga automaticamente um banimento de outro domínio.

Como ler o payload

Campo / caminho	Significado e uso
`decision`	Resultado da análise: APPROVED, REJECTED, PENDING ou DEFERRED, conforme a referência do campo.

O que implementar no seu sistema

Atualize o estado de análise separadamente da verificação da empresa e das permissões do aplicativo.

Limites e cuidados deste campo

decision pode ser APPROVED, REJECTED, PENDING ou DEFERRED. Não é aprovação de permissões do app.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Análise da conta ↗

account_settings_updateConfigurações de chamadasAssinado no appChamadas

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Atualizações de configurações do número; atualmente a referência cobre configurações de chamadas selecionadas.

Quando a Meta pode emitir

Muda uma configuração de chamada observada pela Meta, inclusive quando a própria integração fez a alteração.

Como chega à sua integração

Este campo admite callback alternativo por número segundo a Meta. Com assinatura, permissões, recurso e callback configurados, a Meta pode entregá-lo diretamente ao webhook global do seu sistema. O receptor deve interpretar o envelope Meta original. A inscrição, isoladamente, não comprova que a função esteja habilitada ou que um evento tenha sido entregue.

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. Não há sincronização específica de todas as configurações de Calling no Portal. Os detalhes SIP de diagnóstico da instância não equivalem à implementação completa deste recurso.

Como ler o payload

Campo / caminho	Significado e uso
`messaging_product`	Produto do evento; whatsapp neste contrato.
`timestamp`	Horário da alteração ou evento, em timestamp Unix conforme a referência.
`type`	Tipo de mudança de configuração; atualmente PHONE_NUMBER_SETTINGS.
`phone_number_settings.phone_number_id`	ID do número cuja configuração de chamada foi alterada.
`phone_number_settings.calling`	Configurações de chamadas informadas; somente alguns atributos são observados pela Meta.

O que implementar no seu sistema

Leia type e phone_number_settings, compare somente as configurações presentes e evite ciclos causados pelos próprios updates.

Limites e cuidados deste campo

Também notifica alterações feitas pela própria integração. type=PHONE_NUMBER_SETTINGS. Campos observados em calling: status, call_icon_visibility, callback_permission_status, sip.status e srtp_key_exchange_protocol; não é monitor genérico de toda configuração da conta.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Configurações de chamadas ↗

account_updateAtualizações da contaAssinado no appConta e capacidade

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Eventos da conta: verificação, vínculo com parceiros, políticas/termos, restrições, localização, preços e desconexão/reconexão, conforme event.

Quando a Meta pode emitir

Ocorre um dos eventos administrativos documentados: vínculo com parceiro, política, termos, verificação, desconexão ou reconexão.

Como chega à sua integração

O que a HookCloud Partner faz

O evento chega ao callback administrativo da HookCloud. O Partner interpreta apenas os casos suportados, relacionando a WABA e o número à instância correta. Não há encaminhamento genérico do JSON Meta original para o assinante. Mudanças de estado confirmadas podem produzir os eventos HookCloud documentados, como hookcloud.instance.health_updated e hookcloud.customer.risk_updated; não existe correspondência de um evento HookCloud para cada POST da Meta. Remoções de vínculo só alteram a instância quando o escopo da parceria e a geração da conexão são comprovados. O evento instance.meta_link_removed documenta a retirada confirmada; um evento antigo não deve encerrar uma reconexão nova.

Como ler o payload

Campo / caminho	Significado e uso
`event`	Tipo do evento que seleciona a interpretação e os detalhes condicionais.
`phone_number`	Número comercial informado quando o evento diz respeito a um único número.
`country`	País informado no evento de atualização da localização comercial principal.
`waba_info`	Informações da conta, portfólio ou conta de anúncios, presentes somente nos eventos correspondentes.
`violation_info`	Detalhes da violação identificada pela Meta, quando este for o tipo de evento.
`ban_info`	Detalhes condicionais do estado/data de banimento nos eventos aplicáveis.
`restriction_info`	Restrições e dados adicionais, como expiração ou orientação, quando fornecidos.
`auth_international_rate_eligibility`	Elegibilidade e exceções de preço de autenticação internacional, quando aplicável.
`volume_tier_info`	Dados de atualização da faixa de preço por volume, quando o evento a descreve.

O que implementar no seu sistema

Selecione a interpretação por event e confirme o escopo antes de alterar o estado de uma conexão.

Limites e cuidados deste campo

Objetos são condicionais ao evento. A referência inclui desde 2026 eventos de offboarding e reconexão por mudança de aparelho ou novo registro do número.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Atualizações da conta ↗

automatic_eventsLeads e compras automáticosAssinado no appMedição

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Notifica detecção automática de lead ou compra em conversa iniciada por anúncio Click to WhatsApp quando a empresa aderiu a Automatic Events reporting.

Quando a Meta pode emitir

A Meta detecta LeadSubmitted ou Purchase em uma conversa de anúncio Click to WhatsApp com Automatic Events reporting habilitado.

Como chega à sua integração

O que a HookCloud Partner faz

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`automatic_events[].id`	Identificador WhatsApp da mensagem associada à detecção automática.
`automatic_events[].event_name`	Tipo detectado: LeadSubmitted ou Purchase.
`automatic_events[].timestamp`	Timestamp Unix em que o evento automático foi disparado.
`automatic_events[].ctwa_clid`	Identificador do clique Click to WhatsApp; pode estar ausente para anúncios em Status.
`automatic_events[].custom_data.currency`	Moeda da compra; presente nos eventos de compra aplicáveis.
`automatic_events[].custom_data.value`	Valor da compra na escala documentada pela Meta: preço multiplicado por 1000.

O que implementar no seu sistema

Interprete event_name e a configuração aplicável; trate os identificadores de atribuição como condicionais e observe a escala monetária de custom_data.value.

Limites e cuidados deste campo

event_name=LeadSubmitted/Purchase. Depende de adesão/configuração; marcar campo não implementa o recurso. custom_data é de compra; ctwa_clid pode ser omitido para anúncios em WhatsApp Status. value usa escala indicada na referência (preço multiplicado por 1000).
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Leads e compras automáticos ↗

business_capability_updateCapacidades e limitesAssinado no appConta e capacidade

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudanças de capacidades da hierarquia de contas ou do portfólio, como limites de mensagens e números.

Quando a Meta pode emitir

Uma conta é criada ou uma capacidade do portfólio/hierarquia de contas aumenta ou diminui.

Como chega à sua integração

O que a HookCloud Partner faz

O evento chega ao callback administrativo da HookCloud. O Partner interpreta apenas os casos suportados, relacionando a WABA e o número à instância correta. Não há encaminhamento genérico do JSON Meta original para o assinante. Mudanças de estado confirmadas podem produzir os eventos HookCloud documentados, como hookcloud.instance.health_updated e hookcloud.customer.risk_updated; não existe correspondência de um evento HookCloud para cada POST da Meta. As capacidades da Meta são distintas da quantidade de vagas compradas no pacote HookCloud.

Como ler o payload

Campo / caminho	Significado e uso
`max_daily_conversations_per_business`	Limite de mensagens/capacidade do portfólio informado no evento; interpretar o valor conforme a versão vigente.
`max_phone_numbers_per_business`	Limite de números do portfólio, incluído apenas nas condições previstas pela Meta.
`max_phone_numbers_per_waba`	Limite de números na hierarquia da conta, quando informado.
`max_daily_conversation_per_phone`	Campo legado de limite por telefone; a referência recomenda max_daily_conversations_per_business.

O que implementar no seu sistema

Atualize somente os limites presentes e confirme valores atuais pela API quando a operação depender deles.

Limites e cuidados deste campo

A referência marca max_daily_conversation_per_phone para remoção e recomenda max_daily_conversations_per_business. Evite prometer limites fixos ou associar todo limite exclusivamente ao número.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Capacidades e limites ↗

business_status_updateEstado comercial: contrato a confirmarAssinado no appConta e capacidade

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Campo observado no inventário do app; contrato público específico não confirmado nesta revisão.

Quando a Meta pode emitir

O disparador público específico deste campo não foi confirmado nesta revisão.

Como chega à sua integração

O que a HookCloud Partner faz

O evento chega ao callback administrativo da HookCloud. O Partner interpreta apenas os casos suportados, relacionando a WABA e o número à instância correta. Não há encaminhamento genérico do JSON Meta original para o assinante. Mudanças de estado confirmadas podem produzir os eventos HookCloud documentados, como hookcloud.instance.health_updated e hookcloud.customer.risk_updated; não existe correspondência de um evento HookCloud para cada POST da Meta. O código reconhece evidências explícitas de estado quando presentes. Como não foi confirmado um contrato público específico deste campo, o nome sozinho não comprova verificação, bloqueio ou restabelecimento.

Como ler o payload

Campo / caminho	Significado e uso
`object`	Objeto do webhook: whatsapp_business_account.
`entry[].id`	Identificador do ativo de origem no envelope. O contrato específico deste campo ainda precisa ser confirmado; não assumir que seja o ID do número.
`entry[].changes[].field`	Nome do campo de inscrição que identifica o tipo do evento.
`entry[].changes[].value`	Conteúdo específico do evento. Seu esquema interno não foi confirmado nesta revisão; não inferir chaves ou efeitos.

O que implementar no seu sistema

Preserve o envelope para diagnóstico autorizado; não deduza status nem efeitos pelo nome do campo.

Limites e cuidados deste campo

Não inferir saúde da empresa, verificação, aprovação ou banimento pelo nome do campo. Não publicar esquema inventado.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Visão geral ou referência de roteamento da Meta; contrato específico não confirmado ↗

business_username_updatesUsername comercialAssinado no appIdentidade do número

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudanças de status do username comercial de um número no WhatsApp.

Quando a Meta pode emitir

O username comercial muda de estado, incluindo reserva, aprovação, exclusão ou revogação pela Meta.

Como chega à sua integração

O que a HookCloud Partner faz

A HookCloud registra o evento e agenda a reconciliação controlada do perfil do número correspondente. Um username reservado não é exibido como ativo por suposição. Consulte os dados normalizados da instância e os eventos HookCloud de atualização; não há garantia de encaminhamento do JSON original.

Como ler o payload

Campo / caminho	Significado e uso
`display_phone_number`	Número comercial de exibição ao qual o evento se refere.
`username`	Username comercial afetado; omitido quando status é deleted.
`status`	Estado do username: approved, deleted ou reserved; uma reserva não equivale a username público ativo.
`context`	Contexto adicional condicional; revoked identifica revogação de username pela Meta.

O que implementar no seu sistema

Leia status e context em conjunto; trate o username separadamente do nome de exibição aprovado.

Limites e cuidados deste campo

status: approved, deleted ou reserved. username é omitido em deleted; context=revoked identifica revogação pela Meta. Ausência de context não identifica quem iniciou a mudança. É diferente de mudanças no identificador de um usuário consumidor.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Username comercial ↗

callsChamadasAssinado no appChamadas

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Eventos e status da WhatsApp Business Calling API, como conexão, encerramento e disponibilidade de gravação/transcrição quando configuradas.

Quando a Meta pode emitir

A Calling API produz eventos de conexão, status ou encerramento; recursos adicionais podem produzir eventos de gravação ou transcrição.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O Partner não oferece uma central de telefonia por ter este campo assinado; seu sistema precisa implementar os fluxos da Calling API e cumprir seus requisitos.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`calls[].id`	Identificador único da chamada, usado para correlacionar seus eventos.
`calls[].event`	Evento da chamada, como connect, terminate ou eventos adicionais habilitados.
`calls[].direction`	Indica se a chamada foi iniciada pela empresa ou pelo usuário.
`calls[].timestamp`	Horário do evento de chamada em timestamp Unix.
`calls[].session`	Dados de sinalização SDP quando aplicáveis; não presentes no fluxo SIP correspondente.
`statuses[].type`	Tipo do status; em notificações de Calling, identifica o status como call.
`statuses[].status`	Estado relatado pelo recibo; seus valores dependem do campo e do tipo de evento.
`errors`	Erros condicionais associados ao evento ou à operação; interpretar código e detalhes.

O que implementar no seu sistema

Identifique o evento por calls[].event ou statuses[].type e correlacione pelo identificador da chamada.

Limites e cuidados deste campo

Assinatura não habilita chamadas. Depende de disponibilidade, configuração e permissões aplicáveis. Alguns eventos usam statuses; não presumir somente calls[]. SIP não usa o mesmo session de sinalização WebRTC.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Chamadas ↗

flowsEventos de WhatsApp FlowsAssinado no appWhatsApp Flows

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Criação, estado, alertas de desempenho e expiração de versões de WhatsApp Flows.

Quando a Meta pode emitir

Um Flow é criado, muda de estado, ultrapassa limites técnicos de desempenho ou se aproxima da expiração de versão.

Como chega à sua integração

O que a HookCloud Partner faz

Como ler o payload

Campo / caminho	Significado e uso
`event`	Tipo do evento que seleciona a interpretação e os detalhes condicionais.
`flow_id`	Identificador do WhatsApp Flow a que o evento se refere.
`new_status`	Novo estado do Flow informado no evento de ciclo de vida.
`old_status`	Estado anterior do Flow; pode estar ausente no evento de criação.
`message`	Descrição textual do evento para diagnóstico.
`alert_state`	Estado de ativação ou recuperação do alerta técnico.
`threshold`	Limite técnico que originou o alerta de monitoramento.
`errors`	Erros condicionais associados ao evento ou à operação; interpretar código e detalhes.
`warning`	Aviso relativo ao Flow, incluindo expiração/congelamento de versão quando aplicável.

O que implementar no seu sistema

Use estes eventos para operação e monitoramento do Flow; processe respostas de formulários no campo messages.

Limites e cuidados deste campo

Resposta de um formulário concluído chega em messages com interactive.nfm_reply.response_json. Este campo não cria nem publica um Flow e não equivale ao produto HookCloud Flow.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Eventos de WhatsApp Flows ↗

group_lifecycle_updateCriação e exclusão de gruposAssinado no appGrupos

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Resultado de criação ou exclusão de um grupo da Groups API.

Quando a Meta pode emitir

Uma operação de criação ou exclusão de grupo produz resultado.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O Partner não implementa gerenciamento de grupos. Assinar o campo não torna o número elegível nem sincroniza grupos existentes no WhatsApp Business App.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`groups[].timestamp`	Timestamp do evento relativo ao grupo.
`groups[].group_id`	Identificador do grupo administrado pela Groups API.
`groups[].type`	Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor.
`groups[].request_id`	Identificador do pedido que originou o resultado, quando informado.
`groups[].subject`	Assunto/nome do grupo no resultado da criação.
`groups[].invite_link`	Link de convite retornado para o grupo criado.
`groups[].join_approval_mode`	Modo de aprovação de entrada configurado para o grupo.
`groups[].errors`	Erros da operação de grupo; podem coexistir com resultados parciais.

O que implementar no seu sistema

Correlacione request_id e group_id e verifique errors antes de considerar a operação concluída.

Limites e cuidados deste campo

type=group_create/group_delete; tratar resultados com errors. Assinatura não cria grupos nem torna número elegível à Groups API ou permite sincronizar grupos da coexistência.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Criação e exclusão de grupos ↗

group_participants_updateParticipantes de gruposAssinado no appGrupos

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Entradas, pedidos/cancelamentos de entrada, aprovações, remoções e saídas de participantes da Groups API.

Quando a Meta pode emitir

Uma pessoa entra, solicita/cancela entrada, recebe aprovação, é removida ou sai de um grupo.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O Partner não implementa gerenciamento de grupos. Assinar o campo não torna o número elegível nem sincroniza grupos existentes no WhatsApp Business App.

Como ler o payload

Campo / caminho	Significado e uso
`groups[].group_id`	Identificador do grupo administrado pela Groups API.
`groups[].type`	Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor.
`groups[].timestamp`	Timestamp do evento relativo ao grupo.
`groups[].join_request_id`	Identificador do pedido de entrada no grupo.
`groups[].wa_id`	Identidade WhatsApp do usuário associado ao pedido.
`groups[].added_participants`	Participantes adicionados com sucesso.
`groups[].removed_participants`	Participantes removidos ou que saíram, conforme a origem e o tipo.
`groups[].failed_participants`	Participantes para os quais a operação falhou, com detalhes de erro quando disponíveis.
`groups[].initiated_by`	Origem da mudança, como business ou participant.
`groups[].errors`	Erros da operação de grupo; podem coexistir com resultados parciais.

O que implementar no seu sistema

Interprete type e initiated_by; processe participantes bem-sucedidos e falhos separadamente quando o resultado for parcial.

Limites e cuidados deste campo

Resultados podem ser parciais. Um participante saindo e uma remoção pela empresa não são a mesma origem; interpretar initiated_by/type. Recurso depende de elegibilidade/configuração.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Participantes de grupos ↗

group_settings_updateConfigurações de gruposAssinado no appGrupos

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Resultado de alterações de configurações do grupo, como foto, assunto e descrição.

Quando a Meta pode emitir

Uma alteração de foto, assunto ou descrição do grupo produz resultado.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O Partner não implementa gerenciamento de grupos. Assinar o campo não torna o número elegível nem sincroniza grupos existentes no WhatsApp Business App.

Como ler o payload

Campo / caminho	Significado e uso
`groups[].group_id`	Identificador do grupo administrado pela Groups API.
`groups[].type`	Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor.
`groups[].request_id`	Identificador do pedido que originou o resultado, quando informado.
`groups[].timestamp`	Timestamp do evento relativo ao grupo.
`groups[].profile_picture`	Resultado da atualização de foto, incluindo update_successful e erro quando aplicável.
`groups[].group_subject`	Resultado da atualização de assunto, incluindo texto e update_successful.
`groups[].group_description`	Resultado da atualização de descrição, incluindo texto e update_successful.
`groups[].errors`	Erros da operação de grupo; podem coexistir com resultados parciais.

O que implementar no seu sistema

Leia update_successful e errors de cada configuração; não trate sucesso parcial como sucesso de todas as alterações.

Limites e cuidados deste campo

Cada configuração pode trazer update_successful e errors; alterações podem falhar parcialmente. Recurso depende de Groups API, não apenas da inscrição.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Configurações de grupos ↗

group_status_updateSuspensão de gruposAssinado no appGrupos

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Suspensão de um grupo administrado ou liberação dessa suspensão.

Quando a Meta pode emitir

Um grupo administrado é suspenso ou tem a suspensão retirada.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O Partner não implementa gerenciamento de grupos. Assinar o campo não torna o número elegível nem sincroniza grupos existentes no WhatsApp Business App.

Como ler o payload

Campo / caminho	Significado e uso
`groups[].group_id`	Identificador do grupo administrado pela Groups API.
`groups[].timestamp`	Timestamp do evento relativo ao grupo.
`groups[].type`	Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor.

O que implementar no seu sistema

Atualize o estado do grupo pelo type; mantenha esse estado separado de recibos de entrega/leitura de mensagens.

Limites e cuidados deste campo

type=group_suspend/group_suspend_cleared. Não é o status de entrega/leitura de mensagens do grupo; esses status pertencem ao campo messages.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Suspensão de grupos ↗

historyHistórico na coexistênciaAssinado no appCoexistência

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Histórico de conversas do WhatsApp Business App no onboarding em coexistência, ou indicação de compartilhamento recusado.

Quando a Meta pode emitir

O parceiro solicita a sincronização do histórico de um número em coexistência; a resposta depende da decisão de compartilhamento do titular.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O Partner não inicia automaticamente o pedido de histórico nem oferece uma importação pronta. A solicitação direta à Meta é separada da solicitação de contatos e depende de autorização do titular.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`history[].metadata.phase`	Fase da transferência de histórico; correlacione com os períodos documentados pela Meta.
`history[].metadata.chunk_order`	Ordem do bloco de histórico; blocos podem chegar fora de ordem.
`history[].metadata.progress`	Percentual de progresso da sincronização; 100 indica conclusão.
`history[].threads[].id`	Identificador da conversa histórica transferida.
`history[].threads[].messages`	Mensagens do bloco de histórico, que podem ser numerosas e exigir processamento assíncrono.
`errors`	Erros condicionais associados ao evento ou à operação; interpretar código e detalhes.

O que implementar no seu sistema

Prepare armazenamento/enfileiramento, processe fases e chunks fora de ordem e acompanhe progress sem confundir aceitação do pedido com conclusão.

Limites e cuidados deste campo

Requer pedido inicial separado e autorização do titular. A referência cobre até 180 dias, sem chats de grupo; mídia possui regras próprias. Chunks podem chegar fora de ordem e um webhook pode conter milhares de mensagens.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Histórico na coexistência ↗

message_echoesEchoes: contrato a confirmarNão assinado no appMensagens

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Campo de echoes de mensagens listado pela Meta como compatível com callback alternativo; contrato específico não confirmado nesta revisão.

Quando a Meta pode emitir

O disparador específico do campo separado message_echoes não foi confirmado nesta revisão.

Como chega à sua integração

Este campo estava NÃO ASSINADO no app em 19/10/2026; não espere entrega enquanto permanecer assim. Este campo admite callback alternativo por número segundo a Meta. Com assinatura, permissões, recurso e callback configurados, a Meta pode entregá-lo diretamente ao webhook global do seu sistema. O receptor deve interpretar o envelope Meta original. A inscrição, isoladamente, não comprova que a função esteja habilitada ou que um evento tenha sido entregue.

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O suporte ao callback alternativo está documentado; o esquema público específico deste campo não foi confirmado nesta revisão. Não reutilize por suposição o parser de smb_message_echoes.

Como ler o payload

Campo / caminho	Significado e uso
`object`	Objeto do webhook: whatsapp_business_account.
`entry[].id`	Identificador do ativo de origem no envelope. O contrato específico deste campo ainda precisa ser confirmado; não assumir que seja o ID do número.
`entry[].changes[].field`	Nome do campo de inscrição que identifica o tipo do evento.
`entry[].changes[].value`	Conteúdo específico do evento. Seu esquema interno não foi confirmado nesta revisão; não inferir chaves ou efeitos.

O que implementar no seu sistema

Não reutilize automaticamente o parser de smb_message_echoes ou standby.message_echoes; confirme o contrato antes de interpretar value.

Limites e cuidados deste campo

Não equiparar ao campo smb_message_echoes nem derivar esquema pelo nome. Conversation Routing também documenta echoes dentro de standby; isso não comprova que os contratos sejam idênticos.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Visão geral ou referência de roteamento da Meta; contrato específico não confirmado ↗

message_template_components_updateComponentes do templateAssinado no appTemplates

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Alteração de componentes de um template após edição.

Quando a Meta pode emitir

Um template existente é editado.

Como chega à sua integração

O que a HookCloud Partner faz

A HookCloud relaciona o evento à WABA e ao template, atualiza seu estado suportado e publica hookcloud.meta.template.updated aos endpoints habilitados inscritos. A reconciliação usa cache e controle de frequência. O evento pode trazer template_snapshot parcial ou pendência de consulta: não presuma que todo POST contenha os componentes completos.

Como ler o payload

Campo / caminho	Significado e uso
`message_template_id`	Identificador Meta do template afetado.
`message_template_name`	Nome do template afetado.
`message_template_language`	Idioma e localidade da versão do template afetada.
`message_template_element`	Texto do corpo do template informado na notificação de componentes.
`message_template_title`	Texto do cabeçalho quando o template possui cabeçalho textual.
`message_template_footer`	Texto do rodapé, quando o template possui esse componente.
`message_template_buttons`	Botões informados pelo evento, com tipo, rótulo e destino quando aplicável.

O que implementar no seu sistema

Correlacione o template por ID e idioma e confira seus componentes atuais antes de atualizar a apresentação.

Limites e cuidados deste campo

Título, rodapé e botões são condicionais. Não é resposta do usuário a um template.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Componentes do template ↗

message_template_quality_updateQualidade do templateAssinado no appTemplates

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudança na classificação de qualidade de um template.

Quando a Meta pode emitir

A classificação de qualidade de um template muda.

Como chega à sua integração

O que a HookCloud Partner faz

Como ler o payload

Campo / caminho	Significado e uso
`previous_quality_score`	Classificação anterior de qualidade do template.
`new_quality_score`	Nova qualidade: GREEN, YELLOW, RED ou UNKNOWN.
`message_template_id`	Identificador Meta do template afetado.
`message_template_name`	Nome do template afetado.
`message_template_language`	Idioma e localidade da versão do template afetada.

O que implementar no seu sistema

Mantenha a qualidade em atributo separado do status de aprovação e correlacione a alteração com o template correto.

Limites e cuidados deste campo

Qualidade do template: GREEN, YELLOW, RED ou UNKNOWN; não é qualidade geral do número.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Qualidade do template ↗

message_template_status_updateEstado do templateAssinado no appTemplates

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudanças no estado do template, incluindo aprovação, rejeição, pausa, desativação e arquivamento.

Quando a Meta pode emitir

Um template muda de estado, por exemplo aprovação, rejeição, pausa, desativação ou arquivamento.

Como chega à sua integração

O que a HookCloud Partner faz

Como ler o payload

Campo / caminho	Significado e uso
`event`	Tipo do evento que seleciona a interpretação e os detalhes condicionais.
`message_template_id`	Identificador Meta do template afetado.
`message_template_name`	Nome do template afetado.
`message_template_language`	Idioma e localidade da versão do template afetada.
`reason`	Motivo associado ao evento, especialmente em rejeições.
`message_template_category`	Categoria do template informada junto ao evento de status.
`disable_info`	Informações condicionais da desativação, como disable_date.
`other_info`	Detalhes condicionais de estados como pausa/despausa, incluindo título e descrição.
`rejection_info`	Motivo detalhado e recomendação quando a rejeição inclui esses dados.

O que implementar no seu sistema

Atualize o estado conforme event e use reason e objetos condicionais para explicar a decisão.

Limites e cuidados deste campo

Campos de detalhe variam com event/reason; aprovação não comprova entrega de uma mensagem.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Estado do template ↗

messagesMensagens e statusAssinado no appMensagens

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mensagens recebidas e status de mensagens enviadas, incluindo entrega/leitura/falha e tipos específicos de conteúdo.

Quando a Meta pode emitir

A Meta recebe uma mensagem destinada à empresa ou emite status/eventos compatíveis relativos a uma mensagem.

Como chega à sua integração

O que a HookCloud Partner faz

As mensagens e os status elegíveis chegam diretamente da Meta ao webhook do assinante configurado no número. Seu sistema deve armazenar e processar o conteúdo. O painel Saúde de Entregas depende também do envio dos recibos documentados à HookCloud; não suponha que a HookCloud leu automaticamente o POST entregue ao seu servidor.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`contacts`	Identidade/perfil associados à mensagem; não representa sincronização da agenda do WhatsApp Business.
`messages[].id`	Identificador da mensagem recebida; útil para correlação e deduplicação.
`messages[].type`	Tipo do conteúdo, que determina qual objeto de mensagem processar.
`statuses[].id`	ID da mensagem enviada a que este status se refere; use para reconciliar com o retorno do envio.
`statuses[].status`	Estado da mensagem, por exemplo sent, delivered, read ou failed. Aceitação do envio não equivale a entrega; trate status repetidos ou fora de ordem.
`errors`	Erros condicionais associados ao evento ou à operação; interpretar código e detalhes.
`user_actions[]`	Ações de marketing quando o recurso está disponível, incluindo cliques e landing page views; diferenciar por action_type.
`contacts[].profile.name`	Nome de perfil informado na conversa; não é necessariamente o nome salvo pela empresa em sua agenda.
`contacts[].user_id`	BSUID do usuário, quando presente. Preserve como string e associe ao escopo comercial da conexão.
`messages[].from`	Identificador baseado no telefone do remetente quando disponibilizado; pode não estar presente em cenários que usam username.
`messages[].from_user_id`	BSUID do remetente quando presente; permite identificar o usuário sem depender da exposição do telefone.
`statuses[].recipient_id`	Identificador do destinatário baseado no telefone, quando disponibilizado.
`statuses[].recipient_user_id`	BSUID do destinatário quando presente no status; correlacione com o id da mensagem e o escopo comercial.
`statuses[].errors[]`	Erros da tentativa de entrega, quando status indica falha; interprete code, title e detalhes sem converter toda falha em banimento.
`messages[].interactive.nfm_reply.response_json`	Respostas de um formulário WhatsApp Flow concluído. É conteúdo de messages, não o evento administrativo flows.

O que implementar no seu sistema

Percorra todos os itens, diferencie messages, statuses, user_actions e errors quando presentes, e deduplique pelos identificadores aplicáveis.

Limites e cuidados deste campo

statuses é conteúdo do payload, não campo de inscrição separado. Percorrer todos entry[]/changes[] e tratar payloads sem messages[]. Identificadores de telefone podem ser condicionais ao uso de usernames/BSUID.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

messaging_handoversTransferência de controle da conversaNão assinado no appRoteamento de conversas

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudança de proprietário da conversa em Conversation Routing: controle passado ou tomado.

Quando a Meta pode emitir

O proprietário passa o controle para outro respondente ou o parceiro de escalonamento toma o controle.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. Não há orquestração automática de propriedade de conversas pelo Partner. Seu sistema deve respeitar o papel recebido antes de responder.

Como ler o payload

Campo / caminho	Significado e uso
`messaging_product`	Produto do evento; whatsapp neste contrato.
`sender.phone_number`	Número do usuário da conversa; pode estar ausente quando indisponível.
`recipient.phone_number_id`	ID do número comercial a que pertence a conversa.
`recipient.display_phone_number`	Número comercial em formato de exibição.
`type`	Notificação control_passed para o novo proprietário ou control_taken para o proprietário anterior.
`timestamp`	Horário da alteração ou evento, em timestamp Unix conforme a referência.
`control_passed`	Objeto condicional presente quando a notificação informa controle recebido por passagem.
`control_taken`	Objeto condicional presente quando o respondente perde controle por tomada do parceiro de escalonamento.
`control_passed.previous_owner_role`	Papel do respondente que passou o controle, quando informado.
`control_passed.new_owner_role`	Papel do respondente que recebeu o controle, quando informado.
`control_taken.previous_owner_role`	Papel do respondente que perdeu o controle, quando informado.
`control_taken.new_owner_role`	Papel do novo proprietário; escalation nos casos documentados.

O que implementar no seu sistema

Atualize a propriedade local usando roles quando presentes; ao perder o controle, interrompa respostas que dependam de ser o proprietário.

Limites e cuidados deste campo

control_passed chega ao novo proprietário; control_taken ao proprietário anterior. release não produz esse evento. Preferir roles; previous_owner_app_id/previous_owner_app_role estão depreciados. Campos internos são condicionais.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Transferência de controle da conversa ↗

partner_solutionsSoluções com múltiplos parceirosAssinado no appParcerias Meta

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudanças no estado de uma Multi-Partner Solution: rascunho, convite, aceitação, rejeição ou desativação.

Quando a Meta pode emitir

Uma Multi-Partner Solution é criada, enviada, aceita, rejeitada ou passa pelo processo de desativação.

Como chega à sua integração

O que a HookCloud Partner faz

Como ler o payload

Campo / caminho	Significado e uso
`event`	Tipo do evento que seleciona a interpretação e os detalhes condicionais.
`solution_id`	Identificador da Multi-Partner Solution.
`solution_status`	Estado da solução, como DRAFT, INITIATED, ACTIVE, REJECTED, PENDING_DEACTIVATION ou DEACTIVATED.

O que implementar no seu sistema

Correlacione solution_id e solution_status; preserve a distinção entre solução Meta e assinatura comercial HookCloud.

Limites e cuidados deste campo

event=SOLUTION_CREATED/SOLUTION_UPDATED. entry.id nesta referência é o business portfolio ID; não assumir que todo entry.id seja WABA/Phone Number ID. Não é webhook genérico da assinatura paga HookCloud Partner.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Soluções com múltiplos parceiros ↗

payment_configuration_updateConfiguração de gateway de pagamentosAssinado no appPagamentos no WhatsApp

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudanças na configuração de gateway para Payments API India e Payments API Brazil: conexão, desconexão e ativação.

Quando a Meta pode emitir

Uma configuração da Payments API é conectada, desconectada ou ativada após teste.

Como chega à sua integração

O que a HookCloud Partner faz

A HookCloud registra o evento como informativo e pode agendar uma reconciliação controlada. Ele não confirma cartão de faturamento, saldo nem liberação de envio e não apaga sozinho uma pendência de pagamento. O gateway de pagamentos do WhatsApp não é a cobrança da assinatura HookCloud.

Como ler o payload

Campo / caminho	Significado e uso
`configuration_name`	Nome da configuração de pagamento usada em operações da Payments API.
`provider_name`	Nome do gateway/provedor associado à configuração.
`provider_mid`	Identificador da conta do comerciante no gateway.
`status`	Estado da configuração do gateway: Active, Needs Connecting ou Needs Testing.
`created_timestamp`	Timestamp de criação da configuração de pagamento.
`updated_timestamp`	Timestamp da última atualização da configuração de pagamento.

O que implementar no seu sistema

Atualize o estado da configuração identificada por configuration_name; não confirme cartão Meta, saldo, venda ou recuperação de cobrança com esse evento.

Limites e cuidados deste campo

status=Active/Needs Connecting/Needs Testing. É configuração de gateway de pagamentos no WhatsApp, não cartão de faturamento Meta, saldo da WABA, cobrança da assinatura HookCloud ou confirmação de cada compra.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Configuração de gateway de pagamentos ↗

phone_number_name_updateNome de exibiçãoAssinado no appIdentidade do número

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Resultado da análise do nome de exibição solicitado para o número.

Quando a Meta pode emitir

A Meta analisa o nome de um novo número ou a edição de um nome anteriormente aprovado.

Como chega à sua integração

O que a HookCloud Partner faz

O evento chega ao callback administrativo da HookCloud. O Partner interpreta apenas os casos suportados, relacionando a WABA e o número à instância correta. Não há encaminhamento genérico do JSON Meta original para o assinante. Mudanças de estado confirmadas podem produzir os eventos HookCloud documentados, como hookcloud.instance.health_updated e hookcloud.customer.risk_updated; não existe correspondência de um evento HookCloud para cada POST da Meta. A HookCloud relaciona a decisão ao número e reconcilia o nome aprovado; quando confirmado, o nome da instância é sincronizado. Não use o nome solicitado como se já tivesse sido aprovado.

Como ler o payload

Campo / caminho	Significado e uso
`display_phone_number`	Número comercial de exibição ao qual o evento se refere.
`decision`	Resultado da análise: APPROVED, REJECTED, PENDING ou DEFERRED, conforme a referência do campo.
`requested_verified_name`	Nome de exibição submetido à análise; pode diferir do nome atualmente aprovado.
`rejection_reason`	Motivo da rejeição do nome, quando houve rejeição.

O que implementar no seu sistema

Mostre o nome solicitado e a decisão sem substituir automaticamente um nome aprovado por uma solicitação rejeitada.

Limites e cuidados deste campo

decision pode ser APPROVED, DEFERRED, PENDING ou REJECTED. Não é mudança no username comercial.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Nome de exibição ↗

phone_number_quality_updateThroughput e limites do númeroAssinado no appConta e capacidade

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Atualizações de throughput e eventos/limites relacionados ao número, conforme o payload da Meta.

Quando a Meta pode emitir

A Meta comunica eventos de throughput e limites descritos na referência do campo.

Como chega à sua integração

O que a HookCloud Partner faz

O evento chega ao callback administrativo da HookCloud. O Partner interpreta apenas os casos suportados, relacionando a WABA e o número à instância correta. Não há encaminhamento genérico do JSON Meta original para o assinante. Mudanças de estado confirmadas podem produzir os eventos HookCloud documentados, como hookcloud.instance.health_updated e hookcloud.customer.risk_updated; não existe correspondência de um evento HookCloud para cada POST da Meta. O registro de risco RED depende de evidência explícita de qualidade RED; eventos de onboarding, throughput ou aumento de limite não contam automaticamente como infração.

Como ler o payload

Campo / caminho	Significado e uso
`display_phone_number`	Número comercial de exibição ao qual o evento se refere.
`event`	Tipo do evento que seleciona a interpretação e os detalhes condicionais.
`max_daily_conversations_per_business`	Limite de mensagens/capacidade do portfólio informado no evento; interpretar o valor conforme a versão vigente.
`old_limit`	Campo legado do limite anterior; a referência marca sua remoção.
`current_limit`	Campo legado do limite atual/throughput; não deve substituir o campo recomendado vigente.

O que implementar no seu sistema

Interprete event e os limites presentes; não converta um evento de onboarding ou upgrade em incidente de qualidade.

Limites e cuidados deste campo

A descrição atual enfatiza throughput e eventos ONBOARDING/THROUGHPUT_UPGRADE. Não prometer evento para toda mudança de qualidade GREEN/YELLOW/RED. old_limit/current_limit estão marcados para remoção na referência.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Throughput e limites do número ↗

securityPIN e verificação em duas etapasAssinado no appSegurança

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Eventos de configuração de segurança do número: PIN alterado, pedido de desativação de verificação em duas etapas e conclusão do procedimento.

Quando a Meta pode emitir

Alguém altera/habilita o PIN, pede a desativação da verificação em duas etapas ou conclui o procedimento.

Como chega à sua integração

O que a HookCloud Partner faz

A HookCloud mostra explicações de segurança no Portal/Admin e associa o evento ao número correto. PIN_CHANGED é informativo; pedidos e conclusões de desativação são tratados segundo seu significado. PIN_RESET_SUCCESS aparece como redefinição concluída, sem afirmar banimento ou o estado atual do PIN. Não existe um evento público genérico que replique todo payload security ao assinante.

Como ler o payload

Campo / caminho	Significado e uso
`display_phone_number`	Número comercial de exibição ao qual o evento se refere.
`event`	PIN_CHANGED: alteração/ativação do PIN; PIN_RESET_REQUEST: solicitação de desativação da verificação em duas etapas; PIN_REQUEST_SUCCESS: conclusão da desativação, conforme a referência. O Partner também reconhece PIN_RESET_SUCCESS como redefinição concluída, sem deduzir banimento ou estado atual do PIN.
`requester`	ID do usuário do Meta Business Suite que solicitou a redefinição/desativação, quando incluído.

O que implementar no seu sistema

Associe o evento ao número exato e diferencie mudança informativa de PIN de uma solicitação de desativação.

Limites e cuidados deste campo

Eventos PIN_CHANGED, PIN_RESET_REQUEST e PIN_REQUEST_SUCCESS; requester é condicional. Não é detector genérico de fraude ou banimento.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: PIN e verificação em duas etapas ↗

smb_app_state_syncContatos na coexistênciaAssinado no appCoexistência

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Sincronização inicial e alterações de contatos do WhatsApp Business App em coexistência.

Quando a Meta pode emitir

Uma solicitação inicial bem-sucedida sincroniza contatos; adições, edições e remoções posteriores do WhatsApp Business App também geram eventos.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O Partner ainda não inicia automaticamente o POST smb_app_data e não possui endpoint de importação de contatos. É necessário preparar a integração direta com a Meta e o recebimento antes da janela inicial de 24 horas.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`state_sync[].type`	Tipo do estado sincronizado; contact para os contatos documentados.
`state_sync[].contact.full_name`	Nome completo do contato no WhatsApp Business App; pode faltar na remoção.
`state_sync[].contact.first_name`	Primeiro nome do contato; pode faltar na remoção.
`state_sync[].contact.phone_number`	Número WhatsApp do contato sincronizado.
`state_sync[].action`	add para inclusão ou edição; remove para remoção.
`state_sync[].metadata.timestamp`	Horário em que a alteração de contato gerou o evento.

O que implementar no seu sistema

Faça upsert em action=add, remova em action=remove e use o escopo do número com o identificador do contato, nunca o nome como chave.

Limites e cuidados deste campo

Inicialização separada necessária. action=add também representa edição; remove pode omitir nomes. Não presumir que qualquer mudança na agenda do sistema operacional gera evento.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Contatos na coexistência ↗

smb_message_echoesMensagens do WhatsApp Business AppAssinado no appCoexistência

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Cópias de mensagens enviadas, editadas ou removidas pelo WhatsApp Business App ou dispositivo vinculado compatível em coexistência.

Quando a Meta pode emitir

A empresa envia, edita ou remove uma mensagem pelo aplicativo WhatsApp Business ou dispositivo vinculado compatível.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. O nome da inscrição é smb_message_echoes, mas a lista recebida chama-se message_echoes. Preserve essa distinção no parser.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`message_echoes[].id`	Identificador da mensagem enviada pelo aplicativo ou dispositivo vinculado.
`message_echoes[].from`	Número comercial que enviou a mensagem.
`message_echoes[].to`	Identificador/número do destinatário conforme o contrato da mensagem.
`message_echoes[].timestamp`	Horário do evento da mensagem espelhada.
`message_echoes[].type`	Tipo da mensagem, incluindo edit ou revoke quando aplicável.

O que implementar no seu sistema

Correlacione cada echo pelo ID e tipo da mensagem; diferencie envio original, edição e remoção.

Limites e cuidados deste campo

Campo de inscrição smb_message_echoes contém array message_echoes. É diferente do campo de inscrição message_echoes; não confundir nome do array com nome do campo.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Mensagens do WhatsApp Business App ↗

standbyObservação passiva da conversaNão assinado no appRoteamento de conversas

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Atividade da conversa observada passivamente quando outro respondente controla o thread em Conversation Routing.

Quando a Meta pode emitir

Há atividade em uma conversa controlada por outro respondente e a empresa concedeu visibilidade standby ao app.

Como chega à sua integração

O que a HookCloud Partner faz

A entrega elegível é feita pela Meta ao callback do número; o Partner não importa nem transforma este conteúdo em eventos HookCloud. Seu sistema precisa implementar o recebimento, a persistência e a apresentação. Receber o campo no callback administrativo da HookCloud não o transforma em encaminhamento automático. Visibilidade passiva não concede controle da conversa nem autorização para responder como proprietário.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`standby.contacts`	Identidade/perfil do remetente em uma mensagem observada passivamente.
`standby.messages`	Mensagens recebidas na conversa controlada por outro respondente.
`standby.message_echoes[].id`	Identificador da mensagem enviada por outro respondente.
`standby.message_echoes[].timestamp`	Horário em que o outro respondente enviou a mensagem.
`standby.message_echoes[].message`	Parâmetros exatos enviados à API de mensagens; não presumir conteúdo já renderizado.
`standby.message_echoes[].template`	Definição opcional do template com placeholders, separada dos valores usados no envio.
`standby.message_echoes[].flow`	Definição opcional do Flow associado ao echo.
`standby.statuses`	Recibos de mensagens enviadas por outro respondente.

O que implementar no seu sistema

Armazene contexto e recibos conforme o contrato; não responda automaticamente sem a propriedade ou o papel de escalonamento aplicável.

Limites e cuidados deste campo

Requer inscrição e visibilidade standby concedida pela empresa; fica desativado por padrão. Não responder automaticamente sem propriedade do thread ou papel autorizado de escalonamento. O echo contém parâmetros de envio, e um template pode incluir definição ainda com placeholders; não presumir texto renderizado. Não envia echoes das próprias mensagens.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Observação passiva da conversa ↗

template_category_updateCategoria do templateAssinado no appTemplates

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Mudança futura ou concluída na categoria de um template.

Quando a Meta pode emitir

A Meta anuncia uma mudança futura de categoria ou informa uma mudança concluída, automática ou manual.

Como chega à sua integração

O que a HookCloud Partner faz

Como ler o payload

Campo / caminho	Significado e uso
`message_template_id`	Identificador Meta do template afetado.
`message_template_name`	Nome do template afetado.
`message_template_language`	Idioma e localidade da versão do template afetada.
`correct_category`	Categoria identificada pela Meta como correta; interpretar a distinção entre aviso e mudança efetiva.
`new_category`	Categoria nova em mudança concluída; em aviso antecipado, ainda representa a categoria atual.
`category_update_timestamp`	Timestamp Unix agendado para aplicar a categoria indicada em correct_category.
`previous_category`	Categoria anterior em uma notificação de mudança já concluída.

O que implementar no seu sistema

Diferencie mudança agendada de mudança concluída; na primeira, new_category ainda descreve a categoria atual.

Limites e cuidados deste campo

Na notificação de mudança futura, new_category ainda é a categoria atual; correct_category é o destino e category_update_timestamp informa quando mudará. Em mudança concluída, interpretar previous_category/new_category.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Categoria do template ↗

template_correct_category_detectionDetecção de categoria incorretaAssinado no appTemplates

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Detecção de uso incorreto de categoria em templates do Direct Send, com a categoria identificada pela Meta.

Quando a Meta pode emitir

A Meta detecta uso incorreto de categoria em um template Direct Send.

Como chega à sua integração

O que a HookCloud Partner faz

A HookCloud preserva este evento para diagnóstico, mas o marca como não interpretado e não aplica efeitos operacionais. Não emite hookcloud.meta.template.updated nem altera categoria apenas por esta detecção. Ele não substitui template_category_update.

Como ler o payload

Campo / caminho	Significado e uso
`message_template_id`	Identificador Meta do template afetado.
`message_template_name`	Nome do template afetado.
`message_template_language`	Idioma e localidade da versão do template afetada.
`category`	Categoria usada originalmente pelo template; o exemplo Direct Send documenta UTILITY.
`correct_category`	Categoria que a Meta detectou como correta; para Direct Send, a referência verificada documenta MARKETING.

O que implementar no seu sistema

Identifique o template e examine a categoria detectada; não trate o aviso como confirmação de alteração já aplicada.

Limites e cuidados deste campo

A página Direct Send verificada mostra category=UTILITY e correct_category=MARKETING. Não equivale a template_category_update nem comprova mudança já aplicada. O recurso Direct Send não é habilitado somente por assinar o campo.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Detecção de categoria incorreta ↗

tracking_eventsTracking: contrato a confirmarAssinado no appMedição

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Campo observado no inventário do app; contrato público específico não confirmado nesta revisão.

Quando a Meta pode emitir

O disparador público específico deste campo não foi confirmado nesta revisão.

Como chega à sua integração

O que a HookCloud Partner faz

A HookCloud não implementa um produto ou parser específico para este campo no serviço administrativo atual. Se ele chegar ao callback global do app, é ignorado para efeitos operacionais, sem criar estado nem ser retransmitido automaticamente. Não dependa de um webhook HookCloud equivalente. O contrato específico permanece não confirmado nesta revisão; não equivale a métricas de mensagens nem a eventos de cliques documentados dentro de messages.

Como ler o payload

Campo / caminho	Significado e uso
`object`	Objeto do webhook: whatsapp_business_account.
`entry[].id`	Identificador do ativo de origem no envelope. O contrato específico deste campo ainda precisa ser confirmado; não assumir que seja o ID do número.
`entry[].changes[].field`	Nome do campo de inscrição que identifica o tipo do evento.
`entry[].changes[].value`	Conteúdo específico do evento. Seu esquema interno não foi confirmado nesta revisão; não inferir chaves ou efeitos.

O que implementar no seu sistema

Não deduza métricas ou conversões pelo nome; eventos de clique e landing page documentados usam messages/user_actions.

Limites e cuidados deste campo

Não atribuir automaticamente métricas, anúncios, pixel ou Conversions API a esse campo. As referências oficiais verificadas de cliques e landing page views de marketing usam field=messages com value.user_actions[], não tracking_events. Nenhum esquema específico de tracking_events foi confirmado.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

user_preferencesPreferências de marketingAssinado no appPreferências

Versão da assinatura: v26.0 · Link deste campo

Para que serve

Preferência do usuário para parar ou retomar mensagens de marketing.

Quando a Meta pode emitir

Um usuário decide parar ou retomar mensagens de marketing da empresa.

Como chega à sua integração

O que a HookCloud Partner faz

Quando category=marketing_messages e value=stop/resume, a HookCloud sanitiza os dados, exige correspondência exata com a instância atual e publica hookcloud.meta.user_preferences.updated aos endpoints habilitados que assinam esse evento. Não distribui a preferência para todos os números da WABA. O contrato normalizado mantém wa_id e/ou user_id, categoria, valor e timestamp; não promete todos os campos opcionais do original Meta.

Como ler o payload

Campo / caminho	Significado e uso
`metadata.phone_number_id`	ID do número comercial associado ao evento; use-o para determinar o escopo.
`contacts`	Identidade/perfil associados à mensagem; não representa sincronização da agenda do WhatsApp Business.
`user_preferences[].wa_id`	Identidade WhatsApp do usuário quando disponível; pode ser omitida em cenários de username.
`user_preferences[].user_id`	Identidade do usuário com escopo comercial (BSUID), quando habilitada.
`user_preferences[].parent_user_id`	Parent BSUID para identificação; não é o nível de aplicação da preferência.
`user_preferences[].category`	Categoria da preferência; a referência documenta marketing_messages.
`user_preferences[].value`	Escolha do usuário: stop para parar ou resume para retomar marketing.
`user_preferences[].detail`	Descrição da escolha de parar ou retomar as mensagens.
`user_preferences[].timestamp`	Timestamp Unix da atualização de preferência.

O que implementar no seu sistema

Aplique stop/resume à identidade e ao escopo correto; não use parent_user_id para aplicar uma preferência a todas as identidades relacionadas.

Limites e cuidados deste campo

category=marketing_messages; value=stop/resume. Não dispara para Interested/Not interested em Offers and announcements. Identificadores são condicionais; parent_user_id serve somente à identificação, não aplica preferências no nível parent BSUID.
A existência ou assinatura do campo não comprova implementação, elegibilidade, inicialização, entrega nem armazenamento pelo HookCloud Partner.

Referências oficiais

Referência oficial da Meta: Preferências de marketing ↗

Coexistência: eventos do aplicativo WhatsApp Business

Na coexistência, contatos, histórico e mensagens enviadas pelo WhatsApp Business App usam contratos distintos: smb_app_state_sync, history e smb_message_echoes.

O HookCloud Partner não possui nesta implementação uma rota de importação de contatos nem inicia automaticamente o pedido de smb_app_data. Os passos abaixo descrevem uma operação direta na Graph API da Meta por um backend autorizado para a própria conexão.

Assinar smb_app_state_sync ou conectar o número não inicia a carga de contatos. A solicitação inicial deve ser feita uma vez dentro de 24 horas após o onboarding; o prazo pertence à inicialização, não ao fim das alterações futuras.

A origem são contatos do WhatsApp Business App que possuem número WhatsApp. A presença de contacts em uma mensagem comum descreve o remetente e não comprova sincronização da agenda.

Mantenha o nome salvo do contato separado do nome de perfil recebido em contacts[].profile.name. Uma atualização de perfil não deve sobrescrever automaticamente o nome que a empresa atribuiu ao cliente.

Coexistência e contatos: sequência para sua integração

Prepare a recepção e confirme a conexão
Confirme coexistência, autorização, inscrição no campo e callback efetivo do número/WABA. O receptor deve percorrer entry[].changes[], reconhecer field=smb_app_state_sync, guardar/enfileirar value.state_sync e responder HTTP 200.
Solicite os contatos diretamente à Graph API
Dentro das 24 horas após o onboarding, o backend autorizado usa o Phone Number ID e a credencial daquela conexão. Este endpoint pertence à Meta; não é uma rota do HookCloud Partner. Preserve o request_id retornado.
http
```
POST https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/smb_app_data
Authorization: Bearer <TOKEN_DA_CONEXAO_NO_BACKEND>
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "sync_type": "smb_app_state_sync"
}
```
Aplique a carga e as alterações posteriores
Após a inicialização bem-sucedida, a Meta envia os contatos elegíveis e passa a notificar mudanças. Em state_sync[], action=add cobre inclusão e edição; action=remove pode omitir nomes. Use o escopo do número e o identificador do contato para aplicar alterações idempotentes.
Solicite histórico separadamente, se autorizado
O histórico usa o mesmo endpoint da Meta com sync_type=history. Aceitação do pedido não significa autorização de compartilhamento nem conclusão. A recusa pode produzir o código 2593109. Contatos e histórico não substituem um ao outro.
Investigue sem reiniciar a conexão como teste
Confira horário, request_id ou erro da solicitação inicial, Phone Number ID, inscrição, callback e logs do receptor. Depois do prazo, trocar a URL ou marcar o campo não reabre a janela. A Meta prevê offboarding e novo Embedded Signup para repetir; isso exige preparar o fluxo e avaliar o impacto com o responsável, em vez de desconectar para teste.

Contratos HookCloud e assinaturas · Mensagens e Graph API · Catálogo da Partner API