Centro de Ajuda
Chat API

Bot Talk API

Última atualização:

Bot Talk API

A Bot Talk API é uma REST API para comunicar com um chatbot específico a partir da sua própria aplicação - aplicações personalizadas, ferramentas internas ou automatizações criadas por si. 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 transmitidas via SSE.

Como começar

  1. Selecione o seu chatbot e aceda 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 com o botão Create API Key destacado

O contador junto ao botão mostra quantas chaves estão ativas ("1 of 5 API keys active"). 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), selecione as permissões pretendidas 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 confirmação. O texto simples é apresentado apenas uma vez.

Uma chave tem o formato ck_abcdefghijklmnopqrstuvwxyz012345. Cada chave pertence a esse bot específico, pelo que todos os pedidos efetuados com ela comunicam com esse bot - o bot é identificado pela chave e nunca aparece no URL.

Base URL

https://api.chatlab.com/aichat

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

Permissões da chave

Cada chave tem uma ou ambas as permissões, configuradas 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 apresenta as permissões concedidas a cada chave sob a forma de etiquetas Chat e Conversations.

Autenticação

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

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Os 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

  • No máximo 5 chaves Bot Talk ativas por bot
  • No máximo 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 inferior para reduzir o limite máximo, ajustando a taxa de reposição proporcionalmente.
  • Comprimento máximo da mensagem: 4000 carateres
  • Os fluxos SSE simultâneos por chave estão sujeitos aos limites da sua conta

Endpoints

POST /v1/chat

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

Request body

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - cadeia obrigatória, máx. 4000 carateres.
  • conversationId - UUID opcional. Omitir para uma nova conversa; reutilizar o valor devolvido anteriormente pelo servidor para anexar a uma conversa existente.
  • metadata - objeto opcional: {source, userName, userEmail, userPhone}. O campo userEmail também é utilizado para derivar o ID interno do cliente.

Response body (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4o-mini",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role é sempre "assistant"; message.content é a resposta completa.
  • model é o identificador do modelo em que o bot foi executado para esta chamada.
  • usage.creditsUsed contabiliza a mensagem do utilizador + a resposta do bot (normalmente 2), acrescido de um crédito adicional por cada chamada de ferramenta executada.
  • actions lista as execuções de ferramentas que correram durante este turno. Atualmente, apenas são emitidas entradas de function_call (com type, name, status: "completed").

POST /v1/chat/stream

Variante de transmissão contínua (streaming) do /v1/chat. Devolve Content-Type: text/event-stream com Server-Sent Events.

Request body

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

Response body (eventos SSE)

  • 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 é terminado em seguida.

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

Exemplo em 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.).

Query parameters

  • limit - 1-100, predefinição 20. Valores fora do intervalo são ajustados aos limites.
  • cursor - valor opaco devolvido em nextCursor na página anterior. Omitir na primeira página.

Response body (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; passe-o como cursor para obter a página seguinte.

GET /v1/conversations/{conversation_id}

Histórico completo da conversa.

Response body (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 são devolvidos os papéis user e assistant; 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 de gestão (Management key).

Cabeçalhos de limite de pedidos (rate limit)

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

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - o limite por chave aplicado efetivamente a esta chamada (60 por predefinição, ou o valor de rateLimitPerMinute configurado, caso seja inferior).
  • X-RateLimit-Remaining - tokens restantes no balde logo após esta chamada.
  • X-RateLimit-Reset - segundos no formato Unix epoch em que o próximo token fica disponível (não representa uma reposição total do balde; o balde é restabelecido 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 seja libertado.

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

Formato dos erros

Todos os erros partilham uma estrutura comum:

{
  "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 - dados introduzidos com formato inválido (códigos: invalid_parameter, 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 incluído na 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) - verbo HTTP incorreto no URL
  • 429 rate_limit_error - demasiados pedidos (rate_limit_exceeded) ou demasiados fluxos simultâneos (concurrent_streams_exceeded)
  • 500 api_error - erro interno

Conteúdo relacionado

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

Pesquisar em todos os artigosPergunte ao agente