Centro de Ajuda
Chat API

Bot Talk API

Última atualização:

Bot Talk API

A Bot Talk API é uma API REST para comunicar com um chatbot específico a partir da sua própria aplicação - aplicações personalizadas, ferramentas internas ou automações que constrói autonomamente. Cria uma chave de API no separador API do bot e, em seguida, chama o endpoint de chat com a chave como token Bearer para obter as respostas do bot, quer como uma resposta única, quer em streaming através de SSE.

Introdução

  1. Selecione o seu chatbot e navegue até ao separador API na parte superior da página do bot (Select Bot > API [Selecionar bot > API]).

Separador Bot Talk API

  1. Clique em Create API Key (Criar chave de API).

Separador API destacado; Create API Key está no conteúdo da página

O contador junto ao botão mostra quantas chaves estão ativas ("1 de 5 chaves de API ativas"). A ligação View API Documentation (Ver documentação da API) abre esta referência e o fragmento de curl Quick Start (Início rápido) fornece-lhe um exemplo pronto a executar.

  1. Na caixa de diálogo Create API Key, atribua um nome à chave, defina opcionalmente uma lista de permissões de IP e um limite de pedidos (rate limit), escolha as permissões que terá e clique em Create (Criar).

Caixa de diálogo Create API Key

  1. Copie a chave completa a partir da caixa de diálogo de sucesso. O texto simples é apresentado apenas uma vez.

Uma chave tem o formato ck_abcdefghijklmnopqrstuvwxyz012345. Cada chave pertence a esse bot específico, pelo que cada pedido efetuado com a chave comunica com esse bot - o bot é identificado pela chave e nunca aparece no URL.

  1. A partir do seu servidor, execute o exemplo de curl abaixo com a sua chave e uma mensagem de teste curta. Guarde o conversationId devolvido e reutilize-o para uma mensagem de seguimento. Confirme a resposta e a conversa no separador Chatlogs (Registos de chat) do bot.

Mantenha as chaves ck_ no seu servidor e não no JavaScript do site ou em pacotes de aplicações móveis. A permissão Conversations concede acesso às conversas guardadas deste bot entre diferentes visitantes, pelo que a sua aplicação tem de autorizar cada utilizador final antes de devolver esses dados. Utilize Revoke (Revogar) ou Delete (Eliminar) no separador API para desativar uma chave; nenhuma das ações volta a revelar o seu texto simples.

Antes de começar, crie e treine o seu chatbot e confirme se a sua conta inclui acesso à API e dispõe de créditos de mensagens.

Base URL

https://api.chatlab.com/aichat

Todos os endpoints neste artigo são relativos a este URL base.

Permissões da chave

Cada chave tem uma ou ambas as seguintes permissões, definidas através dos seletores na caixa de diálogo Create API Key:

  • Chat (send messages and receive responses) - permite a utilização dos endpoints /v1/chat e /v1/chat/stream.
  • Conversation history (list and read past conversations) - permite a utilização dos endpoints /v1/conversations.

O separador API mostra as permissões concedidas a cada chave sob a forma de emblemas Chat e Conversations.

Autenticação

Envie a chave no cabeçalho Authorization em cada pedido:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Pedidos sem o cabeçalho Authorization: Bearer ... devolvem 401 missing_api_key. Chaves desconhecidas devolvem 401 invalid_api_key; chaves revogadas devolvem 401 revoked_api_key. Cinco tentativas inválidas num minuto a partir do mesmo IP acionam um bloqueio de 60 minutos.

Limites

  • Máximo de 5 chaves Bot Talk ativas por bot
  • Máximo de 60 pedidos por minuto por chave (token bucket, capacidade de 60, reposição gradual a 1 token por segundo). Configurável para valores inferiores no momento da criação - defina um rateLimitPerMinute mais baixo e o limite máximo diminui, ajustando a taxa de reposição proporcionalmente.
  • Tamanho máximo da mensagem de 4000 carateres
  • Os fluxos SSE simultâneos por chave estão sujeitos aos limites da sua conta

Endpoints

POST /v1/chat

Envia uma mensagem para o bot e recebe a resposta completa numa única resposta JSON.

Corpo do pedido

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - string obrigatória, máx. 4000 carateres.
  • conversationId - UUID opcional. Omita para uma nova conversa; reutilize o valor que o servidor devolveu anteriormente para continuar uma conversa existente.
  • metadata - objeto opcional que aceita {source, userName, userEmail, userPhone}. Atualmente, apenas userEmail é utilizado aqui para derivar o identificador do cliente; o canal é registado como API. Não dependa dos outros campos de metadados para gravação num registo de lead.

