# Guia Uazapi

## Papel do Uazapi neste desenho

Neste modelo, o Uazapi continua cuidando de:

- receber a mensagem
- manter a sessao do WhatsApp
- enviar a resposta final

O ChatAgent entra como camada de resposta inteligente.

Em resumo:

- Uazapi recebe
- ChatAgent responde
- Uazapi devolve

## Qual chave usar

### Modo recomendado

Use a **API key do numero**.

Esse modo e o mais limpo quando cada numero precisa de um perfil proprio.

### Modo compativel

Se voce integrar com a **API key geral do tenant**, envie `number_id` no body.

## O que o ChatAgent espera receber

### Com API key do numero

```json
{
  "from": "jid-ou-numero-do-contato",
  "name": "nome-do-contato",
  "message": "texto-da-mensagem"
}
```

### Com API key geral do tenant

```json
{
  "number_id": 12,
  "from": "jid-ou-numero-do-contato",
  "name": "nome-do-contato",
  "message": "texto-da-mensagem"
}
```

## Passo a passo

### 1. Receba o webhook do Uazapi

Primeiro capture o payload original.

Durante desenvolvimento, vale logar esse evento bruto para ter certeza de onde saem:

- o identificador do contato
- o nome
- o texto da mensagem

### 2. Extraia o contato certo

O campo mais importante para memoria e `from`.

Use um identificador estavel, por exemplo:

- JID
- numero normalizado
- ID persistente do contato

Nao use valor temporario do evento.

### 3. Extraia o texto certo

`message` deve conter apenas o texto da mensagem atual.

Nao mande:

- o payload inteiro
- metadata
- objeto serializado

### 4. Chame o ChatAgent

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

### 5. Devolva o campo certo

Da resposta do ChatAgent, o campo principal e:

```json
{
  "reply": "resposta da IA"
}
```

Esse e o texto que deve voltar para o cliente pelo proprio Uazapi.

## Payload mapping

| Origem no Uazapi | Campo do ChatAgent | Observacao |
| --- | --- | --- |
| identificador do contato | `from` | precisa ser estavel |
| nome do contato | `name` | opcional |
| texto da mensagem | `message` | obrigatorio |
| id do numero cadastrado | `number_id` | so quando a chave usada for a do tenant |
| `reply` da resposta | envio final do Uazapi | texto para o cliente |

## Troubleshooting

## Casos em que costuma dar erro

### 1. A conversa parece sem contexto

Quase sempre significa:

- o `from` muda entre mensagens

### 2. A API responde `400`

Normalmente significa uma destas duas coisas:

- faltou `message`
- faltou `number_id` quando a chave usada foi a do tenant

### 3. A API responde `200`, mas o cliente nao recebe nada

Normalmente significa:

- o envio final nao usou `reply`
- ou o request de envio do Uazapi falhou

## Validacao

Antes de considerar a integracao pronta:

- teste com o mesmo contato duas vezes
- confirme que o `thread_id` fica no formato `number:<id>:whatsapp:<from>`
- confirme que o texto enviado de volta vem de `reply`
- registre log com status HTTP e `thread_id`

## Checklist final

- [ ] o webhook do Uazapi esta funcionando
- [ ] `from` e estavel
- [ ] `message` sai limpa
- [ ] se a chave for do tenant, `number_id` esta no body
- [ ] o envio final usa `reply`