Agente por API

POST /agents/{id}/chat põe o agente da Wevichat para responder dentro do seu sistema. É a mesma inteligência do chat público e do WhatsApp: base de conhecimento, ações que chamam sua API, transbordo para humano, eventos de conversão e etiquetas automáticas.

Serve para atender num canal que a gente ainda não suporta (seu app, um chat interno, um totem), ou para embutir o agente numa tela sua sem usar o widget.

Escopo necessário: conversations:write. Exige plano com o recurso de API. O consumo de IA sai da chave que a sua organização já cadastrou.

A chamada

curl -X POST "https://api.wevi.chat/functions/v1/agents/{id}/chat" \
  -H "Authorization: Bearer wevi_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quanto custa o clareamento?",
    "external_user_id": "cliente-8412"
  }'

const res = await fetch(
  `https://api.wevi.chat/functions/v1/agents/${agenteId}/chat`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer wevi_SUA_CHAVE",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: texto,
      external_user_id: usuario.id,
    }),
  },
);
const { message, conversation_id } = await res.json();
console.log(message.content);

Resposta:

{
  "conversation_id": "e51ba5a3-...",
  "conversation_created": true,
  "message": {
    "id": "9f2c...",
    "role": "assistant",
    "content": "O clareamento sai por R$ 800 e leva uma sessão de cerca de uma hora."
  },
  "handoff": null
}

O id do agente pode ser o UUID ou o slug público, o mesmo que aparece no link do chat.

Manter o fio da conversa

Mande sempre o mesmo external_user_id para aquele usuário. A gente acha a conversa aberta dele e continua de onde parou, com todo o histórico servindo de contexto.

Dá para enriquecer o cadastro na primeira mensagem:

{
  "message": "Oi!",
  "external_user_id": "cliente-8412",
  "user": {
    "name": "Maria Souza",
    "email": "maria@exemplo.com",
    "phone": "5511999998888",
    "metadata": { "plano": "premium" }
  }
}

Quando a resposta demora

Resposta com busca na base de conhecimento e chamada de ação pode levar dezenas de segundos. Se o seu lado não pode esperar, use o modo assíncrono:

{ "message": "...", "external_user_id": "cliente-8412", "async": true }

A resposta volta na hora com 202 e status: "processing". O texto do agente chega pelo webhook message.sent ou em GET /conversations/{id}/messages.

Transbordo e humano no meio

Quando o agente decide passar para uma pessoa, a resposta traz:

{ "handoff": { "requested": true, "pending": false } }

A conversa entra na fila de atendimento do painel. A partir daí, se alguém assumir, novas mensagens suas são registradas mas não passam pela IA:

{ "human_mode": true, "message": null, "note": "Esta conversa está com um atendente humano..." }

Mostre isso para o seu usuário como "um atendente vai responder", e acompanhe a resposta da pessoa pelo webhook message.sent.

A conversa aparece no painel

Tudo que passa por aqui vira conversa no inbox, com o canal marcado como API. A equipe vê, responde, etiqueta e encerra pelos mesmos lugares de sempre. As métricas e os eventos de conversão contam igual.

Erros

Streaming

Ainda não devolvemos a resposta token a token. Para uma interface que precisa de digitação em tempo real, use o modo assíncrono e o webhook message.sent, ou o widget de chat pronto.