Conversas

Abra conversas, troque mensagens com o agente, passe para um humano e responda pelo seu próprio sistema.

Use a API de conversas para montar o chat com a sua própria interface. A Nevox cuida das respostas, das regras do agente e do histórico.

Ciclo de vida

Conversas abertas pela API usam o canal api. Conversas de WhatsApp, chat do site, SMS e voz também aparecem aqui: você pode ler, passar para humano, devolver, encerrar e responder como equipe (a resposta sai pelo canal de origem), mas as mensagens do cliente nelas chegam só pelo canal. Conversas da caixa de email ainda não aparecem na API.

Abrir uma conversa

POST /v1/conversations · escopo conversations:write

curl https://api.nevox.ai/v1/conversations \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c1f0e2a-1b8e-4f0e-9d0a-1d2c3b4a5e6f" \
  -d '{
    "agent_id": "agt_8f2k1x",
    "contact": { "external_id": "paciente_1042", "name": "Maria Souza" },
    "channel": "api",
    "metadata": { "tela": "minhas-consultas" }
  }'

{
  "id": "conv_7mk2p9",
  "agent_id": "agt_8f2k1x",
  "contact_id": "ctc_4hq81",
  "channel": "api",
  "status": "active",
  "metadata": { "tela": "minhas-consultas" },
  "created_at": "2026-11-03T14:30:00Z",
  "updated_at": "2026-11-03T14:30:00Z"
}

Se o contato não existir, ele é criado com o external_id informado. Os campos de contact seguem o mesmo formato de contatos.

Enviar uma mensagem do usuário

POST /v1/conversations/{id}/messages · escopo conversations:write

curl https://api.nevox.ai/v1/conversations/conv_7mk2p9/messages \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Quero remarcar minha consulta de quinta" }'

{
  "user_message": {
    "id": "msg_a1",
    "role": "user",
    "content": "Quero remarcar minha consulta de quinta",
    "created_at": "2026-11-03T14:30:05Z"
  },
  "agent_message": {
    "id": "msg_a2",
    "role": "agent",
    "content": "Claro, Maria. Tenho estes horários livres com a Dra. Lima: sexta às 10h ou segunda às 15h. Qual prefere?",
    "actions_called": [
      { "name": "horarios_livres", "status": "succeeded" }
    ],
    "created_at": "2026-11-03T14:30:07Z"
  },
  "conversation_status": "active"
}

Quando a conversa está em handoff ou human, o agente não responde: agent_message vem como null. O campo actions_called lista as ações que o agente chamou para escrever a resposta, com a situação de cada uma (succeeded, failed, timeout, refused ou confirm, quando pediu confirmação).

As conversas pela API contam na franquia de conversas do plano (a conversa conta no mês em que o agente responde). Acabou a franquia, mensagem em conversa nova recebe 429 monthly_quota_exceeded. Conversas de chave de teste não contam.

Resposta em tempo real (streaming)

Envie "stream": true para receber a resposta aos poucos, em Server-Sent Events:

curl -N https://api.nevox.ai/v1/conversations/conv_7mk2p9/messages \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Quais horários vocês têm amanhã?", "stream": true }'

event: message.started
data: {"id":"msg_a4"}

event: action.called
data: {"name":"horarios_livres","status":"succeeded"}

event: message.delta
data: {"delta":"Amanhã tenho "}

event: message.delta
data: {"delta":"10h e 14h livres."}

event: message.completed
data: {"id":"msg_a4","content":"Amanhã tenho 10h e 14h livres.","conversation_status":"active"}

Outros eventos possíveis: handoff (o agente passou para humano) e error. O texto chega em partes por frase.

Listar e ler

Escopo conversations:read. Listas usam paginação por cursor.

Passar para um humano

O agente passa para humano sozinho quando aparece reclamação, reembolso, pedido especial ou um assunto que você marcou no painel. Você também pode forçar:

POST /v1/conversations/{id}/handoff

{ "reason": "Paciente pediu para falar com a recepção" }

A conversa vai para handoff e a Nevox dispara o webhook conversation.handoff, com o motivo. O resumo da conversa (summary) é gerado pela IA logo depois e aparece em GET /v1/conversations/{id}.

Quando é o agente que passa para humano, o motivo vem em handoff_reason: complaint, refund_request, special_request, forbidden_topic, user_asked_human, low_confidence ou action_failed. Pelo endpoint acima, manual.

Responder como alguém da equipe

Quando alguém da sua equipe responde pelo seu sistema, envie a mensagem com role: "staff":

curl https://api.nevox.ai/v1/conversations/conv_7mk2p9/messages \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "staff",
    "content": "Oi Maria, aqui é a Carla da recepção. Já ajustei o reembolso.",
    "author": { "id": "func_33", "name": "Carla" }
  }'

A primeira mensagem de staff muda o status para human. Se a conversa veio do WhatsApp ou do SMS, a Nevox entrega a resposta no canal de origem (com chave de produção; chave de teste recebe 409 test_key_channel). No chat do site, o visitante vê a resposta no chat.

Devolver para o agente

POST /v1/conversations/{id}/resume: volta para active, e o agente retoma o atendimento.

Encerrar

POST /v1/conversations/{id}/close

{ "resolution": "resolved" }

Valores de resolution: resolved, unresolved, spam. O encerramento dispara o webhook conversation.closed. Conversas da API sem mensagem por 24 horas são encerradas automaticamente com resolution: "inactive". Uma conversa de canal encerrada volta a ficar ativa quando o cliente manda mensagem nova.

O que o agente nunca faz

As regras configuradas no painel valem também na API. O agente:

• não inventa preços, horários ou informações;
• não pede cartão, senha ou documentos;
• não dá orientação médica, jurídica ou financeira;
• não fala de assuntos que você proibiu.