Conversa

Converse com a IA no seu próprio app ou sistema de atendimento, com suporte a streaming, transferência da conversa para um atendente humano, encerramento e avaliação.

POST /v1/chat

{
  "message": "有没有 400 美元以内的潜水表？",
  "conversation_id": null,
  "user": {"id": "u_123", "name": "李四", "email": "li@example.com", "ip": "85.214.132.117", "language": null},
  "stream": false
}

Se conversation_id não for enviado, uma nova conversa é criada; ela é retornada na resposta e deve ser incluída nas mensagens seguintes.
O user é enviado diretamente pelo seu servidor para nós (quem chama a API Key é confiável); somente com ele é possível consultar pedidos.
Idioma padrão da resposta: se user.language for enviado (por exemplo, de, zh-CN, pt-BR), ele será usado; caso contrário, envie user.ip e determinamos pelo local; se nenhum for enviado, usamos o idioma padrão do painel. Se o cliente pedir para trocar o idioma durante a conversa, a solicitação do cliente prevalece.
Com stream: false, retorna {"conversation_id", "message", "status", "products"}; message igual a null indica que a conversa está em atendimento humano e a mensagem foi encaminhada a um atendente.
Com stream: true, retorna SSE; os eventos estão na tabela abaixo.

Evento `type`	Conteúdo
`user_message`	Mensagem do usuário já salva
`delta`	Um trecho de texto `text` da resposta; concatene na ordem
`products`	Cartões de produtos encontrados pela IA
`language`	O cliente pediu para trocar o idioma da resposta; `language` é o novo código de idioma
`status`	Mudança de status da conversa (por exemplo, transferência para atendimento humano)
`replace`	Substitui toda a resposta já recebida por `text` (em caso de erro, troca por uma mensagem padrão)
`queued_for_human`	A conversa está em atendimento humano e não há resposta da IA
`done`	Mensagem final salva e status da conversa
`error`	Erro

Outros endpoints

Método	Caminho	Descrição
GET	`/v1/conversations`	Lista de conversas, `?status=&end_user_id=`
GET	`/v1/conversations/{id}/messages`	Conversa e todas as mensagens
POST	`/v1/conversations/{id}/messages`	Seu sistema de atendimento responde como atendente humano: `{"content", "agent_name"}`; a conversa entra imediatamente em atendimento humano
POST	`/v1/conversations/{id}/status`	Ação do lado do atendimento: `{"status": "ai"}` devolve para a IA, `{"status": "closed"}` encerra a conversa
POST	`/v1/conversations/{id}/close`	O cliente encerra a conversa no seu app; se já estiver encerrada, também retorna sucesso
POST	`/v1/conversations/{id}/rating`	Avaliação do cliente após o encerramento: `{"rating": "good" \| "bad", "comment": "opcional, no máximo 500 caracteres"}`; pode ser alterada

Status da conversa: ai (resposta da IA), pending_human (aguardando atendente), human (em atendimento humano), closed (encerrada).

A conversa também contém: closed_by quem encerrou (customer cliente, agent atendente, ai a IA encerrou depois que o cliente indicou não ter mais dúvidas), rating / rating_comment / rated_at avaliação do cliente.

Encerrar a conversa: no cabeçalho da janela web há um botão “Encerrar conversa” (com confirmação); no mini programa do WeChat, o cliente também encerra ao enviar “encerrar”; com a opção “A IA encerra a conversa automaticamente” ativada em “Configurações do bot”, quando o cliente indica claramente não ter mais dúvidas, a IA se despede e encerra a conversa. Após o encerramento, na janela web o cliente é convidado a avaliar como satisfeito / insatisfeito e pode deixar um comentário; no WeChat, o cliente é convidado a responder 1 ou 2; mensagens enviadas depois disso iniciam uma nova conversa.

Distribuição após transferência para atendimento humano: em “Configurações do bot”, escolha o modo de distribuição — para o atendente com menos conversas em andamento (padrão), distribuição alternada, ou o próprio atendente assume. A distribuição automática só é feita para atendentes com status “online” e com a página do painel aberta; cada um tem um limite de atendimentos simultâneos (definido na página “Equipe”); se o atendente designado não responder dentro do tempo definido (2 minutos por padrão), a conversa é redistribuída. Na conversa, assigned_member_id é o atendente designado, assigned_at é o horário da distribuição e handoff_at é o horário da transferência para atendimento humano. Quando todos estão no limite, o cliente entra na fila e a janela web mostra quantas pessoas estão à frente.

Horário de funcionamento e mensagens: com o horário de funcionamento ativado em “Configurações do bot”, fora do horário, a transferência para atendimento humano do cliente não entra na fila; a janela web exibe um formulário de mensagem (nome, e-mail ou telefone, dúvida), e nas conversas do WeChat e da API aberta a IA solicita que o cliente deixe uma mensagem; o mesmo vale quando não há atendente online dentro do horário de funcionamento. As mensagens geram tickets; quando o atendente responde, se a conversa original ainda não tiver sido encerrada, a resposta é enviada na conversa, e se o cliente deixou e-mail, um e-mail também é enviado em nome da loja. Quando o envio é apenas para o seu sistema (modo de transferência “Enviar para o meu sistema”), o horário de funcionamento não é considerado.

Esta página foi útil?

Última atualização: 31 de outubro de 2026