Ohjekeskus
Chat API

Bot Talk API

Viimeksi päivitetty:

Bot Talk API

Bot Talk API on REST-rajapinta, jonka avulla voit keskustella tietyn chatbotin kanssa suoraan omasta sovelluksestasi käsin - olipa kyseessä räätälöity sovellus, sisäinen työkalu tai itse rakentamasi automaatio. Luot API-avaimen botin API-välilehdellä ja kutsut sen jälkeen chat-päätepistettä käyttäen avainta Bearer-tokenina saadaksesi botin vastaukset, joko yksittäisenä vastauksena tai SSE-yhteyden yli suoratoistettuna (stream).

Aloittaminen

  1. Valitse chatbotisi ja siirry sivun yläreunassa olevalle API-välilehdelle (Select Bot > API (Valitse botti > API)).

Bot Talk API -välilehti

  1. Napsauta Create API Key (Luo API-avain).

API-välilehti, jossa Create API Key -painike on korostettu

Painikkeen vieressä oleva laskuri näyttää, kuinka monta avainta on aktiivisena ("1 of 5 API keys active"). Linkki View API Documentation (Näytä API-dokumentaatio) avaa tämän ohjeen, ja Quick Start (Pika-aloitus) -curl-koodinpätkä tarjoaa heti suoritettavan esimerkin.

  1. Anna avaimelle nimi Create API Key -valintaikkunassa, määritä halutessasi IP-osoitteiden sallittujen lista (whitelist) ja pyyntöjen enimmäismäärä (rate limit), valitse sen käyttöoikeudet ja napsauta sitten Create (Luo).

Create API Key -valintaikkuna

  1. Kopioi koko avain onnistumisilmoituksesta. Selkokielinen avain näytetään vain kerran.

Avain näyttää tältä: ck_abcdefghijklmnopqrstuvwxyz012345. Jokainen avain kuuluu kyseiselle yhdelle botille, joten kaikki avaimella tehdyt pyynnöt ohjautuvat tälle botille - botti tunnistetaan avaimen perusteella, eikä se näy koskaan URL-osoitteessa.

Perus-URL

https://api.chatlab.com/aichat

Kaikki tämän artikkelin päätepisteet ovat suhteessa tähän perus-URL-osoitteeseen.

Avainten käyttöoikeudet

Jokaisella avaimella on toinen tai molemmat näistä käyttöoikeuksista, jotka määritetään Create API Key -ikkunan valitsimilla:

  • Chat (send messages and receive responses) - sallii päätepisteet /v1/chat ja /v1/chat/stream.
  • Conversation history (list and read past conversations) - sallii päätepisteet /v1/conversations.

API-välilehti näyttää kullekin avaimelle myönnetyt luvat Chat- ja Conversations-tunnisteina.

Todennus

Lähetä avain Authorization-otsakkeessa jokaisessa pyynnössä:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Pyynnöt ilman Authorization: Bearer ... -otsaketta palauttavat virheen 401 missing_api_key. Tuntemattomat avaimet palauttavat virheen 401 invalid_api_key; kumotut avaimet palauttavat virheen 401 revoked_api_key. Viisi virheellistä yritystä minuutin sisällä samasta IP-osoitteesta johtaa 60 minuutin estoon.

Rajoitukset

  • Enintään 5 aktiivista Bot Talk -avainta per botti
  • Enintään 60 pyyntöä minuutissa avainta kohden (token bucket, kapasiteetti 60, tasainen täyttyminen 1 tokeni per sekunti). Määritettävissä pienemmäksi luontivaiheessa - aseta alempi rateLimitPerMinute, jolloin katto laskee ja täyttönopeus skaalautuu sen mukana.
  • Viestin enimmäispituus 4 000 merkkiä
  • Samanaikaisten SSE-streamien määrä avainta kohden riippuu tilisi rajoituksista

Päätepisteet

POST /v1/chat

Lähetä viesti botille ja vastaanota koko vastaus yhtenä JSON-vastauksena.

Pyynnön runko

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - pakollinen merkkijono, enintään 4 000 merkkiä.
  • conversationId - valinnainen UUID. Jätä pois aloittaaksesi uuden keskustelun; käytä palvelimen aiemmin palauttamaa arvoa jatkaaksesi olemassa olevaa keskustelua.
  • metadata - valinnainen objekti: {source, userName, userEmail, userPhone}. userEmail-kenttää käytetään myös sisäisen asiakastunnisteen johtamiseen.

