Saltar para o conteúdo principal

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.

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 três identificadores. O resolver os prioriza nesta ordem: uuid → whatsapp_user_id → phone.
​
uuid
string
O UUID de um GET /conversations. O caminho mais direto e estável.
​
whatsapp_user_id
string
O identificador do contato no Meta. Recomendado para clientes novos — sobrevive à migração para BSUID.
​
phone
string
Número no formato E.164 (+5215512345678). É normalizado para dígitos antes do lookup. Útil quando você só tem o telefone.
{ "conversation": { "phone": "+52 55 1234 5678" } }
// equivalente: { "conversation": { "uuid": "7b8a..." } }
phone e whatsapp_user_id apontam hoje para o mesmo valor. Coexistem para a transição do Meta para identificadores alfanuméricos (BSUID). Se você está começando do zero, guarde whatsapp_user_id.

​
A janela de 24h

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

O contato te escreve

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

Janela aberta

Você pode enviar mensagens livres: texto, mídia e quick replies.
3

Passam 24h sem resposta

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

Enviar um template reabre a janela

Você volta a poder enviar mensagens livres.
Enviar texto, mídia ou quick reply 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" } }'
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

Enviar mensagens

Texto, mídia, quick replies e templates.

Templates

Como enviar templates com a janela de 24h fechada.