Hjelpesenter
Chat API

Bot Talk API

Sist oppdatert:

Bot Talk API

Bot Talk API er et REST API for å kommunisere med en spesifikk chatbot fra din egen applikasjon - tilpassede apper, interne verktøy eller automatiseringer du bygger selv. Du oppretter en API-nøkkel i botens API-fane, og kaller deretter chat-endepunktet med nøkkelen som et Bearer-token for å motta botens svar, enten som en enkeltrespons eller strømmet over SSE.

Komme i gang

  1. Velg chatboten din og gå til API-fanen øverst på botsiden (Select Bot > API (Velg bot > API)).

Bot Talk API-fane

  1. Klikk på Create API Key (Opprett API-nøkkel).

API-fane med knappen Create API Key uthevet

Telleren ved siden av knappen viser hvor mange nøkler som er aktive («1 of 5 API keys active»). Lenken View API Documentation (Vis API-dokumentasjon) åpner denne referansen, og Quick Start (Hurtigstart)-curl-kodesnutten gir deg et eksempel som er klart til å kjøres.

  1. I dialogvinduet Create API Key gir du nøkkelen et navn, angir eventuelt en IP-hviteliste og en hastighetsgrense, velger hvilke tillatelser den skal ha, og klikker deretter på Create (Opprett).

Dialogvinduet Create API Key

  1. Kopier hele nøkkelen fra bekreftelsesvinduet. Ren tekst vises bare én gang.

En nøkkel ser slik ut: ck_abcdefghijklmnopqrstuvwxyz012345. Hver nøkkel tilhører den ene boten, så enhver forespørsel som gjøres med nøkkelen, kommuniserer med denne boten - boten identifiseres av nøkkelen og vises aldri i URL-en.

Basis-URL

https://api.chatlab.com/aichat

Alle endepunkter i denne artikkelen er relative til denne basis-URL-en.

Nøkkeltillatelser

Hver nøkkel har én eller begge av disse tillatelsene, som angis med bryterne i Create API Key-dialogvinduet:

  • Chat (send messages and receive responses) - tillater endepunktene /v1/chat og /v1/chat/stream.
  • Conversation history (list and read past conversations) - tillater endepunktene /v1/conversations.

API-fanen viser hver nøkkels tildelte tillatelser som Chat- og Conversations-merker.

Autentisering

Send nøkkelen i Authorization-headeren på hver forespørsel:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Forespørsler uten en Authorization: Bearer ...-header returnerer 401 missing_api_key. Ukjente nøkler returnerer 401 invalid_api_key; tilbakekalte nøkler returnerer 401 revoked_api_key. Fem ugyldige forsøk i løpet av ett minutt fra samme IP utløser en 60-minutters blokkering.

Grenser

  • Maks 5 aktive Bot Talk-nøkler per bot
  • Maks 60 forespørsler per minutt per nøkkel (token bucket, kapasitet 60, jevn påfylling med 1 token per sekund). Kan konfigureres nedover ved opprettelse - sett en lavere rateLimitPerMinute slik at grensen reduseres, og påfyllingshastigheten skalerer i takt med den.
  • Maks meldingslengde 4000 tegn
  • Samtidige SSE-strømmer per nøkkel er underlagt kontogrensene dine

Endepunkter

POST /v1/chat

Send en melding til boten og motta hele svaret i én enkelt JSON-respons.

Forespørselskropp

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - obligatorisk streng, maks 4000 tegn.
  • conversationId - valgfri UUID. Utelat for en ny samtale; gjenbruk verdien serveren returnerte tidligere for å legge til i en eksisterende.
  • metadata - valgfritt objekt: {source, userName, userEmail, userPhone}. userEmail brukes også til å utlede den interne klient-ID-en.

