Guia da API de Mensagens

A API de Interação com Chatbot permite que você interaja com seus chatbots usando uma solicitação POST. Esta API está disponível para usuários inscritos em um plano pago e fornece uma maneira de se comunicar com seu chatbot de forma programática.

Endpoint

POST https://kodagpt.com.br/api/v1/chat

Cabeçalhos de Solicitação

A solicitação à API deve incluir os seguintes cabeçalhos:

Content-Type: application/json - O tipo de conteúdo do payload da solicitação.
API_KEY: "<API-Key>" - A chave secreta para autenticar a solicitação à API.

Corpo da Solicitação

Além dos parâmetros básicos, a API oferece uma variedade de opções avançadas que permitem ajustar a resposta do seu chatbot conforme necessário. Abaixo estão detalhes adicionais sobre os parâmetros que podem ser incluídos no corpo da sua requisição POST para aprimorar a interação com o chatbot.

chatbot_id (string, obrigatório): Refere-se ao ID do chatbot com o qual você deseja interagir (encontrado na página de "Integrações" do chatbot).
question (string, obrigatório): É a pergunta feita pelo usuário para o chatbot.
client_info (string, obrigatório): Uma identificação do usuário do chatbot como nome, email, telefone entre outras informações que desejar.
messages (array, opcional): Um array contendo TODAS as mensagens entre o usuário e o assistente. Cada objeto de mensagem deve ter as propriedades de "content" e "role". O campo "content" representa o conteúdo textual da mensagem, e o campo "role" pode ser "user" ou "assistant" para indicar o remetente da mensagem.
custom_prompt (string, opcional): Permite que você substitua o prompt padrão do chatbot, alterando o comportamento padrão da resposta da IA.
model (string, opcional, padrão 'gpt-3.5-turbo'): 'gpt-3.5-turbo' | 'gpt-3.5-turbo-16k' | 'gpt-4'. Se isso for adicionado ao corpo, tem precedência sobre o modelo padrão. A opção para 'gpt-4' só funciona nos planos Pro e Enterprise e cada chamada de API contabilizará 20 créditos de consumo nas mensagens do plano.
stream (boolean, opcional, o padrão é false): Um valor booleano indicando se deve transmitir o progresso parcial ou esperar pela resposta completa da IA. Se definido como true, as palavras serão enviadas como server-sent events (SSE) pelo servidor a medida que ficarem disponíveis, com a transmissão encerrada automaticamente pelo servidor ao fim da resposta com uma mensagem final "CHATBOT LOG ID: log_id", contendo o "id" da mensagem. Se definido como false, a resposta completa será retornada uma vez que esteja pronta no formato JSON com os campos "status", "text" e "log_id".
stream_format_data (boolean, opcional, o padrão é false): Com o valor configurado em true os pacotes da mensagem vão chegar com "data: " na frente da palavra ou texto. O final do stream vai ser "[DONE]".
persona (número, opcional, padrão é 0): Permite que você ajuste a personalidade do chatbot, variando de 0 a 5. As personas são: (0 - Padrão; 1 - Descolado; 2 - Formal; 3 - Colaborador interno; 4 - Documentações; 5 - Vídeo/YouTube).
system_prompt (string, opcional, padrão é a persona): Fornece uma instrução de sistema ao chatbot. Pode ser usado para criar personas únicas, alterando o estilo e formato da resposta final.
knowledge_base (array, opcional, padrão null): Permite que você introduza uma base de conhecimento específica na forma de um array de objetos para o chatbot usar na resposta final.
conversation_id (string, opcional): Um identificador que ajuda a manter o contexto entre várias requisições. É criado um histórico temporário da conversa (messages) sem precisar fornecer o parâmetro messages. Esse histórico é resetado a cada 24h.
temperature (número, opcional, padrão é 0.50): Os valores de temperatura variam entre 0 e 1. Valores mais altos como 0.8 tornarão a saída mais aleatória, enquanto valores mais baixos como 0,2 a tornarão mais focada e determinístico.
frequency_penalty (número, opcional): Penalidade para o uso de palavras e frases frequentes, numa escala de 0 a 2.
presence_penalty (número, opcional): Penalidade por usar palavras e frases novas ou raras, numa escala de 0 a 2.
max_tokens (número, opcional): O número máximo de tokens na resposta do modelo. O padrão é o máximo permitido por cada modelo da Openai.
top_p (número, opcional): Parâmetro de amostragem nuclear. Define a probabilidade cumulativa no qual as amostras de palavras são escolhidas. A escala é de 0 a 1
whatsapp (boolean, opcional): Especifique se a interação é via WhatsApp para aplicar formatações específicas.

