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

# Conversas

> Como uma conversa é identificada e por que a janela de 24h decide o que você pode enviar.

Uma conversa é o thread de WhatsApp entre o seu negócio e um contato. Quase
todos os endpoints de envio e de ações (`/conversation/*`) a recebem no corpo
da requisição sob o objeto `conversation`.

## Identificar uma conversa

O objeto `conversation` aceita **um** de quatro identificadores. O resolver
avalia nesta ordem: `uuid` → `whatsapp_user_id` → `username` → `phone`:
`whatsapp_user_id` busca por igualdade exata e `username` por igualdade
case-insensitive (ignora maiúsculas); `phone` é normalizado para dígitos.
Quando o contato tem BSUID, `phone` e
`whatsapp_user_id` identificam valores distintos (veja Note).

<ParamField body="uuid" type="string">
  O UUID de um `GET /conversations`. O caminho mais direto e estável (pode ficar
  obsoleto se duas conversas do mesmo contato forem unificadas — veja a nota de
  unificação abaixo).
</ParamField>

<ParamField body="whatsapp_user_id" type="string">
  O BSUID do contato (identidade opaca do Meta). Resolve por igualdade exata
  contra o BSUID armazenado; se não resolver, o endpoint responde `404` sem cair
  para `phone`. Identificador recomendado daqui em diante.
</ParamField>

<ParamField body="username" type="string">
  Username público de WhatsApp do contato, com ou sem `@` inicial e sem
  distinguir maiúsculas. Resolução best-effort contra o último username
  observado pela plataforma (o usuário pode mudar seu handle); se vários
  contatos o compartilham, o endpoint responde `409` (`USERNAME_AMBIGUOUS`).
</ParamField>

<ParamField body="phone" type="string">
  Número no formato E.164 (`+5215512345678`). É normalizado para dígitos antes do
  lookup. Útil quando você só tem o telefone.
</ParamField>

```jsonc theme={null}
{ "conversation": { "phone": "+52 55 1234 5678" } }
// equivalente: { "conversation": { "uuid": "7b8a..." } }
```

<Warning>
  O telefone pode estar **duplicado** entre contatos (números reciclados ou
  identidades separadas que compartilham o número): nesse caso a API responde
  `409` (`PHONE_NUMBER_AMBIGUOUS`) em vez de adivinhar — identifique a conversa
  por `whatsapp_user_id` ou `uuid`. Além disso, `whatsapp_user_id` pode **mudar**
  se o usuário registrar novamente sua conta de WhatsApp (rotação de identidade
  do lado do Meta). Use o `uuid` como chave estável no seu sistema e
  `whatsapp_user_id` como identificador de resolução preferencial.
</Warning>

<Note>
  `phone` e `whatsapp_user_id` são identificadores **distintos**: `phone` é o
  telefone (wa\_id sem `+`) e `whatsapp_user_id` é o BSUID do contato. Coincidem
  apenas enquanto o contato não tem BSUID. Nas respostas, `whatsapp_user_id`
  retorna o BSUID real quando existe, com fallback para o telefone para que sempre
  haja um valor resolvível. Atenção no round-trip: se o contato ainda não tem BSUID,
  este campo traz o telefone; reenvie-o então como `phone`, não como
  `whatsapp_user_id` — o resolver casa `whatsapp_user_id` por igualdade exata e
  responderia `404`.
</Note>

<Note>
  Quando o mesmo contato acabou registrado duas vezes por identidade (por exemplo,
  primeiro só com o telefone e depois com o BSUID), as duas conversas são
  **unificadas automaticamente** em uma só: todo o histórico passa para a
  sobrevivente. O `uuid` da conversa absorvida deixa de resolver e responde `404`; o
  telefone e o BSUID migram para a sobrevivente. Se um `uuid` que você guardou
  começar a dar `404`, resolva a conversa novamente por `phone` ou
  `whatsapp_user_id`.
</Note>

## A janela de 24h

É o conceito central do WhatsApp e decide o que você pode enviar.

<Steps>
  <Step title="O contato te escreve">
    O WhatsApp abre uma **janela de 24 horas**. Cada nova mensagem do contato
    reinicia o contador.
  </Step>

  <Step title="Janela aberta">
    Você pode enviar mensagens livres: texto, mídia e quick replies.
  </Step>

  <Step title="Passam 24h sem resposta">
    A janela se fecha. A única mensagem permitida é um **template**
    aprovado pelo Meta.
  </Step>

  <Step title="Enviar um template reabre a janela">
    Você volta a poder enviar mensagens livres.
  </Step>
</Steps>

<Warning>
  Enviar texto, mídia ou quick reply com a janela fechada falha com
  `WINDOW_CLOSED` (422). Envie um template primeiro para reabri-la.
</Warning>

## Consultar o estado da janela

Antes de enviar uma mensagem livre, você pode verificar se a janela está aberta
com `POST /conversation/status`:

```bash theme={null}
curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/status" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "conversation": { "phone": "+5215512345678" } }'
```

A resposta inclui `window.status` (`open` ou `closed`) e
`window.hours_remaining`, além do estado de atribuição, caixa de entrada, tags e
`inbox_status` da conversa. Use-o para decidir entre uma mensagem livre e
um template.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Enviar mensagens" icon="paper-plane" href="/pt/messages">
    Texto, mídia, quick replies e templates.
  </Card>

  <Card title="Templates" icon="newspaper" href="/pt/templates">
    Como enviar templates com a janela de 24h fechada.
  </Card>
</CardGroup>