# Guia n8n

> Precisa que o agente **decida sozinho** quando chamar uma ferramenta (Tool)
> dentro do n8n, com o node **AI Agent** nativo? Esse e' outro caminho — veja
> [integration-guide-n8n-ai-agent.md](/docs/integration-guide-n8n-ai-agent.md).

## Quando este guia e o certo

Use este caminho quando:

- o n8n ja recebe a mensagem do seu provedor
- o n8n vai chamar o ChatAgent
- o n8n tambem vai devolver a resposta ao cliente

O desenho ideal no n8n e este:

1. um node recebe o evento
2. um node limpa os campos
3. um node chama o ChatAgent
4. um node devolve `reply`

## O jeito mais simples de pensar

O n8n nao precisa entender a IA por dentro.

Ele so precisa fazer duas coisas bem:

- montar o body certo
- devolver o campo certo

## Qual chave usar

### Modo recomendado

Use a **API key do numero**.

Assim o node HTTP nao precisa mandar `number_id`.

### Modo compativel

Se voce usar a **API key geral do tenant**, adicione `number_id` no body.

## Fluxo minimo

Fluxo recomendado:

1. `Webhook`
2. `Set` ou `Function`
3. `HTTP Request` para o ChatAgent
4. `HTTP Request` para responder no provedor
5. opcionalmente `IF` para tratar erro

## Passo a passo

### 1. Receba a mensagem

No node `Webhook`, receba o payload bruto do provedor.

Nao chame o ChatAgent com o payload cru.

Primeiro traduza.

### 2. Monte um body limpo

No node `Set` ou `Function`, crie um JSON simples.

### Exemplo com API key do numero

```json
{
  "from": "={{ $json.from }}",
  "name": "={{ $json.name }}",
  "message": "={{ $json.message }}"
}
```

### Exemplo com API key geral do tenant

```json
{
  "number_id": 12,
  "from": "={{ $json.from }}",
  "name": "={{ $json.name }}",
  "message": "={{ $json.message }}"
}
```

## 3. Configure o node HTTP Request

### URL

```text
https://seu-dominio/api/whatsapp/message
```

### Headers

```text
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
```

### O que muda entre os 2 modos

- com a API key do numero: o body nao precisa de `number_id`
- com a API key geral do tenant: o body precisa de `number_id`

## 4. O que ler na resposta

O campo mais importante da resposta e:

```json
{
  "reply": "texto para devolver ao cliente"
}
```

No node seguinte, use `reply`.

Nao use:

- `thread_id` como texto para o cliente
- o body inteiro da resposta

## Payload mapping

| Origem no n8n | Campo do ChatAgent | Observacao |
| --- | --- | --- |
| identificador estavel do contato | `from` | precisa ser o mesmo contato sempre |
| nome do contato | `name` | opcional |
| texto limpo da mensagem | `message` | obrigatorio |
| id do numero cadastrado | `number_id` | so quando a chave usada for a do tenant |
| `{{$json.reply}}` | texto de saida | resposta final |

## Exemplo de erro que o n8n costuma causar

### Caso 1

O integrador usa a API key geral do tenant, mas esquece `number_id`.

Resultado:

- a API responde `400`

### Caso 2

O integrador manda o payload bruto do webhook em vez de um JSON limpo.

Resultado:

- `message` vem errada
- a resposta fica ruim

### Caso 3

O node final responde com o campo errado.

Resultado:

- o cliente nao recebe o texto certo

## Validacao

## Como validar antes de publicar

- o node `HTTP Request` retorna `200`
- o body enviado ao ChatAgent tem `from` e `message`
- se a chave for a do tenant, o body tambem tem `number_id`
- o node final usa `reply`
- o mesmo contato gera o mesmo `from`

## Checklist final

- [ ] existe um passo explicito de normalizacao
- [ ] a chave usada esta correta para o modo escolhido
- [ ] se a chave for do tenant, `number_id` esta no body
- [ ] o envio final usa `reply`
- [ ] o fluxo foi testado com o mesmo contato mais de uma vez