## 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

- [API REST, tokens e webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-pt-br)
- [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-pt-br)
- [Referência da API (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-pt-br)