API (Legacy)

Aviso de Descontinuação

Esta página documenta a API de Chat legada utilizando autenticação por API Key. Para a nova API com Bearer token com acesso aos endpoints de Base de Conhecimento, Conversas e AI Actions, veja API.

Neste guia, passamos pelos passos necessários para integrar seu Assistente de IA Quickchat personalizado ao seu produto via endpoint de API.

Autenticação

Inclua sua API Key e scenario_id em cada requisição.

Para obter sua chave de API, faça upgrade da sua assinatura para incluir acesso à API.

Chat

Inicializar nova conversa / novo histórico de usuário

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "text": "Hello!"
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

O comando acima retorna um JSON estruturado assim:

{
  "ord_number": 2,
  "conv_id": "abcd1234",
  "reply": "Hey there! 🙂"
}

conv_id é um parâmetro opcional. Uma requisição que não contém conv_id inicia uma nova conversa e retorna um conv_id recém-gerado.

Associe o conv_id ao seu usuário específico para manter o contexto da conversa ao longo do tempo e em múltiplas interações.

Este endpoint realiza uma única troca de mensagens na conversa.

HTTP Request

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

Query Parameters

Parameter	Type	Description
api_key	string	Crie uma conta e assine para obter sua chave de API
scenario_id	Text	ID associado à sua implementação da API Quickchat.
text	string	Mensagem de entrada do usuário

Enviar mensagem ao Assistente de IA

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

O comando acima retorna um JSON estruturado assim:

{
  "ord_number": 236,
  "reply": "Hey, great to hear from you again! 😉"
}

HTTP Request

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

Query Parameters

Parameter	Type	Description
api_key	string	Crie uma conta e assine para obter sua chave de API
scenario_id	string	ID associado à sua implementação da API Quickchat.
conv_id	string (Optional)	Identifica uma conversa/usuário específico.
text	string	Mensagem de entrada do usuário.
message_context	string (Optional)	Contexto adicional por mensagem fornecido pelo cliente, que é passado à IA junto com a mensagem.
client_metadata	dict (Optional)	Por exemplo {userId: 12, website: mywebsite.com}. Máximo de 5 chaves por vez. Esses parâmetros serão atribuídos a cada nova mensagem e exibidos como colunas de dados na exportação de conversas na Inbox.

Mensagens com contexto e metadados personalizados

Conforme descrito na tabela de Query Parameters acima, o endpoint https://chat.quickchat.ai/chat permite enviar dois parâmetros opcionais: message_context e client_metadata.

Client metadata representa atributos personalizados que serão atribuídos a cada nova mensagem e exibidos como colunas de dados na exportação de conversas na Inbox. Você também pode adicionar atributos personalizados às mensagens via Widget com o mesmo efeito.

Message context permite fornecer, por exemplo, contexto específico por usuário em cada mensagem para dar um toque mais personalizado a cada conversa.

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
  "message_context": "The users name is John.",
  "client_metadata": {userId: 12, website: mywebsite.com}
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'userId': 12, 'website': 'mywebsite.com'}
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Adicionar Filtros por Tags da Base de Conhecimento via API

No app do Quickchat AI você pode adicionar tags a cada Artigo. Essas tags podem ser usadas para filtrar a Base de Conhecimento, fazendo com que a IA responda apenas com base em um subconjunto de Artigos da Base de Conhecimento. Note que, por enquanto, este recurso é suportado apenas via API.

Para filtrar por tópicos (tags) da Base de Conhecimento, você deve adicionar o kb_topic ao seu client_metadata nas chamadas à API. É importante garantir que a chave kb_topic esteja presente em todas as chamadas à API, incluindo a inicialização da conversa. Embora o valor de kb_topic possa mudar entre chamadas, o parâmetro em si deve estar constantemente presente durante toda a conversa para ser reconhecido pelo nosso sistema.

O exemplo abaixo mostra como adicionar kb_topic ao client_metadata. No exemplo, qualquer Artigo com a tag your-topic ou sem nenhuma tag será selecionado para o conjunto de candidatos de conhecimento para a resposta.

json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'kb_topic': 'your-topic'}
  }

Erros

Abaixo reunimos os códigos de erro que podem ser retornados pela API, junto com suas descrições e possíveis soluções.

Code	Description	Action
400	Os seguintes parâmetros devem ser fornecidos: api_key, scenario_id, text	Certifique-se de que todos os parâmetros obrigatórios foram fornecidos.
400	conv_id abcd1234 não existe	Verifique se o conv_id informado está correto.
400	O limite para message context é de 1000 caracteres.	Reduza o message context para 1000 caracteres incluindo espaços.
401	Não autorizado	Verifique se seu api_key e scenario_id estão corretos (veja Integrations - API no App).
500	Erro Interno do Servidor	Há um problema do nosso lado. Por favor, entre em contato com o suporte.
503	Serviço Indisponível	Nossos servidores estão sobrecarregados ou temporariamente indisponíveis por manutenção. Se o problema persistir, entre em contato com o suporte.