Ohjekeskus
Chat API

Bot Talk API

Viimeksi päivitetty:

Bot Talk API

Bot Talk API on REST API, jonka avulla voit keskustella tietyn chatbotin kanssa omasta sovelluksestasi - räätälöidyistä sovelluksista, sisäisistä työkaluista tai itse rakentamistasi automaatioista. Luot API-avaimen botin API-välilehdellä ja kutsut sitten chat-päätepistettä käyttäen avainta Bearer-tokenina saadaksesi botin vastaukset joko yksittäisenä vastauksena tai SSE-yhteyden kautta suoratoistettuna.

Aloittaminen

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

Bot Talk API -välilehti

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

API-välilehti korostettuna; Create API Key on sivun sisällössä

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 (Pikaopas) -curl-katkelma tarjoaa heti suoritettavan esimerkin.

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

Create API Key -valintaikkuna

  1. Kopioi koko avain onnistumisilmoituksesta. Selväkielinen avain näytetään vain kerran.

Avain näyttää tältä: ck_abcdefghijklmnopqrstuvwxyz012345. Jokainen avain kuuluu kyseiselle yhdelle botille, joten jokainen avaimella tehty pyyntö viestii kyseisen botin kanssa - botti tunnistetaan avaimen perusteella, eikä se koskaan näy URL-osoitteessa.

  1. Suorita palvelimeltasi alla oleva curl-esimerkki käyttäen avaintasi ja lyhyttä testiviestiä. Tallenna palautettu conversationId ja käytä sitä uudelleen jatkoviestissä. Vahvista vastaus ja keskustelu botin Chatlogs (Keskusteluhistoria) -välilehdellä.

Säilytä ck_-avaimet palvelimellasi, älä verkkosivuston JavaScript-koodissa tai mobiilisovellusten paketeissa. Conversations-oikeus antaa pääsyn tämän botin tallennettuihin keskusteluihin eri kävijöiltä, joten sovelluksesi on todennettava jokainen loppukäyttäjä ennen kyseisten tietojen palauttamista. Voit poistaa avaimen käytöstä API-välilehden toiminnoilla Revoke (Mitätöi) tai Delete (Poista); kumpikaan toiminto ei näytä sen selväkielistä arvoa uudelleen.

Ennen aloittamista luo ja kouluta chatbotisi sekä varmista, että tiliisi sisältyy API-käyttöoikeus ja että sillä on viestisaldoa.

Perus-URL

https://api.chatlab.com/aichat

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

Avaimen käyttöoikeudet

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

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

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

Todennus

Lähetä avain jokaisen pyynnön Authorization-otsakkeessa:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

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

Rajoitukset

  • Enintään 5 aktiivista Bot Talk -avainta bottia kohden
  • Enintään 60 pyyntöä minuutissa avainta kohden (token bucket, kapasiteetti 60, tasainen täyttönopeus 1 token sekunnissa). Määritettävissä pienemmäksi luontivaiheessa - aseta matalampi rateLimitPerMinute, jolloin enimmäismäärä laskee ja täyttönopeus skaalautuu sen mukana.
  • Viestin enimmäispituus 4000 merkkiä
  • Samanaikaisten SSE-tietovirtojen 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 4000 merkkiä.
  • conversationId - valinnainen UUID. Jätä pois uutta keskustelua varten; käytä palvelimen aiemmin palauttamaa arvoa jatkaaksesi olemassa olevaa keskustelua.
  • metadata - valinnainen objekti, joka hyväksyy kentät {source, userName, userEmail, userPhone}. Tällä hetkellä tässä käytetään vain kenttää userEmail asiakastunnisteen johtamiseen; kanavaksi tallennetaan API. Älä luota siihen, että muut metatietokentät tallentuisivat liiditietueeseen.

