> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metricaas.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversas e mensagens

> Conversa e lead, os três estados de atendimento, o interruptor da IA, e o que muda quando um agente responde pela API.

## Conversa e lead são coisas diferentes

O **lead** é o registro do CRM: de onde a pessoa veio, em que etapa do funil está,
quanto comprou. A **conversa** é a troca de mensagens com ela num canal — WhatsApp ou
Instagram —, com o estado do atendimento.

Toda conversa aponta para o seu lead (`lead_id`). As rotas e os webhooks de mensagem
falam em **conversa** (`conversation_id`): é nela que se responde, se pausa a IA e se
resolve o atendimento. As de funil e venda falam em **lead**.

> [!NOTE]
>
> A mesma pessoa no WhatsApp e no Instagram hoje são **dois leads**, cada um com a sua
> conversa. Um agente que responde nos dois canais não deve supor que conhece a pessoa
> do outro canal.

## Estados de atendimento

O atendimento diz **se alguém está falando com a pessoa agora**. Não tem relação com a
etapa do funil: um lead em "Proposta" pode ter o atendimento resolvido, e um lead
"Ganho" pode voltar a conversar.

| Estado | Quer dizer |
| - | - |
| `aguardando` | Chegou mensagem e ninguém da equipe assumiu. É a fila. |
| `em_atendimento` | Alguém da equipe assumiu ou respondeu. |
| `resolvida` | Encerrada. |

Como a conversa anda entre eles:

* **O lead escreve numa conversa resolvida** → ela reabre: volta para `em_atendimento`
  se tinha responsável, ou para `aguardando` se não tinha. Cliente que volta nunca
  some da fila.
* **Alguém da equipe responde** (pelo inbox ou pelo celular) numa conversa
  `aguardando` → ela passa para `em_atendimento`.
* **Resolver** é um clique no inbox ou
  `POST /v1/conversas/{id}/atendimento` com `{"status": "resolvida"}`.

