Chat

Chat

O endpoint de Chat em tempo real envia uma mensagem do visitante ao seu Agente de IA e retorna a resposta da IA em uma única ida e volta. Este é o endpoint que você quer ao construir uma interface de chat personalizada sobre o Quickchat AI.

Ele difere dos outros endpoints de duas formas: fica em app.quickchat.ai/chat, fora dos caminhos base /v1/api/ e /v1/api_core/, e lê o scenario_id do corpo da requisição em vez do token. Usa a mesma autenticação por Bearer token que o restante desta API.

Nota

Envie todas as requisições para https://app.quickchat.ai/chat. O scenario_id no corpo deve corresponder ao Agente de IA ao qual seu Bearer token está vinculado.

Enviar Mensagem

POST https://app.quickchat.ai/chat

Request Body

Parameter	Description
scenario_id string, required	ID do seu Agente de IA. Deve corresponder ao scenario_id vinculado ao Bearer token
text string, required	Mensagem de entrada do usuário
conv_id string	ID da conversa. Omita na primeira requisição para iniciar uma nova conversa, depois envie de volta o conv_id retornado nas requisições seguintes para continuá-la
client_metadata object	Pares chave-valor personalizados (recomendamos no máximo 5 chaves) anexados a cada mensagem. Exibidos como colunas de dados na exportação de conversas na Inbox

Uma requisição sem conv_id inicia uma nova conversa, e o conv_id gerado é retornado na resposta. Armazene esse conv_id e envie-o de volta nas requisições posteriores para manter o contexto da conversa ao longo de múltiplas interações do usuário.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Response 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Field	Description
conv_id string	Identificador da conversa. Sempre retornado. Envie-o de volta no campo conv_id do corpo para continuar a conversa
reply string	A resposta do Agente de IA. Pode conter HTML, como quebras de linha <br>
ord_number integer	Número sequencial da mensagem dentro da conversa
src integer	Indicador interno de origem. Clientes da API podem ignorar este campo

Para continuar uma conversa existente, envie de volta o conv_id que você recebeu:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Client Metadata

O endpoint de Chat aceita um parâmetro client_metadata opcional: atributos personalizados que são atribuídos a cada nova mensagem e exibidos como colunas de dados na exportação de conversas na Inbox. Você pode anexar os mesmos atributos através do widget. Recomendamos enviar no máximo 5 chaves de cada vez, por exemplo {"userId": 12, "website": "mywebsite.com"}. Isso é uma recomendação, não um limite imposto pela API.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Filtragem por Tags da Base de Conhecimento

Você pode adicionar tags aos artigos da Base de Conhecimento e usá-las para restringir em quais artigos a IA se baseia, de modo que ela responda apenas com base em um subconjunto da Base de Conhecimento. Atualmente, essa filtragem é suportada somente via API.

Para filtrar por tag, adicione uma chave kb_topic ao client_metadata. A chave kb_topic deve estar presente em todas as requisições da conversa, incluindo a requisição que a inicia. Seu valor pode mudar entre requisições, mas a chave em si precisa estar presente durante toda a conversa para que o filtro seja aplicado.

No exemplo abaixo, qualquer artigo com a tag your-topic, ou sem nenhuma tag, é incluído no conjunto de candidatos de conhecimento para a resposta.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Erros

O endpoint de Chat retorna uma mensagem de erro em texto simples com um código de status HTTP apropriado.

Status	Description	Action
400	scenario_id ausente ou nenhuma credencial fornecida	Inclua scenario_id no corpo e um header Authorization: Bearer <API_TOKEN> válido
400	conv_id inválido (Conversation conv_id <id> is not valid.)	Omita conv_id para iniciar uma nova conversa, ou envie um conv_id retornado por uma resposta anterior
401	Credenciais inválidas (Unauthorized.)	Verifique se seu Bearer token ou chave de API é válido para este scenario_id
404	scenario_id desconhecido (No implementation found for scenario_id <id>)	Verifique o scenario_id e se seu Bearer token está vinculado a ele
500	Erro interno do servidor	Um problema do nosso lado. Por favor, entre em contato com o suporte
503	Serviço indisponível	Os servidores estão temporariamente sobrecarregados ou em manutenção. Se o problema persistir, por favor entre em contato com o suporte