Skip to main content
Endpoint · GET /conversation (detalhe) e GET /conversation/messages (histórico)
Endpoints de somente consulta: retornam informação e não modificam nada. Não são enviados dentro do array actions — você os chama diretamente.
São as duas leituras que dão contexto antes de operar sobre uma conversa. GET /conversation responde em que estado ela está (janela de 24h, caixa de entrada, funcionário AI, etiquetas) e quem é o contato; GET /conversation/messages responde o que foi dito, em que ordem e por quem. Com o primeiro você decide qual ação é válida (por exemplo, com a janela fechada só é possível enviar um template); com o segundo você redige a resposta com o histórico à vista. Ambos identificam a conversa com a mesma referência que o resto da API, porém passada por query params em vez do corpo: exatamente um de phone, username, whatsapp_user_id ou uuid, mais channel.

​
Detalhe da conversa

Parâmetros
  • phone — telefone no formato E.164. É normalizado para dígitos antes do lookup.
  • username — username público de WhatsApp do contato. É normalizado (remove o @ inicial, ignora maiúsculas).
  • whatsapp_user_id — BSUID do contato (identidade opaca da Meta). Igualdade exata, sem normalizar.
  • uuid — UUID interno do 1TO1 AI, se você já o tiver salvo.
  • channel — chave pública do canal (obrigatório em toda requisição). Liste-as com GET /channels. Não diferencia maiúsculas de minúsculas. Fixa o canal objetivo; nos caminhos por contato restringe a resolução a esse canal, e com uuid o resolver o ignora, mas o contrato continua exigindo-o.
Exatamente um de phone, username, whatsapp_user_id ou uuid deve vir: zero ou dois identificadores respondem 400 (INVALID_REQUEST).

​
Resposta

window_open é o campo que decide o que você pode enviar: se for false, a única mensagem permitida é um template aprovado. window_expires_at vem como null quando o contato nunca escreveu (a janela nunca foi aberta), e inbox_status é pending ou resolved. mailbox e ai_employee são null quando a conversa não tem caixa de entrada ou funcionário AI atribuído. is_tester marca se a conversa foi criada a partir do módulo de testes.
Em contact_info, whatsapp_user_id retorna o BSUID real quando ele existe, com fallback para o telefone enquanto a Meta não migrar. Se o valor recebido for o telefone, reenvie-o como phone e não como whatsapp_user_id — o resolver casa BSUIDs por igualdade exata e retornaria 404.
Erros
  • 400 INVALID_REQUEST — a referência traz zero ou dois identificadores, ou falta channel.
  • 404 CONVERSATION_NOT_FOUND — a conversa não existe ou pertence a outro negócio. CHANNEL_NOT_FOUND — a chave de canal não existe.
  • 409 PHONE_NUMBER_AMBIGUOUS / USERNAME_AMBIGUOUS — vários contatos compartilham esse telefone ou esse username. Identifique por whatsapp_user_id ou uuid.

​
Exemplo

Uma leitura pura: consulta o estado e não altera nada da conversa.
Se a resposta trouxer "window_open": false, a ação correspondente é enviar um template; se trouxer true, você pode enviar texto, mídia ou uma resposta rápida.

​
Histórico de mensagens e eventos

Retorna as mensagens e os eventos do histórico. É identificado com a mesma referência, então não é preciso conhecer nenhum uuid. Parâmetros
  • phone / username / whatsapp_user_id / uuid — a referência da conversa, com a mesma regra: exatamente um.
  • channel — chave pública do canal (obrigatório).
  • cursor — cursor opaco retornado pela página anterior em next_cursor (até 512 caracteres). Não reutilize cursores entre endpoints distintos.
  • limit — itens por página. Padrão 50, máximo 100.
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. has_more em true significa que ainda restam itens mais antigos por ler. A ordem dentro da página é cronológica e não é configurável (não existe parâmetro order).

​
Resposta

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).
  • type — message ou event. Discrimina a união: os SDKs auto-gerados o expõem como tagged union.
  • direction — contact (enviado pela pessoa do outro lado) ou business (saiu do seu negócio).
  • author.type — customer, human, ai_employee, api_token, mass_campaign ou system. author.name pode ser null.
  • event — nos itens message: message_received ou message_sent. Nos itens event: context_note, contact_name_updated, contact_phone_updated, contact_email_updated, scheduled_cancel ou conversion.
  • content_type — nos itens message: text, image, audio, video, document, location, sticker, contacts, template, interactive ou reaction. Sempre null nos itens event.
  • status — nos itens message: pending, sent, delivered, read ou failed. Sempre null nos itens event.
  • sent_at — relógio de negócio do item e chave de ordenação do histórico. Sempre presente.
Erros
  • 400 INVALID_REQUEST — referência inválida. INVALID_CURSOR — cursor corrompido ou não emitido por este endpoint.
  • 404 CONVERSATION_NOT_FOUND / CHANNEL_NOT_FOUND.
  • 409 PHONE_NUMBER_AMBIGUOUS / USERNAME_AMBIGUOUS.

​
Exemplo

Também é uma leitura: percorrer o histórico completo não altera a conversa nem marca nada como lido.
Próxima página (itens mais antigos), com o next_cursor da resposta anterior:
Com o estado e o histórico em mãos, a escrita passa pelas ações: Enviar mensagem para responder e Alterar estado da conversa para marcá-la como resolvida ou pendente. O contexto completo da referência e da janela de 24h está em Conversas.