{ "title": "Campos de webhook do app Meta", "updated_at": "2026-10-19", "app": { "id": "1046505108355448", "name": "HookCloud Partner", "graph_version": "v26.0", "verification_status": "Conferido no Meta Developers: 30 campos assinados e 3 não assinados", "verified_at": "2026-10-19T21:39:29.935Z", "scope_note": "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." }, "overview": "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.", "rules": [ "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." ], "routing": [ { "id": "phone", "title": "Callback alternativo do número", "description": "Para campos compatíveis, a Meta verifica primeiro o callback alternativo do número comercial associado ao evento." }, { "id": "waba", "title": "Callback alternativo da WABA", "description": "Quando não existe callback alternativo do número, a Meta consulta o callback alternativo da Messaging account/WABA." }, { "id": "app", "title": "Callback padrão do app", "description": "É 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." }, { "id": "partner", "title": "Tratamento pelo HookCloud Partner", "description": "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." } ], "coexistence": { "paragraphs": [ "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." ], "steps": [ { "title": "Prepare a recepção e confirme a conexão", "description": "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." }, { "title": "Solicite os contatos diretamente à Graph API", "description": "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.", "code": "POST https://graph.facebook.com/v26.0//smb_app_data\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"messaging_product\": \"whatsapp\",\n \"sync_type\": \"smb_app_state_sync\"\n}" }, { "title": "Aplique a carga e as alterações posteriores", "description": "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." }, { "title": "Solicite histórico separadamente, se autorizado", "description": "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." }, { "title": "Investigue sem reiniciar a conexão como teste", "description": "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." } ], "references": [ { "title": "Meta: onboarding e sincronização na coexistência", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/" }, { "title": "Meta: contrato de contatos smb_app_state_sync", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/smb_app_state_sync/" }, { "title": "Meta: contrato de histórico", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/history/" }, { "title": "Meta: callbacks alternativos", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override/" } ] }, "fields": [ { "id": "account_alerts", "title": "Alertas da conta", "category": "Conta e capacidade", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Alertas sobre limites de mensagens, foto de perfil e status de conta comercial oficial (OBA).", "trigger": "A Meta decide ou solicita informação sobre limites, altera o reconhecimento OBA ou remove a foto comercial.", "payload": [ { "name": "entity_type", "description": "Tipo do ativo ao qual o alerta se refere; determina como interpretar entity_id." }, { "name": "entity_id", "description": "Identificador do ativo afetado; não presumir que seja sempre o ID do número." }, { "name": "alert_info.alert_severity", "description": "Severidade atribuída ao alerta pela Meta." }, { "name": "alert_info.alert_status", "description": "Estado do alerta conforme o evento produzido pela Meta." }, { "name": "alert_info.alert_type", "description": "Tipo do alerta, usado para selecionar a interpretação." }, { "name": "alert_info.alert_description", "description": "Descrição do alerta e, quando fornecida, orientação sobre a causa ou ação." } ], "action": "Leia alert_info antes de criar um alerta operacional; associe entity_type e entity_id ao ativo correto.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Alertas da conta", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/account_alerts/" } ] }, { "id": "account_review_update", "title": "Análise da conta", "category": "Conta e capacidade", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Resultado da análise da conta WhatsApp contra políticas da Meta, entregue pela Messaging account associada.", "trigger": "A análise da conta resulta em aprovação, rejeição, decisão pendente ou decisão adiada.", "payload": [ { "name": "decision", "description": "Resultado da análise: APPROVED, REJECTED, PENDING ou DEFERRED, conforme a referência do campo." } ], "action": "Atualize o estado de análise separadamente da verificação da empresa e das permissões do aplicativo.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Análise da conta", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/account_review_update/" } ] }, { "id": "account_settings_update", "title": "Configurações de chamadas", "category": "Chamadas", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Atualizações de configurações do número; atualmente a referência cobre configurações de chamadas selecionadas.", "trigger": "Muda uma configuração de chamada observada pela Meta, inclusive quando a própria integração fez a alteração.", "payload": [ { "name": "messaging_product", "description": "Produto do evento; whatsapp neste contrato." }, { "name": "timestamp", "description": "Horário da alteração ou evento, em timestamp Unix conforme a referência." }, { "name": "type", "description": "Tipo de mudança de configuração; atualmente PHONE_NUMBER_SETTINGS." }, { "name": "phone_number_settings.phone_number_id", "description": "ID do número cuja configuração de chamada foi alterada." }, { "name": "phone_number_settings.calling", "description": "Configurações de chamadas informadas; somente alguns atributos são observados pela Meta." } ], "action": "Leia type e phone_number_settings, compare somente as configurações presentes e evite ciclos causados pelos próprios updates.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Configurações de chamadas", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/call-settings/" } ] }, { "id": "account_update", "title": "Atualizações da conta", "category": "Conta e capacidade", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "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.", "trigger": "Ocorre um dos eventos administrativos documentados: vínculo com parceiro, política, termos, verificação, desconexão ou reconexão.", "payload": [ { "name": "event", "description": "Tipo do evento que seleciona a interpretação e os detalhes condicionais." }, { "name": "phone_number", "description": "Número comercial informado quando o evento diz respeito a um único número." }, { "name": "country", "description": "País informado no evento de atualização da localização comercial principal." }, { "name": "waba_info", "description": "Informações da conta, portfólio ou conta de anúncios, presentes somente nos eventos correspondentes." }, { "name": "violation_info", "description": "Detalhes da violação identificada pela Meta, quando este for o tipo de evento." }, { "name": "ban_info", "description": "Detalhes condicionais do estado/data de banimento nos eventos aplicáveis." }, { "name": "restriction_info", "description": "Restrições e dados adicionais, como expiração ou orientação, quando fornecidos." }, { "name": "auth_international_rate_eligibility", "description": "Elegibilidade e exceções de preço de autenticação internacional, quando aplicável." }, { "name": "volume_tier_info", "description": "Dados de atualização da faixa de preço por volume, quando o evento a descreve." } ], "action": "Selecione a interpretação por event e confirme o escopo antes de alterar o estado de uma conexão.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Atualizações da conta", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/account_update/" } ] }, { "id": "automatic_events", "title": "Leads e compras automáticos", "category": "Medição", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "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.", "trigger": "A Meta detecta LeadSubmitted ou Purchase em uma conversa de anúncio Click to WhatsApp com Automatic Events reporting habilitado.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "automatic_events[].id", "description": "Identificador WhatsApp da mensagem associada à detecção automática." }, { "name": "automatic_events[].event_name", "description": "Tipo detectado: LeadSubmitted ou Purchase." }, { "name": "automatic_events[].timestamp", "description": "Timestamp Unix em que o evento automático foi disparado." }, { "name": "automatic_events[].ctwa_clid", "description": "Identificador do clique Click to WhatsApp; pode estar ausente para anúncios em Status." }, { "name": "automatic_events[].custom_data.currency", "description": "Moeda da compra; presente nos eventos de compra aplicáveis." }, { "name": "automatic_events[].custom_data.value", "description": "Valor da compra na escala documentada pela Meta: preço multiplicado por 1000." } ], "action": "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.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Leads e compras automáticos", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/automatic_events/" } ] }, { "id": "business_capability_update", "title": "Capacidades e limites", "category": "Conta e capacidade", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mudanças de capacidades da hierarquia de contas ou do portfólio, como limites de mensagens e números.", "trigger": "Uma conta é criada ou uma capacidade do portfólio/hierarquia de contas aumenta ou diminui.", "payload": [ { "name": "max_daily_conversations_per_business", "description": "Limite de mensagens/capacidade do portfólio informado no evento; interpretar o valor conforme a versão vigente." }, { "name": "max_phone_numbers_per_business", "description": "Limite de números do portfólio, incluído apenas nas condições previstas pela Meta." }, { "name": "max_phone_numbers_per_waba", "description": "Limite de números na hierarquia da conta, quando informado." }, { "name": "max_daily_conversation_per_phone", "description": "Campo legado de limite por telefone; a referência recomenda max_daily_conversations_per_business." } ], "action": "Atualize somente os limites presentes e confirme valores atuais pela API quando a operação depender deles.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Capacidades e limites", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/business_capability_update/" } ] }, { "id": "business_status_update", "title": "Estado comercial: contrato a confirmar", "category": "Conta e capacidade", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Campo observado no inventário do app; contrato público específico não confirmado nesta revisão.", "trigger": "O disparador público específico deste campo não foi confirmado nesta revisão.", "payload": [ { "name": "object", "description": "Objeto do webhook: whatsapp_business_account." }, { "name": "entry[].id", "description": "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." }, { "name": "entry[].changes[].field", "description": "Nome do campo de inscrição que identifica o tipo do evento." }, { "name": "entry[].changes[].value", "description": "Conteúdo específico do evento. Seu esquema interno não foi confirmado nesta revisão; não inferir chaves ou efeitos." } ], "action": "Preserve o envelope para diagnóstico autorizado; não deduza status nem efeitos pelo nome do campo.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Visão geral ou referência de roteamento da Meta; contrato específico não confirmado", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview/" } ] }, { "id": "business_username_updates", "title": "Username comercial", "category": "Identidade do número", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mudanças de status do username comercial de um número no WhatsApp.", "trigger": "O username comercial muda de estado, incluindo reserva, aprovação, exclusão ou revogação pela Meta.", "payload": [ { "name": "display_phone_number", "description": "Número comercial de exibição ao qual o evento se refere." }, { "name": "username", "description": "Username comercial afetado; omitido quando status é deleted." }, { "name": "status", "description": "Estado do username: approved, deleted ou reserved; uma reserva não equivale a username público ativo." }, { "name": "context", "description": "Contexto adicional condicional; revoked identifica revogação de username pela Meta." } ], "action": "Leia status e context em conjunto; trate o username separadamente do nome de exibição aprovado.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Username comercial", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/" } ] }, { "id": "calls", "title": "Chamadas", "category": "Chamadas", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Eventos e status da WhatsApp Business Calling API, como conexão, encerramento e disponibilidade de gravação/transcrição quando configuradas.", "trigger": "A Calling API produz eventos de conexão, status ou encerramento; recursos adicionais podem produzir eventos de gravação ou transcrição.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "calls[].id", "description": "Identificador único da chamada, usado para correlacionar seus eventos." }, { "name": "calls[].event", "description": "Evento da chamada, como connect, terminate ou eventos adicionais habilitados." }, { "name": "calls[].direction", "description": "Indica se a chamada foi iniciada pela empresa ou pelo usuário." }, { "name": "calls[].timestamp", "description": "Horário do evento de chamada em timestamp Unix." }, { "name": "calls[].session", "description": "Dados de sinalização SDP quando aplicáveis; não presentes no fluxo SIP correspondente." }, { "name": "statuses[].type", "description": "Tipo do status; em notificações de Calling, identifica o status como call." }, { "name": "statuses[].status", "description": "Estado relatado pelo recibo; seus valores dependem do campo e do tipo de evento." }, { "name": "errors", "description": "Erros condicionais associados ao evento ou à operação; interpretar código e detalhes." } ], "action": "Identifique o evento por calls[].event ou statuses[].type e correlacione pelo identificador da chamada.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Chamadas", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference/" } ] }, { "id": "flows", "title": "Eventos de WhatsApp Flows", "category": "WhatsApp Flows", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Criação, estado, alertas de desempenho e expiração de versões de WhatsApp Flows.", "trigger": "Um Flow é criado, muda de estado, ultrapassa limites técnicos de desempenho ou se aproxima da expiração de versão.", "payload": [ { "name": "event", "description": "Tipo do evento que seleciona a interpretação e os detalhes condicionais." }, { "name": "flow_id", "description": "Identificador do WhatsApp Flow a que o evento se refere." }, { "name": "new_status", "description": "Novo estado do Flow informado no evento de ciclo de vida." }, { "name": "old_status", "description": "Estado anterior do Flow; pode estar ausente no evento de criação." }, { "name": "message", "description": "Descrição textual do evento para diagnóstico." }, { "name": "alert_state", "description": "Estado de ativação ou recuperação do alerta técnico." }, { "name": "threshold", "description": "Limite técnico que originou o alerta de monitoramento." }, { "name": "errors", "description": "Erros condicionais associados ao evento ou à operação; interpretar código e detalhes." }, { "name": "warning", "description": "Aviso relativo ao Flow, incluindo expiração/congelamento de versão quando aplicável." } ], "action": "Use estes eventos para operação e monitoramento do Flow; processe respostas de formulários no campo messages.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Eventos de WhatsApp Flows", "url": "https://developers.facebook.com/docs/whatsapp/flows/reference/webhooks/" } ] }, { "id": "group_lifecycle_update", "title": "Criação e exclusão de grupos", "category": "Grupos", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Resultado de criação ou exclusão de um grupo da Groups API.", "trigger": "Uma operação de criação ou exclusão de grupo produz resultado.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "groups[].timestamp", "description": "Timestamp do evento relativo ao grupo." }, { "name": "groups[].group_id", "description": "Identificador do grupo administrado pela Groups API." }, { "name": "groups[].type", "description": "Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor." }, { "name": "groups[].request_id", "description": "Identificador do pedido que originou o resultado, quando informado." }, { "name": "groups[].subject", "description": "Assunto/nome do grupo no resultado da criação." }, { "name": "groups[].invite_link", "description": "Link de convite retornado para o grupo criado." }, { "name": "groups[].join_approval_mode", "description": "Modo de aprovação de entrada configurado para o grupo." }, { "name": "groups[].errors", "description": "Erros da operação de grupo; podem coexistir com resultados parciais." } ], "action": "Correlacione request_id e group_id e verifique errors antes de considerar a operação concluída.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Criação e exclusão de grupos", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/webhooks/" } ] }, { "id": "group_participants_update", "title": "Participantes de grupos", "category": "Grupos", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Entradas, pedidos/cancelamentos de entrada, aprovações, remoções e saídas de participantes da Groups API.", "trigger": "Uma pessoa entra, solicita/cancela entrada, recebe aprovação, é removida ou sai de um grupo.", "payload": [ { "name": "groups[].group_id", "description": "Identificador do grupo administrado pela Groups API." }, { "name": "groups[].type", "description": "Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor." }, { "name": "groups[].timestamp", "description": "Timestamp do evento relativo ao grupo." }, { "name": "groups[].join_request_id", "description": "Identificador do pedido de entrada no grupo." }, { "name": "groups[].wa_id", "description": "Identidade WhatsApp do usuário associado ao pedido." }, { "name": "groups[].added_participants", "description": "Participantes adicionados com sucesso." }, { "name": "groups[].removed_participants", "description": "Participantes removidos ou que saíram, conforme a origem e o tipo." }, { "name": "groups[].failed_participants", "description": "Participantes para os quais a operação falhou, com detalhes de erro quando disponíveis." }, { "name": "groups[].initiated_by", "description": "Origem da mudança, como business ou participant." }, { "name": "groups[].errors", "description": "Erros da operação de grupo; podem coexistir com resultados parciais." } ], "action": "Interprete type e initiated_by; processe participantes bem-sucedidos e falhos separadamente quando o resultado for parcial.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Participantes de grupos", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/webhooks/" } ] }, { "id": "group_settings_update", "title": "Configurações de grupos", "category": "Grupos", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Resultado de alterações de configurações do grupo, como foto, assunto e descrição.", "trigger": "Uma alteração de foto, assunto ou descrição do grupo produz resultado.", "payload": [ { "name": "groups[].group_id", "description": "Identificador do grupo administrado pela Groups API." }, { "name": "groups[].type", "description": "Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor." }, { "name": "groups[].request_id", "description": "Identificador do pedido que originou o resultado, quando informado." }, { "name": "groups[].timestamp", "description": "Timestamp do evento relativo ao grupo." }, { "name": "groups[].profile_picture", "description": "Resultado da atualização de foto, incluindo update_successful e erro quando aplicável." }, { "name": "groups[].group_subject", "description": "Resultado da atualização de assunto, incluindo texto e update_successful." }, { "name": "groups[].group_description", "description": "Resultado da atualização de descrição, incluindo texto e update_successful." }, { "name": "groups[].errors", "description": "Erros da operação de grupo; podem coexistir com resultados parciais." } ], "action": "Leia update_successful e errors de cada configuração; não trate sucesso parcial como sucesso de todas as alterações.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Configurações de grupos", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/webhooks/" } ] }, { "id": "group_status_update", "title": "Suspensão de grupos", "category": "Grupos", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Suspensão de um grupo administrado ou liberação dessa suspensão.", "trigger": "Um grupo administrado é suspenso ou tem a suspensão retirada.", "payload": [ { "name": "groups[].group_id", "description": "Identificador do grupo administrado pela Groups API." }, { "name": "groups[].timestamp", "description": "Timestamp do evento relativo ao grupo." }, { "name": "groups[].type", "description": "Tipo da operação ou mudança de grupo; selecione a interpretação por esse valor." } ], "action": "Atualize o estado do grupo pelo type; mantenha esse estado separado de recibos de entrega/leitura de mensagens.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Suspensão de grupos", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/webhooks/" } ] }, { "id": "history", "title": "Histórico na coexistência", "category": "Coexistência", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Histórico de conversas do WhatsApp Business App no onboarding em coexistência, ou indicação de compartilhamento recusado.", "trigger": "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.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "history[].metadata.phase", "description": "Fase da transferência de histórico; correlacione com os períodos documentados pela Meta." }, { "name": "history[].metadata.chunk_order", "description": "Ordem do bloco de histórico; blocos podem chegar fora de ordem." }, { "name": "history[].metadata.progress", "description": "Percentual de progresso da sincronização; 100 indica conclusão." }, { "name": "history[].threads[].id", "description": "Identificador da conversa histórica transferida." }, { "name": "history[].threads[].messages", "description": "Mensagens do bloco de histórico, que podem ser numerosas e exigir processamento assíncrono." }, { "name": "errors", "description": "Erros condicionais associados ao evento ou à operação; interpretar código e detalhes." } ], "action": "Prepare armazenamento/enfileiramento, processe fases e chunks fora de ordem e acompanhe progress sem confundir aceitação do pedido com conclusão.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Histórico na coexistência", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/history/" } ] }, { "id": "message_echoes", "title": "Echoes: contrato a confirmar", "category": "Mensagens", "subscription": { "status": "disabled", "version": "v26.0" }, "purpose": "Campo de echoes de mensagens listado pela Meta como compatível com callback alternativo; contrato específico não confirmado nesta revisão.", "trigger": "O disparador específico do campo separado message_echoes não foi confirmado nesta revisão.", "payload": [ { "name": "object", "description": "Objeto do webhook: whatsapp_business_account." }, { "name": "entry[].id", "description": "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." }, { "name": "entry[].changes[].field", "description": "Nome do campo de inscrição que identifica o tipo do evento." }, { "name": "entry[].changes[].value", "description": "Conteúdo específico do evento. Seu esquema interno não foi confirmado nesta revisão; não inferir chaves ou efeitos." } ], "action": "Não reutilize automaticamente o parser de smb_message_echoes ou standby.message_echoes; confirme o contrato antes de interpretar value.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Visão geral ou referência de roteamento da Meta; contrato específico não confirmado", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/override/" } ] }, { "id": "message_template_components_update", "title": "Componentes do template", "category": "Templates", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Alteração de componentes de um template após edição.", "trigger": "Um template existente é editado.", "payload": [ { "name": "message_template_id", "description": "Identificador Meta do template afetado." }, { "name": "message_template_name", "description": "Nome do template afetado." }, { "name": "message_template_language", "description": "Idioma e localidade da versão do template afetada." }, { "name": "message_template_element", "description": "Texto do corpo do template informado na notificação de componentes." }, { "name": "message_template_title", "description": "Texto do cabeçalho quando o template possui cabeçalho textual." }, { "name": "message_template_footer", "description": "Texto do rodapé, quando o template possui esse componente." }, { "name": "message_template_buttons", "description": "Botões informados pelo evento, com tipo, rótulo e destino quando aplicável." } ], "action": "Correlacione o template por ID e idioma e confira seus componentes atuais antes de atualizar a apresentação.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Componentes do template", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/message_template_components_update/" } ] }, { "id": "message_template_quality_update", "title": "Qualidade do template", "category": "Templates", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mudança na classificação de qualidade de um template.", "trigger": "A classificação de qualidade de um template muda.", "payload": [ { "name": "previous_quality_score", "description": "Classificação anterior de qualidade do template." }, { "name": "new_quality_score", "description": "Nova qualidade: GREEN, YELLOW, RED ou UNKNOWN." }, { "name": "message_template_id", "description": "Identificador Meta do template afetado." }, { "name": "message_template_name", "description": "Nome do template afetado." }, { "name": "message_template_language", "description": "Idioma e localidade da versão do template afetada." } ], "action": "Mantenha a qualidade em atributo separado do status de aprovação e correlacione a alteração com o template correto.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Qualidade do template", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/message_template_quality_update/" } ] }, { "id": "message_template_status_update", "title": "Estado do template", "category": "Templates", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mudanças no estado do template, incluindo aprovação, rejeição, pausa, desativação e arquivamento.", "trigger": "Um template muda de estado, por exemplo aprovação, rejeição, pausa, desativação ou arquivamento.", "payload": [ { "name": "event", "description": "Tipo do evento que seleciona a interpretação e os detalhes condicionais." }, { "name": "message_template_id", "description": "Identificador Meta do template afetado." }, { "name": "message_template_name", "description": "Nome do template afetado." }, { "name": "message_template_language", "description": "Idioma e localidade da versão do template afetada." }, { "name": "reason", "description": "Motivo associado ao evento, especialmente em rejeições." }, { "name": "message_template_category", "description": "Categoria do template informada junto ao evento de status." }, { "name": "disable_info", "description": "Informações condicionais da desativação, como disable_date." }, { "name": "other_info", "description": "Detalhes condicionais de estados como pausa/despausa, incluindo título e descrição." }, { "name": "rejection_info", "description": "Motivo detalhado e recomendação quando a rejeição inclui esses dados." } ], "action": "Atualize o estado conforme event e use reason e objetos condicionais para explicar a decisão.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Estado do template", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/message_template_status_update/" } ] }, { "id": "messages", "title": "Mensagens e status", "category": "Mensagens", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mensagens recebidas e status de mensagens enviadas, incluindo entrega/leitura/falha e tipos específicos de conteúdo.", "trigger": "A Meta recebe uma mensagem destinada à empresa ou emite status/eventos compatíveis relativos a uma mensagem.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "contacts", "description": "Identidade/perfil associados à mensagem; não representa sincronização da agenda do WhatsApp Business." }, { "name": "messages[].id", "description": "Identificador da mensagem recebida; útil para correlação e deduplicação." }, { "name": "messages[].type", "description": "Tipo do conteúdo, que determina qual objeto de mensagem processar." }, { "name": "statuses[].id", "description": "ID da mensagem enviada a que este status se refere; use para reconciliar com o retorno do envio." }, { "name": "statuses[].status", "description": "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." }, { "name": "errors", "description": "Erros condicionais associados ao evento ou à operação; interpretar código e detalhes." }, { "name": "user_actions[]", "description": "Ações de marketing quando o recurso está disponível, incluindo cliques e landing page views; diferenciar por action_type." }, { "name": "contacts[].profile.name", "description": "Nome de perfil informado na conversa; não é necessariamente o nome salvo pela empresa em sua agenda." }, { "name": "contacts[].user_id", "description": "BSUID do usuário, quando presente. Preserve como string e associe ao escopo comercial da conexão." }, { "name": "messages[].from", "description": "Identificador baseado no telefone do remetente quando disponibilizado; pode não estar presente em cenários que usam username." }, { "name": "messages[].from_user_id", "description": "BSUID do remetente quando presente; permite identificar o usuário sem depender da exposição do telefone." }, { "name": "statuses[].recipient_id", "description": "Identificador do destinatário baseado no telefone, quando disponibilizado." }, { "name": "statuses[].recipient_user_id", "description": "BSUID do destinatário quando presente no status; correlacione com o id da mensagem e o escopo comercial." }, { "name": "statuses[].errors[]", "description": "Erros da tentativa de entrega, quando status indica falha; interprete code, title e detalhes sem converter toda falha em banimento." }, { "name": "messages[].interactive.nfm_reply.response_json", "description": "Respostas de um formulário WhatsApp Flow concluído. É conteúdo de messages, não o evento administrativo flows." } ], "action": "Percorra todos os itens, diferencie messages, statuses, user_actions e errors quando presentes, e deduplique pelos identificadores aplicáveis.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Mensagens e status", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/" }, { "title": "Meta: IDs de usuário no escopo comercial (BSUID)", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/" } ] }, { "id": "messaging_handovers", "title": "Transferência de controle da conversa", "category": "Roteamento de conversas", "subscription": { "status": "disabled", "version": "v26.0" }, "purpose": "Mudança de proprietário da conversa em Conversation Routing: controle passado ou tomado.", "trigger": "O proprietário passa o controle para outro respondente ou o parceiro de escalonamento toma o controle.", "payload": [ { "name": "messaging_product", "description": "Produto do evento; whatsapp neste contrato." }, { "name": "sender.phone_number", "description": "Número do usuário da conversa; pode estar ausente quando indisponível." }, { "name": "recipient.phone_number_id", "description": "ID do número comercial a que pertence a conversa." }, { "name": "recipient.display_phone_number", "description": "Número comercial em formato de exibição." }, { "name": "type", "description": "Notificação control_passed para o novo proprietário ou control_taken para o proprietário anterior." }, { "name": "timestamp", "description": "Horário da alteração ou evento, em timestamp Unix conforme a referência." }, { "name": "control_passed", "description": "Objeto condicional presente quando a notificação informa controle recebido por passagem." }, { "name": "control_taken", "description": "Objeto condicional presente quando o respondente perde controle por tomada do parceiro de escalonamento." }, { "name": "control_passed.previous_owner_role", "description": "Papel do respondente que passou o controle, quando informado." }, { "name": "control_passed.new_owner_role", "description": "Papel do respondente que recebeu o controle, quando informado." }, { "name": "control_taken.previous_owner_role", "description": "Papel do respondente que perdeu o controle, quando informado." }, { "name": "control_taken.new_owner_role", "description": "Papel do novo proprietário; escalation nos casos documentados." } ], "action": "Atualize a propriedade local usando roles quando presentes; ao perder o controle, interrompa respostas que dependam de ser o proprietário.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Transferência de controle da conversa", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messaging-handovers/" } ] }, { "id": "partner_solutions", "title": "Soluções com múltiplos parceiros", "category": "Parcerias Meta", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mudanças no estado de uma Multi-Partner Solution: rascunho, convite, aceitação, rejeição ou desativação.", "trigger": "Uma Multi-Partner Solution é criada, enviada, aceita, rejeitada ou passa pelo processo de desativação.", "payload": [ { "name": "event", "description": "Tipo do evento que seleciona a interpretação e os detalhes condicionais." }, { "name": "solution_id", "description": "Identificador da Multi-Partner Solution." }, { "name": "solution_status", "description": "Estado da solução, como DRAFT, INITIATED, ACTIVE, REJECTED, PENDING_DEACTIVATION ou DEACTIVATED." } ], "action": "Correlacione solution_id e solution_status; preserve a distinção entre solução Meta e assinatura comercial HookCloud.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Soluções com múltiplos parceiros", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/partner_solutions/" } ] }, { "id": "payment_configuration_update", "title": "Configuração de gateway de pagamentos", "category": "Pagamentos no WhatsApp", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mudanças na configuração de gateway para Payments API India e Payments API Brazil: conexão, desconexão e ativação.", "trigger": "Uma configuração da Payments API é conectada, desconectada ou ativada após teste.", "payload": [ { "name": "configuration_name", "description": "Nome da configuração de pagamento usada em operações da Payments API." }, { "name": "provider_name", "description": "Nome do gateway/provedor associado à configuração." }, { "name": "provider_mid", "description": "Identificador da conta do comerciante no gateway." }, { "name": "status", "description": "Estado da configuração do gateway: Active, Needs Connecting ou Needs Testing." }, { "name": "created_timestamp", "description": "Timestamp de criação da configuração de pagamento." }, { "name": "updated_timestamp", "description": "Timestamp da última atualização da configuração de pagamento." } ], "action": "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.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Configuração de gateway de pagamentos", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/payment_configuration_update/" } ] }, { "id": "phone_number_name_update", "title": "Nome de exibição", "category": "Identidade do número", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Resultado da análise do nome de exibição solicitado para o número.", "trigger": "A Meta analisa o nome de um novo número ou a edição de um nome anteriormente aprovado.", "payload": [ { "name": "display_phone_number", "description": "Número comercial de exibição ao qual o evento se refere." }, { "name": "decision", "description": "Resultado da análise: APPROVED, REJECTED, PENDING ou DEFERRED, conforme a referência do campo." }, { "name": "requested_verified_name", "description": "Nome de exibição submetido à análise; pode diferir do nome atualmente aprovado." }, { "name": "rejection_reason", "description": "Motivo da rejeição do nome, quando houve rejeição." } ], "action": "Mostre o nome solicitado e a decisão sem substituir automaticamente um nome aprovado por uma solicitação rejeitada.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Nome de exibição", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/phone_number_name_update/" } ] }, { "id": "phone_number_quality_update", "title": "Throughput e limites do número", "category": "Conta e capacidade", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Atualizações de throughput e eventos/limites relacionados ao número, conforme o payload da Meta.", "trigger": "A Meta comunica eventos de throughput e limites descritos na referência do campo.", "payload": [ { "name": "display_phone_number", "description": "Número comercial de exibição ao qual o evento se refere." }, { "name": "event", "description": "Tipo do evento que seleciona a interpretação e os detalhes condicionais." }, { "name": "max_daily_conversations_per_business", "description": "Limite de mensagens/capacidade do portfólio informado no evento; interpretar o valor conforme a versão vigente." }, { "name": "old_limit", "description": "Campo legado do limite anterior; a referência marca sua remoção." }, { "name": "current_limit", "description": "Campo legado do limite atual/throughput; não deve substituir o campo recomendado vigente." } ], "action": "Interprete event e os limites presentes; não converta um evento de onboarding ou upgrade em incidente de qualidade.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Throughput e limites do número", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/phone_number_quality_update/" } ] }, { "id": "security", "title": "PIN e verificação em duas etapas", "category": "Segurança", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "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.", "trigger": "Alguém altera/habilita o PIN, pede a desativação da verificação em duas etapas ou conclui o procedimento.", "payload": [ { "name": "display_phone_number", "description": "Número comercial de exibição ao qual o evento se refere." }, { "name": "event", "description": "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." }, { "name": "requester", "description": "ID do usuário do Meta Business Suite que solicitou a redefinição/desativação, quando incluído." } ], "action": "Associe o evento ao número exato e diferencie mudança informativa de PIN de uma solicitação de desativação.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: PIN e verificação em duas etapas", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/security/" } ] }, { "id": "smb_app_state_sync", "title": "Contatos na coexistência", "category": "Coexistência", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Sincronização inicial e alterações de contatos do WhatsApp Business App em coexistência.", "trigger": "Uma solicitação inicial bem-sucedida sincroniza contatos; adições, edições e remoções posteriores do WhatsApp Business App também geram eventos.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "state_sync[].type", "description": "Tipo do estado sincronizado; contact para os contatos documentados." }, { "name": "state_sync[].contact.full_name", "description": "Nome completo do contato no WhatsApp Business App; pode faltar na remoção." }, { "name": "state_sync[].contact.first_name", "description": "Primeiro nome do contato; pode faltar na remoção." }, { "name": "state_sync[].contact.phone_number", "description": "Número WhatsApp do contato sincronizado." }, { "name": "state_sync[].action", "description": "add para inclusão ou edição; remove para remoção." }, { "name": "state_sync[].metadata.timestamp", "description": "Horário em que a alteração de contato gerou o evento." } ], "action": "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.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Contatos na coexistência", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/smb_app_state_sync/" } ] }, { "id": "smb_message_echoes", "title": "Mensagens do WhatsApp Business App", "category": "Coexistência", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Cópias de mensagens enviadas, editadas ou removidas pelo WhatsApp Business App ou dispositivo vinculado compatível em coexistência.", "trigger": "A empresa envia, edita ou remove uma mensagem pelo aplicativo WhatsApp Business ou dispositivo vinculado compatível.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "message_echoes[].id", "description": "Identificador da mensagem enviada pelo aplicativo ou dispositivo vinculado." }, { "name": "message_echoes[].from", "description": "Número comercial que enviou a mensagem." }, { "name": "message_echoes[].to", "description": "Identificador/número do destinatário conforme o contrato da mensagem." }, { "name": "message_echoes[].timestamp", "description": "Horário do evento da mensagem espelhada." }, { "name": "message_echoes[].type", "description": "Tipo da mensagem, incluindo edit ou revoke quando aplicável." } ], "action": "Correlacione cada echo pelo ID e tipo da mensagem; diferencie envio original, edição e remoção.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Mensagens do WhatsApp Business App", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/smb_message_echoes/" } ] }, { "id": "standby", "title": "Observação passiva da conversa", "category": "Roteamento de conversas", "subscription": { "status": "disabled", "version": "v26.0" }, "purpose": "Atividade da conversa observada passivamente quando outro respondente controla o thread em Conversation Routing.", "trigger": "Há atividade em uma conversa controlada por outro respondente e a empresa concedeu visibilidade standby ao app.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "standby.contacts", "description": "Identidade/perfil do remetente em uma mensagem observada passivamente." }, { "name": "standby.messages", "description": "Mensagens recebidas na conversa controlada por outro respondente." }, { "name": "standby.message_echoes[].id", "description": "Identificador da mensagem enviada por outro respondente." }, { "name": "standby.message_echoes[].timestamp", "description": "Horário em que o outro respondente enviou a mensagem." }, { "name": "standby.message_echoes[].message", "description": "Parâmetros exatos enviados à API de mensagens; não presumir conteúdo já renderizado." }, { "name": "standby.message_echoes[].template", "description": "Definição opcional do template com placeholders, separada dos valores usados no envio." }, { "name": "standby.message_echoes[].flow", "description": "Definição opcional do Flow associado ao echo." }, { "name": "standby.statuses", "description": "Recibos de mensagens enviadas por outro respondente." } ], "action": "Armazene contexto e recibos conforme o contrato; não responda automaticamente sem a propriedade ou o papel de escalonamento aplicável.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Observação passiva da conversa", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/standby/" } ] }, { "id": "template_category_update", "title": "Categoria do template", "category": "Templates", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Mudança futura ou concluída na categoria de um template.", "trigger": "A Meta anuncia uma mudança futura de categoria ou informa uma mudança concluída, automática ou manual.", "payload": [ { "name": "message_template_id", "description": "Identificador Meta do template afetado." }, { "name": "message_template_name", "description": "Nome do template afetado." }, { "name": "message_template_language", "description": "Idioma e localidade da versão do template afetada." }, { "name": "correct_category", "description": "Categoria identificada pela Meta como correta; interpretar a distinção entre aviso e mudança efetiva." }, { "name": "new_category", "description": "Categoria nova em mudança concluída; em aviso antecipado, ainda representa a categoria atual." }, { "name": "category_update_timestamp", "description": "Timestamp Unix agendado para aplicar a categoria indicada em correct_category." }, { "name": "previous_category", "description": "Categoria anterior em uma notificação de mudança já concluída." } ], "action": "Diferencie mudança agendada de mudança concluída; na primeira, new_category ainda descreve a categoria atual.", "delivery": "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.", "partner_behavior": "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. Mudança futura permanece separada da categoria vigente até a data/evidência de aplicação.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Categoria do template", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/template_category_update/" } ] }, { "id": "template_correct_category_detection", "title": "Detecção de categoria incorreta", "category": "Templates", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Detecção de uso incorreto de categoria em templates do Direct Send, com a categoria identificada pela Meta.", "trigger": "A Meta detecta uso incorreto de categoria em um template Direct Send.", "payload": [ { "name": "message_template_id", "description": "Identificador Meta do template afetado." }, { "name": "message_template_name", "description": "Nome do template afetado." }, { "name": "message_template_language", "description": "Idioma e localidade da versão do template afetada." }, { "name": "category", "description": "Categoria usada originalmente pelo template; o exemplo Direct Send documenta UTILITY." }, { "name": "correct_category", "description": "Categoria que a Meta detectou como correta; para Direct Send, a referência verificada documenta MARKETING." } ], "action": "Identifique o template e examine a categoria detectada; não trate o aviso como confirmação de alteração já aplicada.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Detecção de categoria incorreta", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send/integrity-and-content-guidelines/" } ] }, { "id": "tracking_events", "title": "Tracking: contrato a confirmar", "category": "Medição", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Campo observado no inventário do app; contrato público específico não confirmado nesta revisão.", "trigger": "O disparador público específico deste campo não foi confirmado nesta revisão.", "payload": [ { "name": "object", "description": "Objeto do webhook: whatsapp_business_account." }, { "name": "entry[].id", "description": "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." }, { "name": "entry[].changes[].field", "description": "Nome do campo de inscrição que identifica o tipo do evento." }, { "name": "entry[].changes[].value", "description": "Conteúdo específico do evento. Seu esquema interno não foi confirmado nesta revisão; não inferir chaves ou efeitos." } ], "action": "Não deduza métricas ou conversões pelo nome; eventos de clique e landing page documentados usam messages/user_actions.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Visão geral ou referência de roteamento da Meta; contrato específico não confirmado", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview/" }, { "title": "Meta: cliques de marketing chegam em messages", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/marketing-messages/track-click-events/" }, { "title": "Meta: visualizações de landing page chegam em messages", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/marketing-messages/track-landing-page-views/" } ] }, { "id": "user_preferences", "title": "Preferências de marketing", "category": "Preferências", "subscription": { "status": "enabled", "version": "v26.0" }, "purpose": "Preferência do usuário para parar ou retomar mensagens de marketing.", "trigger": "Um usuário decide parar ou retomar mensagens de marketing da empresa.", "payload": [ { "name": "metadata.phone_number_id", "description": "ID do número comercial associado ao evento; use-o para determinar o escopo." }, { "name": "contacts", "description": "Identidade/perfil associados à mensagem; não representa sincronização da agenda do WhatsApp Business." }, { "name": "user_preferences[].wa_id", "description": "Identidade WhatsApp do usuário quando disponível; pode ser omitida em cenários de username." }, { "name": "user_preferences[].user_id", "description": "Identidade do usuário com escopo comercial (BSUID), quando habilitada." }, { "name": "user_preferences[].parent_user_id", "description": "Parent BSUID para identificação; não é o nível de aplicação da preferência." }, { "name": "user_preferences[].category", "description": "Categoria da preferência; a referência documenta marketing_messages." }, { "name": "user_preferences[].value", "description": "Escolha do usuário: stop para parar ou resume para retomar marketing." }, { "name": "user_preferences[].detail", "description": "Descrição da escolha de parar ou retomar as mensagens." }, { "name": "user_preferences[].timestamp", "description": "Timestamp Unix da atualização de preferência." } ], "action": "Aplique stop/resume à identidade e ao escopo correto; não use parent_user_id para aplicar uma preferência a todas as identidades relacionadas.", "delivery": "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.", "partner_behavior": "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.", "caveats": [ "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." ], "references": [ { "title": "Referência oficial da Meta: Preferências de marketing", "url": "https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/user_preferences/" } ] } ] }