Vastauksen runko (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 on aina "assistant"; message.content on koko vastaus.
  • model on sen mallin tunniste, jolla botti suoritti tämän kutsun.
  • usage.creditsUsed huomioi käyttäjän viestin + botin vastauksen (yleensä 2) sekä yhden ylimääräisen creditin jokaista suoritettua työkalukutsua kohden.
  • actions listaa työkalujen suoritukset, jotka tapahtuivat tämän vuoron aikana. Tällä hetkellä palautetaan vain function_call-merkintöjä (kenttinä type, name, status: "completed").

POST /v1/chat/stream

/v1/chat-päätepisteen suoratoistoversio. Palauttaa otsakkeen Content-Type: text/event-stream käyttäen Server-Sent Events -tapahtumia.

Pyynnön runko

Samanmuotoinen kuin POST /v1/chat. Rungon stream-lippua ei tarvita - tämän polun käyttäminen käynnistää SSE:n automaattisesti.

Vastauksen runko (SSE-tapahtumat)

  • message.delta - sisältöfragmentti { "content": "..." }. Näitä saapuu useita peräkkäin sitä mukaa kuin tokeneita muodostuu.
  • action - työkalun suoritus { "type", "name", "status": "executing" }. Lähetetään, kun botti käynnistää funktiokutsun.
  • message.done - päättävä tapahtuma, joka sisältää kentät conversationId, model, usage ja (mahdollisen) suoritettujen toimintojen listan actions.
  • error - lähetetään, jos vastauksen luominen epäonnistuu; yhteys katkaistaan tämän jälkeen.

Yhteyttä ylläpitäviä SSE-kommentteja (:keepalive) lähetetään 15 sekunnin välein pitkien vastausten luomisen aikana. Palvelinpuolen aikakatkaisut: 30 sekuntia ensimmäiselle tokenille, 120 sekuntia yhteensä yhtä streamia kohden.

Curl-esimerkki

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

Listaa avaimeesi liitetyn botin keskustelut kaikista lähteistä (widget, WhatsApp, API jne.).

Kyselyparametrit

  • limit - 1-100, oletusarvo 20. Alueen ulkopuolella olevat arvot rajataan sallittuun väliin.
  • cursor - edellisellä sivulla kentässä nextCursor palautettu arvo. Jätä pois ensimmäisellä sivulla.

Vastauksen runko (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 katkaistaan 100 merkkiin ja sen perään lisätään ....
  • nextCursor on null viimeisellä sivulla; anna se cursor-parametrina hakeaksesi seuraavan sivun.

GET /v1/conversations/{conversation_id}

Koko keskusteluhistoria.

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

Vastauksessa palautetaan vain roolit user ja assistant; sisäiset system- ja työkaluviestit suodatetaan pois. Palauttaa virheen 404 not_found_error, jos keskustelu ei kuulu avaimeesi liitetylle botille.

Jos haluat tarkastella botin asetuksia ja määrityksiä, käytä Management API:n päätepistettä GET /v1/management/bots/{bot_id} Management-avaimella.

Pyyntörajojen otsakkeet

Vastaukset, jotka etenevät pyyntörajojen tarkistusvaiheeseen (eli todennus ja IP-sallittujen lista on hyväksytty), sisältävät seuraavat otsakkeet:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - tälle kutsulle todellisuudessa sovellettu avainkohtainen enimmäismäärä (oletuksena 60 tai määrittämäsi alempi rateLimitPerMinute).
  • X-RateLimit-Remaining - jäljellä olevat tokenit heti tämän kutsun jälkeen.
  • X-RateLimit-Reset - Unix-aikaleima sekunteina, jolloin seuraava tokeni on käytettävissä (ei koko kapasiteetin nollautuminen; tokenit täydentyvät jatkuvasti). Kun säiliö on täynnä, tämä vastaa nykyistä aikaa.

Vastauksissa 429 rate_limit_exceeded lähetetään myös Retry-After-otsake, joka ilmoittaa kokonaisina sekunteina ajan, kunnes vähintään yksi tokeni vapautuu.

Todennusta edeltävät virheet (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ja 403 ip_not_whitelisted eivät sisällä X-RateLimit-*-otsakkeita - rajoitinta tarkistetaan vasta todennuksen ja IP-tarkistusten onnistuttua.

Virhemuoto

Kaikki virheet noudattavat samaa perusrakennetta:

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

Yleisimmät HTTP-tilakoodit:

  • 400 invalid_request_error - virheellinen syöte (koodit: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - puuttuva avain (missing_api_key), tuntematon avain (invalid_api_key) tai kumottu avain (revoked_api_key)
  • 402 quota_exceeded_error - viesticreditit loppu
  • 403 permission_error - IP-osoite estetty (ip_blocked), IP-osoite ei ole avaimen sallittujen listalla (ip_not_whitelisted) tai avaintyyppi ei salli tätä päätepistettä (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - keskustelu ei kuulu tälle botille
  • 405 invalid_request_error (method_not_allowed) - väärä HTTP-verbi URL-osoitteessa
  • 429 rate_limit_error - liian monta pyyntöä (rate_limit_exceeded) tai liian monta samanaikaista streamia (concurrent_streams_exceeded)
  • 500 api_error - sisäinen virhe

Aiheeseen liittyvää

Tilintason toimenpiteitä (bottien luominen, päivittäminen ja kulutustietojen nouto) varten katso Management API.

Hae kaikista artikkeleistaKysy agentilta