Suporte a Webhook e API - Perguntas frequentes
Perguntas frequentes sobre o uso das APIs do Chakra Chat e de webhooks de entrada.
Aborda webhooks de eventos de entrada (pass-through e no formato Chakra), assinatura HMAC, recuperação do histórico de mensagens, Coexistence e idempotência de envio.
1. Comportamento geral do webhook
O webhook oferece suporte a novas tentativas, enfileiramento ou processamento em lote? Qual é o prazo e o corpo de resposta exigidos para uma confirmação bem-sucedida?
Não há política de novas tentativas nem de enfileiramento para webhooks Pass through ou Chakra. Uma confirmação bem-sucedida consiste em um HTTP 200 sem necessidade de corpo na resposta e deve ser retornada em menos de 200 ms. Referência: Documentação do webhook de eventos de entrada
Os eventos do webhook podem ser processados em lote, duplicados ou entregues fora de ordem? As entregas duplicadas são idênticas em bytes e cada entrega tem uma assinatura HMAC independente?
O processamento em lote não é compatível, e os eventos podem chegar fora de ordem. Referência: Webhook de eventos de entrada — seção Validação de HMAC
Quais são os limites aplicáveis ao tamanho do corpo do webhook, ao tamanho do lote, à simultaneidade e à taxa de entrega?
Nenhum limite foi publicado. Espera-se um uso razoável.
Qual é a latência dos eventos do webhook ao assinar webhooks?
A latência histórica medida entre um evento da Meta chegar ao Chakra Webhook e uma tentativa de enviar o evento ser feita é de cerca de 10-50 ms.
2. Recuperação de eventos perdidos
Se um webhook for perdido, qual endpoint pode listar as mensagens de entrada, os status de entrega e os ecos do Business App que estão faltando?
Não há um endpoint específico para "eventos perdidos". As mensagens de entrada perdidas podem ser recuperadas pelas APIs de histórico de chats, com filtros por ID do plugin e ID do número de telefone do WhatsApp. Uma consulta equivalente para status de entrega ou ecos do Business App — assim como informações sobre períodos de retenção ou atrasos de consistência — não é abordada na documentação publicada e deve ser considerada indisponível no momento, até confirmação interna. Referência: Listar chats | Listar mensagens do chat | Listar mensagens anteriores de um número de telefone
3. Payloads e identificação de eventos
Onde posso encontrar payloads atuais completos e com dados confidenciais removidos para message, status, message_echoe smb_message_echo, incluindo um status de falha com todos os campos de erro?
Há payloads de exemplo publicados na referência do webhook de eventos de entrada. Referência: Webhook de eventos de entrada — payloads de exemplo
Para eventos status, message_echoe smb_message_echo , quais campos identificam o plugin, a WABA e o número de telefone comercial que recebe a mensagem quando uma conta tem vários números?
Nos eventos no formato pass-through/Meta, o número que recebe a mensagem aparece em value.metadata.phone_number_id / display_phone_number, e o ID da WABA aparece em entry[].id.
- Exemplo de evento de mensagem de texto de entrada: apidocs.chakrahq.com/doc-919167#sample-inbound-text-message-event
- Estrutura do objeto de evento de entrada: apidocs.chakrahq.com/doc-919167#inbound-event-object-structure
Referência: Webhook de eventos de entrada
Quais mensagens do Business App geram eventos smb_message_echoe há tipos não compatíveis ou dispositivos complementares?
Todas as mensagens de texto e mídia do Business App geram eventos smb_message_echo . Os tipos de mensagem não compatíveis são:
- Enquetes
- Mensagens temporárias
- Mensagens excluídas
A quais campos/eventos nossa WABA está inscrita?
Os seguintes eventos estão inscritos e disponíveis por meio do webhook de passagem
O webhook account_alerts notifica você sobre alterações no limite de mensagens, perfil comerciale status de Conta Comercial Oficial . | |
O webhook account_review_update notifica você quando uma Conta do WhatsApp Business é analisada de acordo com nossas diretrizes de política. | |
O webhook account_update notifica você sobre alterações no envio da verificação empresarial conduzida por parceiro , na elegibilidade para a taxa internacional de autenticação ou na localização comercial principal de uma Conta do WhatsApp Business quando ela é compartilhada com um Parceiro de Soluções, violações de políticas ou termos, desativação, reconexão ou exclusão da conta. | |
O webhook automatic_events notifica você quando detectamos um evento de compra ou lead em uma conversa entre você e um usuário do WhatsApp que enviou uma mensagem por meio do seu anúncio de clique para o WhatsApp, caso você tenha aceitado participar dos relatórios de Eventos Automáticos . | |
O webhook business_capability_update notifica você sobre alterações nos recursos da Conta do WhatsApp Business ou do portfólio empresarial (limites de mensagens, limites de números de telefoneetc.). | |
O webhook calls notifica você sobre eventos de chamada de chamadas iniciadas pelo usuário e chamadas iniciadas pela empresa, como quando uma chamada é conectada ou encerrada. | |
O webhook history é usado para sincronizar o histórico de conversas do app WhatsApp Business de um cliente empresarial integrado por um provedor de soluções. | |
O webhook message_template_components_update notifica você sobre alterações nos componentes de um modelo. | |
O webhook message_template_quality_update notifica você sobre alterações na pontuação de qualidade. | |
O webhook message_template_status_update notifica você sobre alterações no status de um modelo existente. | |
O webhook messages descreve as mensagens enviadas por um usuário do WhatsApp para uma empresa e o status das mensagens enviadas por uma empresa para um usuário do WhatsApp. | |
O webhook partner_solutions descreve alterações no status de uma Solução para Múltiplos Parceiros. | |
O webhook payment_configuration_update notifica você sobre alterações nas configurações de pagamento da Payments API India e da Payments API Brazil. | |
O webhook phone_number_name_update notifica você sobre os resultados da verificação do nome de exibição do número de telefone comercial. | |
O webhook phone_number_quality_update notifica você sobre alterações no nível de capacidade de envio. | |
O webhook security notifica você sobre alterações nas configurações de segurança de um número de telefone comercial. | |
O webhook smb_app_state_sync é usado para sincronizar os contatos de usuários do app WhatsApp Business que foram integrados por meio de um provedor de soluções. | |
O webhook smb_message_echoes notifica você sobre mensagens enviadas pelo app WhatsApp Business ou por um dispositivo complementar ("vinculado") por um cliente empresarial que foi integrado à Cloud API por meio de um provedor de soluções. | |
O webhook template_category_update notifica você sobre alterações na categoria. | |
O webhook user_preferences notifica você sobre alterações nas preferências de mensagens de marketing. |
4. Controles de mensagens enviadas
Nossa conta inclui webhooks de passagem, webhooks personalizados, HMAC e ecos de coexistência?
Todas as contas do Chakra Chat são compatíveis com webhooks de passagem, webhooks personalizados, HMAC e ecos de coexistência.
5. Segredo HMAC e rotação
Nós fornecemos o segredo HMAC ou o Chakra o gera?
Você fornece o segredo e o define em Admin > Equipe > Segredos. Referência: Webhook de eventos recebidos — Validação HMAC
Gerar novamente o segredo HMAC da equipe invalida o anterior imediatamente. Qual procedimento de transição evita a perda de webhooks durante a rotação? As assinaturas antigas e novas podem se sobrepor temporariamente? O mecanismo de rotação está documentado (o segredo é definido em Admin > Equipe > Segredos e enviado pelo cabeçalho X-Chakra-Signature-256 ), mas não há suporte para um procedimento de transição nem para um período de sobreposição de assinaturas. Referência: Webhook de eventos recebidos — Validação HMAC
O mesmo endpoint de callback e segredo podem receber mensagens de passagem, status, message_echoe eventos smb_message_echo ?
Todos os eventos no formato Chakra e de passagem (message, status, message_echo, smb_message_echo) compartilham uma única URL de callback e um único segredo HMAC. O feed de passagem da Meta usa uma URL separada, e a assinatura HMAC desse feed especificamente não está documentada. Referência: Webhook de eventos recebidos
6. Configuração da URL de callback
Onde configuramos a URL de callback do webhook: no painel ou pela API? No painel do Chakra: página Configuração do WhatsApp → guia "Mais" → campo "URL do webhook de passagem" (formato Meta) e campo "URL do webhook do Chakra" (formato Chakra).
Ela também pode ser definida programaticamente pela API de configuração do plug-in: apidocs.chakrahq.com/api-33925592
Referência: Webhook de eventos de entrada
O callback é válido para toda a equipe, para a WABA/o plug-in ou para cada número de telefone?
Por plug-in. Cada instância do plug-in Configuração do WhatsApp tem seus próprios campos de URL para o webhook de passagem e o webhook do Chakra — não há webhook no nível da equipe. Em cada plug-in, é possível configurar webhooks específicos da WABA/do número de telefone. Referência: Webhook de eventos recebidos
7. Idempotência da API
Algum endpoint de envio oferece suporte a uma chave de idempotência do cliente ou a um mecanismo de supressão de duplicatas? Após um timeout, como podemos determinar com certeza se uma mensagem foi aceita?
Nenhum parâmetro de chave de idempotência é compatível com os endpoints de envio. Um envio bem-sucedido retorna um ID de mensagem do WhatsApp (wamid) de forma síncrona no corpo da resposta. O procedimento documentado após um timeout é consultar o histórico de conversas/mensagens e procurar por esse wamid — não há mecanismo de chave de idempotência nem de supressão de duplicatas na própria chamada de envio. Referência: Enviar mensagem de sessão do WhatsApp | Listar mensagens da conversa
8. Desconexão da Coexistence
Qual SLA de liberação e escalonamento do provedor se aplica ao desconectar a Coexistence, incluindo associações residuais com parceiros/faturamento?
O cliente fornece os próprios dados de faturamento diretamente à Meta, portanto não há possibilidade de problemas residuais de faturamento. Referência: Desconectar conta WABA | Cancelar o registro de um número de telefone comercial do WhatsApp