> ## Documentation Index > Fetch the complete documentation index at: https://dev.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, mais `channel` (**obrigatório**), a chave pública do canal objetivo. 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). Chave estável de uma conversa que você já conhece (por exemplo, persistida de uma integração anterior). O caminho mais direto, embora possa ficar obsoleto se duas conversas do mesmo contato forem unificadas — veja a nota de unificação abaixo. 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. 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`). Número no formato E.164 (`+5215512345678`). É normalizado para dígitos antes do lookup. Útil quando você só tem o telefone. Chave pública do canal — copie-a do dashboard em **Configurações → Canais** (campo **Chave do canal**), ou liste-as com `GET /channels`. **Obrigatório** em toda requisição: fixa o canal objetivo. Não diferencia maiúsculas de minúsculas (é normalizado no servidor). Não identifica sozinho. Nas vias por contato (`phone`, `username`, `whatsapp_user_id`) restringe a resolução ao canal indicado; com `uuid` o motor o ignora, mas o contrato o exige mesmo assim. Desambigua o **canal**, não o **contato**: se vários contatos compartilham `phone` ou `username`, essa ambiguidade se resolve com `whatsapp_user_id` ou `uuid`. Nas vias por contato, se você enviar uma chave que não existe, a API responde `404` (`CHANNEL_NOT_FOUND`). ```jsonc theme={null} { "conversation": { "phone": "+52 55 1234 5678", "channel": "ch_7A9K2M4Q" } } // equivalente: { "conversation": { "uuid": "7b8a1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "channel": "ch_7A9K2M4Q" } } ``` 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. `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`. 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`. `channel` é **obrigatório em toda requisição**: você sempre fixa o canal objetivo com sua chave pública (liste-as com `GET /channels`). Assim, se um contato tem conversas em **mais de um canal** (vários números de WhatsApp), a resolução por `phone`, `username` ou `whatsapp_user_id` já sabe qual você quer apontar. Uma chave que não existe responde `404` (`CHANNEL_NOT_FOUND`). ## Ler uma conversa Você se dirige a uma conversa com uma das referências acima: a API pública não oferece uma listagem para enumerá-las. Essas referências vêm do seu próprio inbound —o `phone` ou o `whatsapp_user_id` do contato que te escreveu— ou de um `uuid` que você tenha persistido. Com essa referência, `GET /conversation` retorna seu estado (`conversation_info` e `contact_info`) e `GET /conversation/messages` seu histórico. O shape completo e os parâmetros estão em [Conversa e histórico](/pt/action-groups/query-conversation). ## A janela de 24h É o conceito central do WhatsApp e decide o que você pode enviar. O WhatsApp abre uma **janela de 24 horas**. Cada nova mensagem do contato reinicia o contador. Você pode enviar mensagens livres: texto, mídia e respostas rápidas. A janela se fecha. A única mensagem permitida é um **template** aprovado pelo Meta. Você volta a poder enviar mensagens livres. Enviar texto, mídia ou uma resposta rápida com a janela fechada falha com `WINDOW_CLOSED` (422). Envie um template primeiro para reabri-la. ## 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", "channel": "ch_7A9K2M4Q" } }' ``` Resposta: ```jsonc theme={null} { "conversation": { "uuid": "7b8a2c1d-3e4f-…", "phone": "5215512345678", "whatsapp_user_id": "5215512345678" }, "window": { "status": "open", "expires_at": "2026-07-21T18:30:00Z", "hours_remaining": 18.5 }, "assignment": { "type": "ai_employee", "ai_employee": { "uuid": "1a2b…", "name": "Aura" } }, "mailbox": { "uuid": "5c6d…", "name": "Vendas" }, "tags": [{ "uuid": "9e0f…", "name": "VIP", "color": "#22c55e" }], "inbox_status": "pending", "last_message": null, "is_tester": false, "tester_virtual_now": null } ``` A resposta inclui `conversation.uuid` (a chave estável da conversa), `window.status` (`open` ou `closed`), `window.expires_at` (timestamp ISO do fechamento da janela; `null` se o contato nunca escreveu) 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. ## Ler o histórico ```http theme={null} GET /conversation/messages?phone=+5215512345678&limit=50 ``` Retorna as mensagens e os eventos da conversa. Ela é identificada com a mesma referência que o resto da API, então **não é preciso conhecer nenhum uuid**. O histórico é paginado **para trás no tempo**: a primeira chamada traz os itens mais recentes e `next_cursor` avança em direção aos mais antigos. Cada item responde quatro perguntas: quem falou (`direction` e `author`), o que aconteceu (`event`), com qual conteúdo (`content_type` e `body`) e quando (`sent_at`). Lidos em ordem, se parecem com a conversa real: ``` --- 2 de julho de 2026 --- contact message_received text "Olá, o pacote premium está disponível?" business message_sent text "Bom dia! Sim, o pacote premium está disponível." └ Funcionário AI: Vendas noturnas business context_note "O cliente pediu um orçamento formal por e-mail." └ Integração CRM (via API) ``` E é assim que viaja no JSON: ```json theme={null} { "items": [ { "type": "message", "direction": "contact", "event": "message_received", "content_type": "text", "body": "Olá, o pacote premium está disponível?", "author": { "type": "customer", "name": "Ana Pérez" }, "status": "delivered", "sent_at": "2026-07-02T14:39:00.000Z" }, { "type": "message", "direction": "business", "event": "message_sent", "content_type": "text", "body": "Bom dia! Sim, o pacote premium está disponível.", "author": { "type": "ai_employee", "name": "Vendas noturnas" }, "status": "read", "sent_at": "2026-07-02T14:39:12.000Z" } ], "next_cursor": "MjAyNi0wNy0wMlQxNDozOTowMC4wMDBafDkxODIz", "has_more": true } ``` **`type`** distingue as duas classes de item: `message` é conteúdo que viajou pelo WhatsApp (traz `content_type` e `status`), e `event` é algo que aconteceu no histórico — uma nota de contexto, um dado do contato atualizado, uma conversão — sem conteúdo enviado. A ordem dentro de cada página é cronológica, e `sent_at` é a chave que ordena o histórico completo à medida que você pagina para trás. ## Próximos passos Texto, mídia, respostas rápidas e templates. Como enviar templates com a janela de 24h fechada.