## Visão geral

A Conversa Labs oferece dois pontos de extensão complementares para desenvolvedores:

- **Canal de API**: um **inbox programável**. Em vez de um canal pronto (WhatsApp, e-mail etc.),
  você cria uma caixa de entrada do tipo API e conecta o seu próprio aplicativo. Mensagens de
  entrada chegam via API REST e as respostas dos agentes são entregues no seu `webhook_url`.
- **Agent bot**: um **bot via webhook** (`bot_type: webhook`). Ele é atribuído a um inbox (de
  qualquer canal) e recebe os eventos de conversa/mensagem no seu `outgoing_url`. O bot processa o
  evento e pode responder chamando a API de volta com o seu token de acesso.

Quando usar cada um:

- Use o **canal de API** quando precisar de um canal sob medida que a plataforma não oferece de
  forma nativa.
- Use um **agent bot** quando quiser automatizar respostas (triagem, respostas automáticas, IA)
  antes ou junto do atendimento humano, em qualquer inbox.

Os dois podem ser combinados: um inbox de API que também tem um agent bot atribuído.

## Pré-requisitos

- Permissão de **administrador** na conta (criação de inbox e de agent bots é restrita a admins).
- Um **endpoint HTTPS** acessível para receber webhooks (`webhook_url` do canal e/ou `outgoing_url`
  do bot).
- Um **token de acesso** válido para autenticar as chamadas à API REST.

## Passo a passo

1. **Crie um inbox do tipo API**: vá em **Configurações → Caixas de entrada → Adicionar →
   API**. Informe um nome e, opcionalmente, o `webhook_url`. Após criar, anote o **identifier**
   gerado para o canal.
2. **Envie uma mensagem de entrada**: crie/abra uma conversa nesse inbox e poste a mensagem do
   cliente via API (`POST .../conversations/:id/messages`), autenticando com o token de acesso.
3. **Configure o `webhook_url`** do canal para receber as mensagens de saída: quando um agente
   responde na conversa, o payload é entregue no seu endpoint.
4. **(Opcional) Crie um agent bot**: em **Configurações → Bots de IA/Agent bots**, informe nome,
   descrição e o `outgoing_url` (`bot_type` = webhook). Depois **atribua o bot ao inbox** para que
   ele passe a receber os eventos daquela caixa de entrada.

## Configurações & opções

- **Token de acesso do bot**: usado pelo bot para chamar a API de volta (criar respostas, reagir,
  atualizar status). Pode ser regenerado por **reset_access_token**.
- **Segredo do bot**: usado para assinar/verificar o payload do webhook enviado ao `outgoing_url`.
  Pode ser regenerado por **reset_secret**.
- **Verificação HMAC do canal** (`hmac_token`, `hmac_mandatory`): valida a identidade do contato.
  Com `hmac_mandatory` ativo, contatos só são aceitos com o hash de identificação válido,
  calculado a partir do `hmac_token`.
- **Atualização de status de mensagem**: permitida **apenas em inboxes de API** (por exemplo, marcar
  entregue/lida ou registrar erro de envio).
- **Payload do bot** (`webhook_data`): identifica o bot no evento com `{ id, name, type: "agent_bot" }`.

## Casos de uso

- **Canal sob medida**: conectar um aplicativo próprio (um app interno, um marketplace, um canal
  proprietário) como um inbox via API.
- **Respostas automáticas**: um agent bot que faz a triagem inicial, responde dúvidas frequentes e
  só então passa a conversa para um agente humano.

## Dicas, limites e boas práticas

- Sempre **verifique a assinatura HMAC** do webhook (canal e/ou segredo do bot) antes de processar o
  payload.
- Garanta **idempotência**: ao criar mensagens de entrada, use um `source_id` único para deduplicar
  reentregas.
- Defina um **ponto de handoff** claro do bot para o humano (por exemplo, atribuir a conversa a um
  agente/time e parar de responder pelo bot).
- Trate tokens e segredos como credenciais: nunca os exponha no front-end.

## Solução de problemas

- **401/403**: token de acesso inválido, expirado ou sem permissão.
- **O bot não recebe eventos**: confirme que o `outgoing_url` está correto, acessível e que o bot
  está atribuído ao inbox.
- **HMAC inválido**: o hash de identificação não confere com o `hmac_token`; recalcule a assinatura
  e confira a ordem/codificação dos campos.

## 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)
- [Canal de API: o contrato de eventos estruturados](/hc/ajuda/articles/api-developers-api-channel-contract-pt-br)