Vastauksen runko (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 on aina "assistant"; message.content on koko vastaus.
  • model on sen mallin tunniste, jota botti käytti tähän kutsuun.
  • usage.creditsUsed ilmoittaa tällä hetkellä 2 plus yhden jokaista suoritettua työkalukutsua kohden valmistunutta vuoroa kohti. Tämä vastauksen laskuri ei sisällä malli-/kontekstikohtaisia krediittikertoimia, eikä sitä saa käyttää laskutuskirjanpitona. Käytä tilin kulutuksen seurantaan Management API usage -tietoja ja katso viestisaldot.
  • actions luettelee työkalujen suoritukset, jotka ajettiin tämän vuoron aikana. Tällä hetkellä vain function_call-merkinnät lähetetään (kentillä type, name, status: "completed").

POST /v1/chat/stream

Suoratoistava variantti päätepisteestä /v1/chat. Palauttaa otsakkeen Content-Type: text/event-stream Server-Sent Events (SSE) -muodossa.

Pyynnön runko

Sama rakenne kuin POST /v1/chat. Rungon stream-lippua ei vaadita - tämän polun käyttäminen itsessään käynnistää SSE-suoratoiston.

Vastauksen runko (SSE-tapahtumat)

  • message.reset - hylkää nykyiselle vastaukselle kertyneen tekstin ja aloita muutosten kerääminen alusta. Tätä voi tapahtua, kun luonti käynnistyy uudelleen; molempien versioiden yhdistäminen näyttäisi kaksoiskappaleen tai korvatun vastauksen.
  • message.delta - sisältökatkelma { "content": "..." }. Näitä suoratoistetaan useita sitä mukaa kuin tokeneita saapuu.
  • 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 (jos sellaisia on) valmistuneen actions-luettelon.
  • error - lähetetään, jos luonti epäonnistuu; tietovirta päättyy 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ä tietovirtaa 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 sidotun botin keskustelut kaikista lähteistä (widget, WhatsApp, API jne.).

Kyselyparametrit

  • limit - 1-100, oletus 20. Alueen ulkopuolella olevat arvot rajataan sallittuun väliin.
  • cursor - edellisen sivun 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; välitä se arvona cursor hakeaksesi seuraavan sivun.

GET /v1/conversations/{conversation_id}

Tämän päätepisteen palauttamat tallennetut keskusteluviestit.

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

Vain roolit user ja assistant palautetaan; sisäiset system- ja työkalujen viestit suodatetaan pois. Palauttaa virheen 404 not_found_error, jos keskustelu ei kuulu avaimeesi sidotulle botille.

Tarkastellaksesi botin määrityksiä käytä Management API -päätepistettä GET /v1/management/bots/{bot_id} Management-avaimella.

Pyyntörajoitusotsakkeet

Vastaukset, jotka etenevät pyyntörajoitusvaiheeseen asti (eli todennus ja sallittujen IP-osoitteiden tarkistus on läpäisty), sisältävät seuraavat otsakkeet:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - tähän kutsuun todellisuudessa sovellettu avainkohtainen enimmäismäärä (oletuksena 60 tai määrittämäsi rateLimitPerMinute, jos se on pienempi).
  • X-RateLimit-Remaining - jäljellä olevat tokenit heti tämän kutsun jälkeen.
  • X-RateLimit-Reset - Unix-aikaleima sekunteina, jolloin seuraava token tulee saataville (tämä ei tarkoita koko kiintiön nollautumista; kiintiö täyttyy jatkuvasti). Kun kiintiö on täysi, tämä on nykyinen aika.

Vastauksissa 429 rate_limit_exceeded asetetaan myös otsake Retry-After, joka ilmaistaan kokonaisina sekunteina siihen asti, kunnes vähintään yksi token vapautuu.

Ennen todennusta tapahtuvat virheet (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ja 403 ip_not_whitelisted eivät sisällä X-RateLimit-*-otsakkeita - pyyntörajoitinta tarkistetaan vasta onnistuneen todennuksen ja IP-tarkistusten jälkeen.

Virhemuoto

Kaikki virheet käyttävät samaa rakennetta:

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

Yleiset HTTP-tilakoodit:

  • 400 invalid_request_error - virheellinen syöte (invalid_parameter)
  • 415 invalid_request_error - sisältötyyppiä ei tueta (unsupported_media_type)
  • 401 authentication_error - puuttuva avain (missing_api_key), tuntematon avain (invalid_api_key) tai mitätöity avain (revoked_api_key)
  • 402 quota_exceeded_error - viestisaldo on loppunut
  • 403 permission_error - IP-osoite on 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 tietovirtaa (concurrent_streams_exceeded)
  • 500 api_error - sisäinen virhe

Aiheeseen liittyvää

Tilitason toiminnoista (bottien luominen, bottien päivittäminen, kulutustietojen noutaminen) kerrotaan artikkelissa Management API.

Hae kaikista artikkeleistaKysy agentilta