Corpo da resposta (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "5.6-LUNA",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role é sempre "assistant"; message.content é a resposta completa.
  • model é o id do modelo em que o bot foi executado para esta chamada.
  • usage.creditsUsed reporta atualmente 2 mais um por cada chamada de ferramenta (tool call) reportada para um turno concluído. Este contador de resposta não inclui multiplicadores de crédito de modelo/contexto e não deve ser utilizado como o seu registo de faturação. Utilize a utilização da Management API para o consumo da conta e consulte os créditos de mensagens.
  • actions lista as execuções de ferramentas que foram efetuadas durante este turno. Atualmente, apenas são emitidas entradas function_call (com type, name, status: "completed").

POST /v1/chat/stream

Variante de streaming de /v1/chat. Devolve Content-Type: text/event-stream com Server-Sent Events.

Corpo do pedido

A mesma estrutura de POST /v1/chat. O parâmetro stream no corpo não é obrigatório - a utilização deste caminho é o que aciona o SSE.

Corpo da resposta (eventos SSE)

  • message.reset - descarta o texto acumulado para a resposta atual e recomeça a recolher deltas. Isto pode ocorrer quando a geração é reiniciada; acrescentar ambas as versões mostraria uma resposta duplicada ou substituída.
  • message.delta - fragmento de conteúdo { "content": "..." }. Vários destes eventos são transmitidos à medida que os tokens chegam.
  • action - execução de ferramenta { "type", "name", "status": "executing" }. Emitido quando o bot aciona uma chamada de função.
  • message.done - evento final com conversationId, model, usage e (se existirem) a lista de actions concluídas.
  • error - enviado se a geração falhar; o fluxo termina em seguida.

Comentários SSE de manutenção de ligação (:keepalive) são enviados a cada 15 segundos durante gerações longas. Tempos limite do lado do servidor: 30 segundos para o primeiro token, 120 segundos no total por fluxo.

Exemplo de curl

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Lista as conversas do bot associado à sua chave, em todas as origens (widget, WhatsApp, API, etc.).

Parâmetros de consulta

  • limit - 1-100, padrão 20. Os valores fora do intervalo são ajustados aos limites.
  • cursor - valor opaco devolvido em nextCursor na página anterior. Omita para a primeira página.

Corpo da resposta (200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • lastMessagePreview é truncado para 100 carateres com um sufixo ....
  • nextCursor é null na última página; envie-o como cursor para obter a página seguinte.

GET /v1/conversations/{conversation_id}

Mensagens de conversas guardadas disponibilizadas por este endpoint.

Corpo da resposta (200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Apenas as funções user e assistant são devolvidas; as mensagens internas de system e de ferramentas são filtradas. Devolve 404 not_found_error se a conversa não pertencer ao bot associado à sua chave.

Para inspecionar a configuração do bot, utilize o endpoint da Management API GET /v1/management/bots/{bot_id} com uma chave Management.

Cabeçalhos de limite de pedidos

As respostas que atingem a fase de verificação de limites (ou seja, passaram a autenticação e a lista de permissões de IP) incluem:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - o limite por chave efetivamente aplicado a esta chamada (60 por padrão, ou o valor configurado em rateLimitPerMinute se for inferior).
  • X-RateLimit-Remaining - tokens restantes no balde imediatamente após esta chamada.
  • X-RateLimit-Reset - segundos da época Unix em que o próximo token fica disponível (não representa uma reposição completa do balde; o balde recarrega continuamente). Quando o balde está cheio, este valor corresponde à hora atual.

Em respostas 429 rate_limit_exceeded, o cabeçalho Retry-After também é incluído, expresso em segundos inteiros até que pelo menos um token fique disponível.

Erros prévios à autenticação (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) e 403 ip_not_whitelisted não incluem os cabeçalhos X-RateLimit-* - o limitador só é consultado após a conclusão com sucesso da autenticação e das verificações de IP.

Formato de erro

Todos os erros partilham um envelope único:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Códigos HTTP comuns:

  • 400 invalid_request_error - entrada malformada (invalid_parameter)
  • 415 invalid_request_error - tipo de conteúdo não suportado (unsupported_media_type)
  • 401 authentication_error - chave em falta (missing_api_key), chave desconhecida (invalid_api_key) ou chave revogada (revoked_api_key)
  • 402 quota_exceeded_error - créditos de mensagens esgotados
  • 403 permission_error - IP bloqueado (ip_blocked), IP não constante da lista de permissões da chave (ip_not_whitelisted) ou o tipo de chave não permite este endpoint (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - a conversa não pertence a este bot
  • 405 invalid_request_error (method_not_allowed) - método HTTP incorreto no URL
  • 429 rate_limit_error - pedidos em excesso (rate_limit_exceeded) ou demasiados fluxos simultâneos (concurrent_streams_exceeded)
  • 500 api_error - erro interno

Relacionado

Para operações ao nível da conta (criar bots, atualizar bots, consultar utilização), consulte a Management API.

Pesquisar em todos os artigosPergunte ao agente