A mensagem de um fluxo ou de um agente pela API **não** move o atendimento — ver
[abaixo](#a-fala-da-ia-e-a-fila).

## O interruptor da IA

Cada conversa tem um interruptor: a IA **pode** ou **não pode** responder ali. Ele
existe para o humano assumir sem precisar combinar nada com o fluxo do agente — a
pausa é do Metricaas, não do seu n8n.

**Pausa sozinho quando um humano responde**, pelo inbox ou pelo celular. A mensagem
de um fluxo e a do próprio agente pela API não pausam.

**Pausa também quando alguém pede:**

* o agente, com `POST /v1/conversas/{id}/ia` e `{"pausada": true, "motivo": "pediu atendente"}`
  — é como a IA chama um humano;
* alguém da equipe, pelo inbox.

**Retoma:**

* **quando alguém da equipe resolve a conversa pelo inbox** — resolver devolve a
  conversa à IA. Se o lead escrever de novo depois, o agente responde;
* pelo inbox, no bloco **Agente de IA** da conversa;
* com `POST /v1/conversas/{id}/ia` e `{"pausada": false}` — **só quando quem pausou
  foi o próprio agente** (`por: "api"`). Pausa de pessoa (`humano:…` ou `celular`)
  devolve **`409`**: quem assumiu a conversa é quem a devolve.

Resolver pela **API** (`POST /v1/conversas/{id}/atendimento`) não derruba a pausa de
uma pessoa: a conversa fica resolvida e a IA continua pausada. Assim nem um agente
confuso nem um token vazado tiram a conversa da mão de quem a assumiu.

Pausar o que já está pausado não muda nada — nem a hora, nem quem pausou: a primeira
pessoa que assumiu continua sendo a resposta para *"quem tirou a IA daqui?"*. A rota
responde `{"pausada": true, "mudou": false}`.

O estado aparece em três lugares:

| Onde | Campo |
| - | - |
| todo webhook `message.*` | `ia_pausada` — o estado **depois** daquela mensagem |
| `GET /v1/conversas/{id}` | `ia: { pausada, pausada_em, por, por_email }` — `por` diz quem pausou: `api`, `celular` ou `humano:<id da pessoa>`; `por_email` traz o e-mail dela |
| o inbox | a conversa mostra que a IA está pausada, e permite retomar |

### O que acontece quando o agente tenta responder numa conversa pausada

`POST /v1/conversas/{id}/mensagens` responde **`409`**, e o `detail` diz quem pausou e
quando. Nada é enviado.

Esse `409` é o caso normal de uma corrida: o lead escreveu, o agente começou a pensar,
e nesse meio-tempo alguém da equipe respondeu. **Descarte a resposta do agente** — o
humano já está na conversa.

> [!WARNING]
>
> Existe `"forcar": true` no corpo, que envia mesmo com a IA pausada e fica registrado
> na trilha de auditoria. Ele serve para um caso desenhado de propósito — por exemplo, a
> última mensagem do agente avisando que vai chamar alguém, quando você pausou antes de
> enviar. **Não o use como resposta automática ao `409`**: isso é o agente falando por
> cima do humano.

## A fala da IA e a fila

A mensagem enviada pela API:

* **aparece no inbox com um selo próprio**, para a equipe saber que não foi ninguém
  dela;
* **não assume a conversa** — o responsável continua o mesmo;
* **não tira a conversa da fila** — uma conversa `aguardando` continua `aguardando`
  depois que a IA responde;
* **não conta como primeira resposta do time**. O tempo de resposta da IA é medido à
  parte, para o relatório de atendimento não misturar os dois.

É o mesmo tratamento das mensagens de fluxo. Robô falando não é alguém assumindo: se
a IA responde e a conversa saísse da fila, ninguém mais olharia para ela.

## Quem escreveu: `source`

Toda mensagem tem uma origem, e ela é a mesma nos webhooks e em
`GET /v1/conversas/{id}/mensagens`:

| `source` | Quem |
| - | - |
| `lead` | o lead |
| `api` | um agente ou sistema, pela API |
| `inbox` | alguém da equipe, pelo inbox |
| `celular` | alguém da equipe, direto pelo app do WhatsApp |
| `automacao` | um fluxo do Metricaas |

Um agente que assina `message.sent` recebe de volta **as próprias mensagens**, com
`source = api`. Filtre por `source` antes de reagir a qualquer coisa.

## Enviar é assíncrono

`POST /v1/conversas/{id}/mensagens` responde **`202`** com `status: "pending"`: a
mensagem entrou na fila de envio, não saiu ainda. Depois ela passa a `sent`,
`delivered` e `read` — ou `failed`.

Para saber o que aconteceu, sem esperar o webhook:

```bash theme={null}
curl https://app.metricaas.com.br/v1/mensagens/9e3a5c71-0d2b-4e86-b1f4-6a7c8d9e0f12 \
  -H "Authorization: Bearer $METRICAAS_TOKEN"
```

Quando o envio falha, o campo `error` diz o motivo. Quando dá certo, o webhook
`message.sent` chega com `source = api`.

## Idempotência

O `POST …/mensagens` **exige** o cabeçalho `Idempotency-Key` (1 a 200 caracteres) —
sem ele, `400`. É a única defesa contra mandar a mesma mensagem duas vezes ao lead: o
WhatsApp não deduplica.

* A mesma chave já usada em **outra** conversa responde **`422`** e não envia nada.
* A mesma chave, na mesma conversa, responde **`200`** com a mensagem original e
  `"duplicate": true`. Nada é enviado de novo.
* A chave vale **para sempre** dentro da empresa.

> [!WARNING]
>
> Nunca use uma chave fixa, o id do lead ou o id da conversa como `Idempotency-Key`. A
> segunda mensagem da conversa voltaria `duplicate: true` e **não seria enviada**, sem
> erro nenhum. A chave identifica **uma tentativa de envio**: num agente que reage a
> webhook, use `resposta:<metricaas_message_id>` da mensagem que disparou a resposta.
> O `X-Metricaas-Delivery` não serve: quando o WhatsApp reentrega o mesmo evento, nós
> geramos uma entrega nova, com outro id — e a mesma mensagem.

## Limites

| Limite | Valor | Ao estourar |
| - | - | - |
| por token | 30 envios por minuto | `429` com `Retry-After` |
| por empresa | 1.000 envios por dia | `429` com `Retry-After` |

O dia é o de Brasília: o contador da empresa zera à meia-noite de São Paulo. A
repetição idempotente (`duplicate: true`) não conta. O upload de arquivo para enviar
(`POST /v1/midia`) conta no limite por minuto.

O limite diário existe para limitar o estrago de um token vazado ou de um fluxo em
laço — um agente saudável numa empresa normal não chega perto dele.

## Começar a conversa: `POST /v1/conversas`

Para falar **primeiro** com quem pediu contato (a recuperação de quem deixou o
telefone num formulário e não comprou):

```bash theme={null}
curl -X POST https://app.metricaas.com.br/v1/conversas \
  -H "Authorization: Bearer mcp_SEU_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: recuperacao-ana-2026-11-14" \
  -d '{ "phone": "11987654321", "channel": "whatsapp", "text": "Oi, Ana! Ainda quer o seu mapa?" }'
```

```json theme={null}
{
  "conversation_id": "6a1f0c2e-…", "message_id": "9b2e1d3f-…", "status": "pending",
  "agendada_para": "2026-11-14T13:02:10.000Z", "fria": true, "conversa_nova": true, "duplicate": false
}
```

Mensagem que o lead não pediu, em volume, é o que faz o WhatsApp banir o número.
Por isso as travas são as mesmas da primeira mensagem dos fluxos, na mesma fila:

| trava | o que acontece |
| - | - |
| **consentimento** | só lead de formulário (origem `form`; crie com `POST /v1/leads` e `"origem": "form"`), ou quem já escreveu nesta conversa. Senão, `409` |
| **pediu para parar** | lead com a tag **`nao-contatar`** recebe `409`, sempre. Aplique a tag quando a pessoa pedir para sair |
| **uma primeira por lead** | somando fluxos e API. Enquanto o lead não responde, as próximas entram na mesma fila |
| **em gotas** | no mínimo 60 s entre duas mensagens a frio da empresa, 100 por dia. A resposta diz quando sai (`agendada_para`); se a vaga passaria de 30 min, `429` com `Retry-After` |
| **só pela UAZAPI** | na API oficial do WhatsApp (Cloud API), começar conversa exige template aprovado, que este endpoint ainda não manda: `422` |

Se o lead **já escreveu** nesta conversa, a mensagem sai como a de
`POST /v1/conversas/{id}/mensagens`, com a mesma recusa da IA pausada (`409`, e o
`forcar`). Conversa ligada a **outro** lead com o mesmo número: `409`.

O token precisa de `inbox:operate` **e** `crm:operate`: o de finalidade **Agente de
atendimento** responde quem escreveu, mas não abre conversa nova (`403`).

O `Idempotency-Key` é obrigatório e os limites são os da tabela acima (30 por minuto
por token, 1.000 por dia por empresa). A conversa nasce **resolvida e sem dono**:
quando o lead responder, ela volta para a fila do time como qualquer outra.

## O que a API não faz

* **Template e janela de 24 horas** da API oficial do WhatsApp — inclusive para
  começar conversa (ver acima).
* **Mandar mídia de uma URL qualquer.** O arquivo precisa ser enviado antes por
  `POST /v1/midia`, que devolve a URL a usar em `media_url`. Uma URL de fora responde
  `422`. Essa URL abre o arquivo só por 10 minutos, mas segue aceita em `media_url`
  depois disso.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.