Exemplo básico:

{
  "chatbot_id": "12a97d87-b8qa-4558-9d03-a0f4y4iu60bd7",
  "question": "O KodaGPT tem API?",
  "client_info": "Cliente X - [email protected]",
  "messages": [
    { content: 'Olá tudo bem? Como posso te ajudar hoje', role: 'assistant' },
    { content: 'O que é o KodaGPT?', role: 'user' },
    { content: 'É um chatbot customizável que usa o ChatGPT', role: 'assistant' },
  ],
  "stream": false,
  "temperature": 0.75,
  "model": "gpt-3.5-turbo"
}

Exemplo de requisição

const response = await fetch('https://kodagpt.com.br/api/v1/chat', {
  method: 'POST',
  headers: {
    "Content-Type": "application/json",
    "API_KEY": "<API-Key>"
  },
  body: JSON.stringify({
    "chatbot_id": "12a97d87-b8qa-4558-9d03-a0f4y4iu60bd7",
    "question": "O KodaGPT tem API?",
    "client_info": "Cliente X - [email protected]",
    "messages": [
      { content: 'Olá tudo bem? Como posso te ajudar hoje', role: 'assistant' },
      { content: 'O que é o KodaGPT?', role: 'user' },
      { content: 'É um chatbot customizável que usa o ChatGPT', role: 'assistant' },
    ],
    "stream": false,
    "temperature": 0.75,
    "model": "gpt-3.5-turbo"
  })
});

if (!response.ok) {
  const errorData = await response.json();
  throw Error(errorData.message);
}
const data = await response.json(); 
console.log(data); // { "status": "success", "text": "...", "log_id": 12345}

Resposta

A resposta da API vai ter a seguinte estrutura JSON

{
  "status": "success",
  "text": "Sim! O KodaGPT possui uma API para desenvolvedores e pode ser usada por todos que tem o plano Pro e Enterprise.",
  "log_id": 12345
}

Exemplo de Solicitação com Funcionalidade de Streaming

Se o parâmetro de stream estiver definido como true, as palavras serão enviadas de volta como eventos de servidor apenas com dados à medida que estiverem disponíveis. Para ler o fluxo, você pode usar os trechos de código a seguir:

const response = await fetch(`http://localhost:4000/api/chat`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "API_KEY": "<API-Key>"
  },
  body: JSON.stringify({
    "chatbot_id": "12a97d87-b8qa-4558-9d03-a0f4y4iu60bd7",
    "question": "O KodaGPT tem API?",
    "client_info": "Cliente X - [email protected]",
    "stream": true
  })
});

if (!response.ok) {
  const errorData = await response.json();
  throw Error(errorData.message);
}

const data = response.body;

if (!data) {
  // algum erro aconteceu
}

const reader = data.getReader();
const decoder = new TextDecoder();
let done = false;

while (!done) {
  const { value, done: doneReading } = await reader.read();
  done = doneReading;
  const chunkValue = decoder.decode(value);
  console.log(chunkValue); // Isso registrará partes da resposta do chatbot até que a resposta esteja concluída.
}

Tratamento de Erros

A API retorna respostas em formato JSON, incluindo quando ocorrem erros. Aqui estão alguns códigos comuns de erro HTTP que você pode encontrar:

400 Bad Request: A solicitação estava malformada. Verifique o corpo da resposta para obter mais detalhes sobre o erro.
401 Unauthorized: Falha na autenticação. Verifique se a sua chave de API está correta.
403 Forbidden: A chave da API é válida, mas não tem permissão para acessar o recurso solicitado. Verifique suas permissões.
429 Too Many Requests: Você atingiu o limite de taxa de solicitações para a sua chave de API.
500 Internal Server Error: O servidor encontrou uma situação que não sabe como lidar.

Considerações de Segurança

Nunca exponha sua chave de API em locais acessíveis ao público, como repositórios públicos no GitHub.
Limite as permissões da sua chave de API o quanto possível para reduzir o impacto potencial caso ela seja comprometida.
Sempre utilize HTTPS para garantir que as suas interações com a API sejam criptografadas e seguras.

Suporte

Se você encontrar qualquer problema ou tiver sugestões de melhoria, não hesite em entrar em contato conosco através do nosso email [email protected]