Conversas

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).

string

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.

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.

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).

string

Número no formato E.164 (+5215512345678). É normalizado para dígitos antes do lookup. Útil quando você só tem o telefone.

string

obrigatório

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).

{ "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.

A janela de 24h

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

O contato te escreve

O WhatsApp abre uma janela de 24 horas. Cada nova mensagem do contato reinicia o contador.

Janela aberta

Você pode enviar mensagens livres: texto, mídia e respostas rápidas.

Passam 24h sem resposta

A janela se fecha. A única mensagem permitida é um template aprovado pelo Meta.

Enviar um template reabre a janela

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:

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:

{
  "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

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:

{
  "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.

Introdução

Conceitos

Guias

Ações

Identificar uma conversa

Ler uma conversa

A janela de 24h

Consultar o estado da janela

Ler o histórico

Próximos passos

Enviar mensagens

Templates

​Identificar uma conversa

​Ler uma conversa

​A janela de 24h

​Consultar o estado da janela

​Ler o histórico

​Próximos passos

Enviar mensagens

Templates

Identificar uma conversa

Ler uma conversa

A janela de 24h

Consultar o estado da janela

Ler o histórico

Próximos passos