Hjelpesenter
Chat API

Bot Talk API

Sist oppdatert:

Bot Talk API

Bot Talk API er et REST-API for å kommunisere med én bestemt 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 enkel respons eller strømmet over SSE.

Kom i gang

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

Bot Talk API-fane

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

API-fanen markert; Create API Key finnes i sideinnholdet

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 curl-eksempelet under Quick Start (Hurtigstart) gir deg et bruksklart eksempel.

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

Dialogboksen Create API Key

  1. Kopier hele nøkkelen fra bekreftelsesdialogen. Nøkkelen i ren tekst vises bare én gang.

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

  1. Kjør curl-eksempelet nedenfor fra serveren din med nøkkelen din og en kort testmelding. Lagre den returnerte verdien for conversationId, og gjenbruk den deretter for oppfølgingsmeldinger. Bekreft svaret og samtalen i botens Chatlogs-fane (Samtalelogger).

Oppbevar ck_-nøkler på serveren din, ikke i JavaScript på nettstedet eller i pakker for mobilapper. En Conversations-tillatelse gir tilgang til denne botens lagrede samtaler på tvers av alle besøkende, så applikasjonen din må autorisere hver enkelt sluttbruker før disse dataene returneres. Bruk Revoke (Tilbakekall) eller Delete (Slett) i API-fanen for å deaktivere en nøkkel; ingen av handlingene viser nøkkelen i ren tekst igjen.

Før du starter, bør du opprette og trene chatboten din og kontrollere at kontoen din inkluderer API-tilgang og har meldingskreditter.

Base-URL

https://api.chatlab.com/aichat

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

Nøkkeltillatelser

Hver nøkkel har én eller begge av disse tillatelsene, angitt med bryterne i dialogboksen Create API Key:

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

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

Autentisering

Send nøkkelen i Authorization-headeren ved 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-adresse 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 - angi en lavere rateLimitPerMinute, så reduseres grensen, og påfyllingshastigheten justeres tilsvarende.
  • 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 (Request body)

{
  "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 samtale.
  • metadata - valgfritt objekt som godtar {source, userName, userEmail, userPhone}. For øyeblikket brukes bare userEmail her for å utlede klientidentifikatoren; kanalen registreres som API. Ikke stol på at de andre metadatafeltene lagres i en lead-oppføring.

Responskropp (Response body) (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 er alltid "assistant"; message.content er hele svaret.
  • model er modell-ID-en boten kjørte på for dette kallet.
  • usage.creditsUsed rapporterer for øyeblikket 2 pluss én per rapportert verktøykall for en fullført samtalerunde. Denne responstelleren inkluderer ikke kredittmultiplikatorer for modell/kontekst og må ikke brukes som fakturagrunnlag. Bruk Management API-forbruk for kontoforbruk og se meldingskreditter.
  • actions viser verktøykjøringer som ble utført i løpet av denne runden. Foreløpig sendes bare function_call-oppføringer (med type, name, status: "completed").

POST /v1/chat/stream

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

Forespørselskropp (Request body)

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 (Response body) (SSE-hendelser)

  • message.reset - forkast teksten som er akkumulert for det nåværende svaret, og begynn å samle inn deltas på nytt. Dette kan skje når genereringen starter på nytt; å slå sammen begge versjonene ville føre til et duplisert eller foreldet svar.
  • 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) listen over fullførte actions.
  • 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

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

Spørreparametere (Query parameters)

  • limit - 1-100, standard er 20. Verdier utenfor dette intervallet justeres automatisk til grensene.
  • cursor - ugjennomsiktig verdi returnert i nextCursor på forrige side. Utelat for den første siden.

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

GET /v1/conversations/{conversation_id}

Lagrede samtalemeldinger tilgjengeliggjort via dette endepunktet.

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

Kun rollene user og assistant 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 å undersøke bot-konfigurasjonen, bruk Management API-endepunktet GET /v1/management/bots/{bot_id} med en Management-nøkkel.

Hastighetsgrense-headere (Rate limit headers)

Svar som når hastighetsgrense-fasen (det vil si at 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 gjelder 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-tid i sekunder da neste token blir tilgjengelig (ikke en full tilbakestilling av bøtten; bøtten fylles kontinuerlig). Når bøtten er full, er dette gjeldende tidspunkt.

Ved 429 rate_limit_exceeded-svar er Retry-After også satt, angitt i hele sekunder frem 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 - grensekontrollen konsulteres bare etter at autentisering og IP-kontroller er fullført.

Feilformat

Alle feil deler samme struktur:

{
  "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 (invalid_parameter)
  • 415 invalid_request_error - innholdstype støttes ikke (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 - meldingskreditter er brukt opp
  • 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 for 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 operasjoner på kontonivå (opprette boter, oppdatere boter, hente forbruk), se Management API.

Søk i alle artiklerSpør agenten