Responskropp (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 er alltid "assistant"; message.content er hele svaret.
  • model er modell-ID-en boten kjørte på for dette kallet.
  • usage.creditsUsed gjør rede for brukermeldingen + botsvaret (vanligvis 2), pluss én ekstra credit per utførte verktøykall.
  • actions viser verktøykjøringer som ble utført under denne runden. For øyeblikket sendes bare function_call-oppføringer (med type, name, status: "completed").

POST /v1/chat/stream

Strømmende variant av /v1/chat. Returnerer Content-Type: text/event-stream med Server-Sent Events.

Forespørselskropp

Samme struktur som POST /v1/chat. stream-flagget i kroppen er ikke påkrevd - det er bruken av denne stien som utløser SSE.

Responskropp (SSE-hendelser)

  • message.delta - innholdsfragment { "content": "..." }. Flere av disse strømmes etter hvert som tokens ankommer.
  • action - verktøykjøring { "type", "name", "status": "executing" }. Sendes når boten utløser et funksjonskall.
  • message.done - avsluttende hendelse med conversationId, model, usage og (hvis aktuelt) den fullførte actions-listen.
  • error - sendes hvis genereringen mislykkes; strømmen avsluttes deretter.

Keep-alive SSE-kommentarer (:keepalive) sendes hvert 15. sekund under lange genereringer. Tidsavbrudd på serversiden: 30 sekunder for første token, 120 sekunder totalt per strøm.

Curl-eksempel

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

List opp samtaler for boten som er knyttet til nøkkelen din, på tvers av alle kilder (widget, WhatsApp, API osv.).

Spørringsparametere

  • limit - 1-100, standardverdi 20. Verdier utenfor området justeres til grensene.
  • cursor - ugjennomsiktig verdi returnert i nextCursor på forrige side. Utelat for første side.

Responskropp (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 avkortes til 100 tegn med et ...-suffiks.
  • nextCursor er null på den siste siden; send den som cursor for å hente neste.

GET /v1/conversations/{conversation_id}

Fullstendig samtalehistorikk.

Responskropp (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"}
  ]
}

Bare user- og assistant-roller returneres; interne system- og verktøymeldinger filtreres ut. Returnerer 404 not_found_error hvis samtalen ikke tilhører boten som er knyttet til nøkkelen din.

For å inspisere botkonfigurasjonen bruker du Management API-endepunktet GET /v1/management/bots/{bot_id} med en Management-nøkkel.

Hastighetsgrense-headere

Responser som når trinnet for hastighetsbegrensning (dvs. autentisering og IP-hviteliste er godkjent), inkluderer:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - grensen per nøkkel som faktisk ble brukt for dette kallet (60 som standard, eller din konfigurerte rateLimitPerMinute hvis den er lavere).
  • X-RateLimit-Remaining - gjenværende tokens i bøtten rett etter dette kallet.
  • X-RateLimit-Reset - Unix epoch-sekunder der neste token blir tilgjengelig (ikke en fullstendig tilbakestilling av bøtten; bøtten fylles opp kontinuerlig). Når bøtten er full, er dette gjeldende tidspunkt.

Ved 429 rate_limit_exceeded-responser settes også Retry-After, uttrykt i hele sekunder til minst ett token blir ledig.

Feil før autentisering (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) og 403 ip_not_whitelisted inneholder ikke X-RateLimit-*-headere - hastighetsbegrenseren konsulteres først etter at autentisering og IP-kontroller er fullført.

Feilformat

Alle feil deler samme innpakning:

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

Vanlige HTTP-koder:

  • 400 invalid_request_error - feilformatert inndata (koder: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - manglende nøkkel (missing_api_key), ukjent nøkkel (invalid_api_key) eller tilbakekalt nøkkel (revoked_api_key)
  • 402 quota_exceeded_error - meldings-credits er oppbrukt
  • 403 permission_error - IP blokkert (ip_blocked), IP ikke i nøkkelens hviteliste (ip_not_whitelisted), eller nøkkeltypen tillater ikke dette endepunktet (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - samtalen tilhører ikke denne boten
  • 405 invalid_request_error (method_not_allowed) - feil HTTP-metode på URL-en
  • 429 rate_limit_error - for mange forespørsler (rate_limit_exceeded) eller for mange samtidige strømmer (concurrent_streams_exceeded)
  • 500 api_error - intern feil

Relatert

For handlinger på kontonivå (opprette boter, oppdatere boter, hente forbruk), se Management API.

Søk i alle artiklerSpør agenten