Conversas
Liste as conversas, leia o histórico de mensagens, saiba o que a IA está fazendo e feche, adie ou atribua uma conversa.
Cada contato tem uma única conversa com a loja, que guarda todo o histórico. Quando o cliente escreve de novo, ou quando você envia algo para ele, uma conversa fechada ou adiada é reaberta em vez de começar outra.
GET /conversations
Lista as conversas, das que tiveram movimento mais recente para as mais antigas. Acesso: chave secreta (leitura).
| Parâmetro | Descrição |
|---|---|
status | open, closed ou snoozed (adiada) |
page, pageSize | Paginação: padrão 50, máximo 100 |
curl "https://vamo.ai/api/v1/conversations?status=open&pageSize=20" \
-H "Authorization: Bearer sk_live_SUA_CHAVE"Resposta 200
{
"data": [
{
"id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
"status": "open",
"unreadCount": 2,
"lastMessagePreview": "Tem a capinha MagSafe na cor azul?",
"updatedAt": "2026-10-31T13:02:11.000Z",
"createdAt": "2026-09-12T10:00:00.000Z",
"contactId": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
"contactName": "Mariana Costa",
"contactPhone": "+5511987654321",
"aiEnabled": true,
"activity": "queued"
}
],
"pagination": { "page": 1, "pageSize": 20, "total": 37 }
}GET /conversations/:id
Uma conversa, com os mesmos campos da lista e mais assignedTo (o ID de usuário do membro responsável, ou null). Acesso: chave secreta (leitura). Responde 404 not_found (Conversation not found) se ela não existe ou é de outra organização.
curl https://vamo.ai/api/v1/conversations/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716 \
-H "Authorization: Bearer sk_live_SUA_CHAVE"O que a IA está fazendo
aiEnabled diz se a IA pode responder essa conversa. activity diz o que está acontecendo agora:
activity | Significa |
|---|---|
idle | Nada pendente |
queued | A IA vai responder em instantes (está esperando o cliente terminar de escrever) |
generating | A IA está escrevendo a resposta |
draft_review | Uma resposta da IA espera a aprovação da equipe |
ai_dismissed | A IA passou a conversa para a equipe |
waiting_follow_up | A IA precisa que a equipe complete uma informação para voltar ao cliente |
internal_error | A IA não conseguiu responder por uma falha técnica |
waiting | A IA não vai responder agora: foi desligada, está pausada, a janela de 24 horas fechou, ou uma pessoa da equipe está respondendo |
ai_dismissed e waiting_follow_up são as conversas que aparecem em Precisa de você na caixa de entrada. Novos valores podem surgir: trate um valor desconhecido como idle. As regras por trás de cada estado estão em Estados da conversa.
PATCH /conversations/:id
Fecha, reabre, adia ou atribui uma conversa. Acesso: chave secreta com Leitura e escrita.
| Campo | Tipo | Descrição |
|---|---|---|
status | string | open, closed ou snoozed |
assignedTo | string ou null | O ID de usuário de um membro da organização, ou null para tirar o responsável. Quem não é membro: 404 not_found (Member not found) |
curl -X PATCH https://vamo.ai/api/v1/conversations/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716 \
-H "Authorization: Bearer sk_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "status": "closed" }'Resposta 200
{
"data": {
"id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
"storeId": "7b1e2c3d-4a5f-4b6c-8d7e-9f0a1b2c3d4e",
"contactId": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
"status": "closed",
"assignedTo": null,
"unreadCount": 0,
"lastMessagePreview": "Obrigada! Chegou certinho.",
"snoozedUntil": null,
"aiEnabled": true,
"activity": "idle",
"updatedAt": "2026-10-31T13:02:11.000Z",
"createdAt": "2026-09-12T10:00:00.000Z"
}
}O que cada mudança faz:
| Você envia | O que acontece |
|---|---|
"status": "closed" | A conversa fecha e volta para idle: rascunhos da IA esperando aprovação são descartados, um retorno agendado é cancelado e uma automação em andamento para. Se a conversa estava com a equipe, ela é devolvida: a próxima mensagem do cliente reabre a conversa e a IA volta a responder (se aiEnabled for true). Dispara conversation.closed |
"status": "open" | Reabre. Uma conversa que não estava aberta sobe para o topo da caixa de entrada. Dispara conversation.updated |
"status": "snoozed" | Adia sem data de fim: ela some da aba Todas e volta quando o cliente escrever ou alguém reabrir. Dispara conversation.updated |
assignedTo | Define ou tira o responsável. Dispara conversation.updated |
Fechar uma conversa que já está fechada não refaz nada disso.
Sem nenhum desses campos, ou com status fora da lista: 400 validation_error.
GET /conversations/:id/messages
O histórico de mensagens da conversa. Acesso: chave secreta (leitura).
| Parâmetro | Descrição |
|---|---|
page, pageSize | Padrão 50, máximo 100 |
A página 1 traz as mensagens mais recentes, e dentro da página elas vêm em ordem cronológica (a mais antiga primeiro). Para ler mais para trás, aumente page. Rascunhos da IA que esperam aprovação, ou que foram descartados, não aparecem.
curl "https://vamo.ai/api/v1/conversations/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716/messages?pageSize=2" \
-H "Authorization: Bearer sk_live_SUA_CHAVE"Resposta 200
{
"data": [
{
"id": "0b1c2d3e-4f5a-4b6c-9d7e-8f9a0b1c2d3e",
"conversationId": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
"senderType": "customer",
"content": "Tem a capinha MagSafe na cor azul?",
"status": "delivered",
"source": "chat",
"createdAt": "2026-10-31T13:01:50.000Z"
},
{
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"conversationId": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
"senderType": "ai",
"content": "Tenho sim, Mariana! A capinha MagSafe azul para iPhone 15 sai por R$ 89,90. Quer que eu separe uma?",
"status": "read",
"source": "chat",
"createdAt": "2026-10-31T13:02:11.000Z"
}
],
"pagination": { "page": 1, "pageSize": 2, "total": 214 }
}Os campos de cada mensagem estão em Mensagens.