API

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

Autenticação

Inclua API Key e scenario_id em toda requisição.

Para obter sua chave, faça upgrade do seu plano para incluir acesso à API.

Chat

Inicializar nova conversa / 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')))

A resposta segue o formato:

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

conv_id é opcional. Sem conv_id, a chamada inicia nova conversa e retorna um id.

Associe conv_id ao seu usuário para manter contexto com o tempo.

Este endpoint realiza uma única troca de mensagens.

HTTP Request

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

Parâmetros

Parâmetro	Tipo	Descrição
api_key	string	Crie uma conta e assine para obter sua chave de API
scenario_id	Text	ID da sua implementação Quickchat API
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')))

A resposta segue o formato:

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

HTTP Request

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

Parâmetros

Parâmetro	Tipo	Descrição
api_key	string	Crie uma conta e assine para obter sua chave de API
scenario_id	string	ID da sua implementação Quickchat API.
conv_id	string (Opcional)	Identifica uma conversa/usuário.
text	string	Mensagem de entrada do usuário.
message_context	string (Opcional)	Contexto adicional por mensagem, enviado à IA junto com a mensagem.
client_metadata	dict (Opcional)	Ex.: {userId: 12, website: mywebsite.com}. Máx. 5 chaves. Atribuído a cada nova mensagem e exibido como colunas na exportação CSV de conversas na Inbox.

Mensagens com contexto e metadados customizados

Conforme a tabela acima, o endpoint https://chat.quickchat.ai/chat aceita message_context e client_metadata.

client_metadata são atributos definidos pelo cliente, atribuídos a cada mensagem e exibidos no CSV.

message_context permite inserir contexto por usuário para personalizar a 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 é possível adicionar tags a cada Artigo. Elas servem para filtrar a Base de Conhecimento, fazendo a IA responder apenas com um subconjunto de artigos.

Para filtrar por tópicos (tags), adicione kb_topic em client_metadata. Garanta que a chave esteja presente em todas as chamadas, inclusive na inicialização; o valor pode mudar, a chave não.

Exemplo:

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

Códigos de erro possíveis, com descrição e ação:

Código	Descrição	Ação
400	Parâmetros obrigatórios: api_key, scenario_id, text	Verifique se enviou todos os obrigatórios.
400	conv_id abcd1234 não existe	Verifique o conv_id informado.
400	Limite de message_context é 1000 caracteres	Reduza message_context para 1000 caracteres (com espaços).
401	Não autorizado	Verifique api_key e scenario_id (ver Integrations - API).
500	Erro interno do servidor	Problema do nosso lado. Entre em contato.
503	Serviço indisponível	Sobrecarga/manutenção. Persistindo, entre em contato.