# Guias de Integracao

## O que esta documentacao resolve

Esta trilha foi feita para quem quer plugar a API do ChatAgent em um sistema que ja existe.

Em outras palavras:

- voce ja recebe mensagens em algum lugar
- voce quer mandar essas mensagens para o ChatAgent
- voce quer pegar a resposta e devolver ao cliente

O foco aqui nao e explicar o projeto inteiro por dentro.

O foco e mostrar, de forma clara, como integrar sem quebrar contexto, sem escolher a chave errada e sem devolver o campo errado ao cliente.

## A ideia central em uma frase

Seu sistema recebe a mensagem, traduz para o formato do ChatAgent, chama a API e devolve o campo `reply`.

## Novo caminho recomendado

Para integracoes novas, prefira a camada generica:

```http
POST /api/messages
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
```

Nesse modelo, voce envia:

- `actor`
- `conversation`
- `message`

O endpoint `/api/whatsapp/message` continua suportado, mas agora deve ser visto como um adaptador oficial de canal.

## Descoberta para agentes

Se a integracao for feita por outro agente, orquestrador ou automacao generica, comece pelo manifesto:

```http
GET /api/agents/manifest
Authorization: Bearer SUA_API_KEY
```

Ele retorna o endpoint recomendado, exemplos de payload, campos obrigatorios e erros que o agente deve tratar.

O manifesto nao consome creditos e nao altera dados.

## Existem 2 jeitos de autenticar

### Jeito recomendado: API key do numero

Use este modo quando cada numero precisa responder com um perfil proprio.

Exemplo:

- numero Comercial
- numero Suporte
- numero Agenda

Cada numero pode ter sua propria:

- identidade
- contexto
- personalidade
- regras
- objetivo

Quando voce usa a **API key do numero**, nao precisa mandar `number_id`.

Essa e a opcao mais simples e a que mais evita erro.

### Jeito compativel: API key geral do tenant

Use este modo quando voce ainda quer integrar com a chave geral da conta.

Nesse caso, voce **precisa** mandar `number_id` no body para dizer qual numero deve responder.

Sem `number_id`, a API nao adivinha o perfil.

## Quando usar a API publica

Use a API publica quando o seu sistema ja consegue:

- receber eventos de mensagem
- fazer requisicoes HTTP
- mandar resposta de volta para o contato

Isso cobre bem cenarios como:

- `n8n`
- `Uazapi`
- `Evolution API`
- `Baileys`
- backends proprios

## Pre-requisitos

Antes de integrar, confirme:

- voce sabe qual chave vai usar
- voce consegue fazer `POST` HTTP
- voce consegue extrair um `from` estavel
- voce consegue extrair o texto limpo da mensagem
- voce consegue devolver `reply` ao cliente

## Endpoint principal

```http
POST /api/whatsapp/message
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
```

## Endpoint generico

```http
POST /api/messages
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
```

Exemplo rapido:

```json
{
  "actor": {
    "id": "lead-42",
    "type": "lead",
    "name": "Maria"
  },
  "conversation": {
    "id": "site-chat:lead-42",
    "channel": "web"
  },
  "message": {
    "text": "Quero um orcamento"
  }
}
```

## Exemplo rapido: modo recomendado

Aqui a chave ja pertence ao numero.

```json
{
  "from": "5511999999999@s.whatsapp.net",
  "name": "Maria",
  "message": "Ola"
}
```

## Exemplo rapido: modo compativel

Aqui a chave e a geral do tenant, entao `number_id` vira obrigatorio.

```json
{
  "number_id": 12,
  "from": "5511999999999@s.whatsapp.net",
  "name": "Maria",
  "message": "Ola"
}
```

## Exemplo de resposta

```json
{
  "reply": "Ola! Como posso ajudar?",
  "thread_id": "number:12:whatsapp:5511999999999@s.whatsapp.net",
  "channel": "whatsapp",
  "credits_remaining": 123,
  "elapsed": 4.2,
  "status": "answered"
}
```

## O que cada campo quer dizer

- `from`: quem esta falando. Esse valor precisa ser estavel para o mesmo contato.
- `name`: nome do contato. E opcional.
- `message`: texto limpo da mensagem atual.
- `number_id`: qual numero deve responder. So existe quando voce usa a chave geral do tenant.
- `reply`: texto que deve voltar para o cliente.
- `thread_id`: identificador da conversa para log e rastreio.

## Fluxo recomendado

O caminho seguro e este:

1. seu provedor recebe a mensagem
2. voce extrai um identificador estavel do contato
3. voce extrai o texto limpo da mensagem
4. voce escolhe a autenticacao certa
5. voce chama `/api/whatsapp/message`
6. voce le `reply`
7. voce devolve `reply` ao provedor

## Erros comuns

### 1. Esqueceu `number_id`

O erro mais comum hoje e este:

- usar a API key geral do tenant
- esquecer de mandar `number_id`

### 2. O `from` muda a cada mensagem

O segundo erro mais comum e este:

- usar um `from` diferente a cada mensagem

Quando isso acontece, a conversa parece perder memoria.

## Checklist final

- [ ] eu sei se vou usar a API key do numero ou a API key geral do tenant
- [ ] se a chave for a do tenant, eu tenho o `number_id`
- [ ] eu tenho um `from` estavel para o mesmo contato
- [ ] eu mando apenas texto limpo em `message`
- [ ] eu devolvo `reply` ao cliente
- [ ] eu guardo `thread_id` no log

## Qual guia ler agora

- [Guia n8n](./integration-guide-n8n.md)
- [Guia para agentes](./integration-guide-agents.md)
- [Guia Uazapi](./integration-guide-uazapi.md)
- [Guia Evolution e Baileys](./integration-guide-evolution-baileys.md)
- [Guia do contrato da API](./integration-guide-api.md)
- [Guia de integracao do app interno](./integration-guide-internal-app.md)
- [Troubleshooting de integracao](./integration-troubleshooting.md)