Central de Ajuda Conversa Labs
pt_BR
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

Canal de API: o contrato de eventos estruturados

Abrir em
Ver como Markdown Abrir no ChatGPT Abrir no Claude
Conversa Labs

Conversa Labs

Última atualização em Jul 16, 2026

Visão geral

O canal de API é uma caixa de entrada de primeira classe. Qualquer módulo da plataforma o alcança da mesma forma que alcança o WhatsApp ou o widget web: ele cria uma mensagem em uma conversa. Essa mensagem é então enviada via POST — assinada — para a URL do webhook da sua caixa de entrada. Como todo payload de mensagem carrega o content_type completo e os content_attributes, o conteúdo estruturado (botões interativos, CTAs de pagamento, cards de catálogo, eventos de agenda e reações) chega à sua integração de forma nativa — você o renderiza.

Tudo aqui é aditivo e retrocompatível: integrações existentes continuam funcionando e podem ignorar qualquer campo que não reconheçam. Não há novos campos obrigatórios.

Pré-requisitos

  • Uma caixa de entrada de API com uma URL de webhook configurada.
  • O secret da caixa de entrada para verificar a assinatura do webhook (e, opcionalmente, o hmac_token para HMAC de entrada).
  • Um access token para a API REST quando você enviar dados de volta.

Passo a passo

  1. Crie uma caixa de entrada de API e defina sua URL de webhook.
  2. Receba eventos nessa URL e verifique a assinatura com o secret da caixa de entrada.
  3. Leia content_type + content_attributes em cada payload de mensagem para renderizar conteúdo rico.
  4. Envie mensagens de entrada, recibos de entrega e reações de volta através da API REST.
  5. (Opcional) Restrinja quais eventos você recebe com webhook_subscriptions.

Tipos de conteúdo de saída (o que o webhook entrega)

Cada payload de message_created / message_updated inclui content_type, content, content_attributes e attachments. Além do text simples, a caixa de entrada de API pode entregar:

  • input_select — opções interativas em content_attributes.items ([{title, value}]). Quando um canal não consegue renderizar as opções, a plataforma também anexa um menu numerado ao content.
  • content_attributes.payment_interactive — uma ação de pagamento: { body, buttons: [{ type: "cta_url", text, url } | { type: "cta_copy", text, code }] }. A cobrança completa (valor, código PIX, boleto, links) também chega como content_attributes.payment_charge na mensagem de resumo.
  • content_attributes.catalog_product — um card de produto: { mode: "single" | "list", products: [{ id, name, price, currency, image_url, ... }] }.
  • content_attributes.calendar_event — uma confirmação de agendamento ou lembrete: { id, title, starts_at, ends_at, location, meet_url, kind: "confirmation" | "reminder" } (horários em ISO-8601).
  • content_attributes.reactions — um array de { emoji, sender_jid }. O operador é me; um contato é armazenado sob seu próprio identificador. As reações viajam no evento message_updated.
  • Templates — os metadados do template enviado viajam em additional_attributes.template_params ({ name, language, category, processed_params }).
  • Mídia, localização, contatos, stickers — entregues como attachments reais (além de content_attributes.media_kind para stickers).

Entrada (o que você envia de volta)

  • Mensagem de entrada — POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages com message_type: "incoming". Aceita content, content_type, content_attributes e attachments, de modo que uma resposta interativa é simétrica ao contrato de saída.
  • Recibos de entrega — PUT/PATCH .../messages/{id} (apenas caixas de entrada de API) com status de sent / delivered / read / failed (e um external_error opcional). Isso altera o status da mensagem, que é retransmitido via message_updated.
  • Reações — POST .../messages/{id}/react com emoji (um emoji vazio o remove). Passe by=contact para registrar a reação do contato (o padrão registra a do operador). Nenhum provedor é contatado para uma caixa de entrada de API — a reação é persistida e retransmitida via message_updated.

Campanhas

Campanhas pontuais podem direcionar uma caixa de entrada de API. Cada contato do público recebe uma conversa real e uma mensagem de saída, que viaja pelo seu webhook exatamente como qualquer outra mensagem de saída.

Configurações & opções

  • webhook_subscriptions — um array opcional em additional_attributes do canal de API (atualize a caixa via API com channel[additional_attributes][webhook_subscriptions]). Quando definido, apenas esses eventos são entregues; quando ausente ou vazio, todos os eventos são entregues (o padrão). Os nomes de eventos devem ser eventos válidos da plataforma (por exemplo, message_created, message_updated, conversation_created, conversation_status_changed, conversation_typing_on).
  • hmac_mandatory — rejeita requisições de entrada que não podem ser verificadas por HMAC.

Casos de uso

  • Conecte a caixa de entrada a um app personalizado que renderiza CTAs de pagamento, cards de catálogo e agendamentos de agenda.
  • Retransmita a reação de um contato do seu próprio cliente de volta para a mensagem.
  • Espelhe confirmações e lembretes de agendamento no canal de registro do cliente.

Dicas, limites e boas práticas

  • Sempre verifique a assinatura do webhook antes de agir sobre um payload.
  • Faça deduplicação pelo id de entrega / evento; espere retentativas.
  • Prefira content_attributes para renderização estruturada; content é o fallback em texto simples.
  • Inscreva-se apenas nos eventos que você usa para reduzir ruído.

Solução de problemas

  • Nenhum evento chegando: confirme que a URL do webhook está definida e, se você configurou webhook_subscriptions, que o evento esperado está na lista.
  • 422 nas inscrições: a lista contém um nome de evento desconhecido — remova-o.
  • Reação não atribuída ao contato: passe by=contact na chamada de react.

Veja também