Bot Talk API

Bot Talk API

Το Bot Talk API είναι ένα REST API για την επικοινωνία με ένα συγκεκριμένο chatbot μέσα από τη δική σας εφαρμογή - προσαρμοσμένες εφαρμογές, εσωτερικά εργαλεία ή αυτοματισμούς που δημιουργείτε εσείς. Δημιουργείτε ένα κλειδί API στην καρτέλα API του bot και, στη συνέχεια, καλείτε το chat endpoint χρησιμοποιώντας το κλειδί ως Bearer token για να λάβετε τις απαντήσεις του bot, είτε ως μεμονωμένη απόκριση είτε μέσω ροής SSE.

Ξεκινώντας

1. Επιλέξτε το chatbot σας και μεταβείτε στην καρτέλα API στο επάνω μέρος της σελίδας του bot (Select Bot > API [Επιλογή Bot > API]).

2. Κάντε κλικ στο Create API Key (Δημιουργία κλειδιού API).

Ο μετρητής δίπλα στο κουμπί δείχνει πόσα κλειδιά είναι ενεργά ("1 of 5 API keys active"). Ο σύνδεσμος View API Documentation (Προβολή τεκμηρίωσης API) ανοίγει αυτόν τον οδηγό αναφοράς και το απόσπασμα curl Quick Start (Γρήγορη εκκίνηση) σας δίνει ένα έτοιμο παράδειγμα προς εκτέλεση.

3. Στο παράθυρο διαλόγου Create API Key, δώστε ένα όνομα στο κλειδί, προαιρετικά ορίστε μια λίστα επιτρεπόμενων IP (IP whitelist) και ένα όριο ρυθμού αιτημάτων (rate limit), επιλέξτε ποια δικαιώματα θα διαθέτει και, στη συνέχεια, κάντε κλικ στο Create (Δημιουργία).

4. Αντιγράψτε το πλήρες κλειδί από το παράθυρο επιβεβαίωσης. Το κείμενο χωρίς κρυπτογράφηση εμφανίζεται μόνο μία φορά.

Ένα κλειδί έχει τη μορφή ck_abcdefghijklmnopqrstuvwxyz012345. Κάθε κλειδί ανήκει σε αυτό το συγκεκριμένο bot, επομένως κάθε αίτημα που πραγματοποιείται με το κλειδί επικοινωνεί με αυτό το bot - το bot αναγνωρίζεται από το κλειδί και δεν εμφανίζεται ποτέ στο URL.

Βασικό URL (Base URL)

https://api.chatlab.com/aichat

Όλα τα endpoints σε αυτό το άρθρο είναι σχετικά με αυτό το βασικό URL.

Δικαιώματα κλειδιού

Κάθε κλειδί φέρει ένα ή και τα δύο από τα ακόλουθα δικαιώματα, τα οποία ορίζονται με τους διακόπτες στο παράθυρο διαλόγου Create API Key:

• Chat (send messages and receive responses) - επιτρέπει τα endpoints /v1/chat και /v1/chat/stream.
• Conversation history (list and read past conversations) - επιτρέπει τα endpoints /v1/conversations.

Η καρτέλα API εμφανίζει τα εκχωρημένα δικαιώματα κάθε κλειδιού ως ετικέτες Chat και Conversations.

Έλεγχος ταυτότητας (Authentication)

Στέλνετε το κλειδί στην κεφαλίδα Authorization σε κάθε αίτημα:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Τα αιτήματα χωρίς κεφαλίδα Authorization: Bearer ... επιστρέφουν 401 missing_api_key. Τα άγνωστα κλειδιά επιστρέφουν 401 invalid_api_key, ενώ τα ανακληθέντα κλειδιά επιστρέφουν 401 revoked_api_key. Πέντε μη έγκυρες προσπάθειες μέσα σε ένα λεπτό από την ίδια IP ενεργοποιούν αποκλεισμό 60 λεπτών.

Όρια

• Έως 5 ενεργά κλειδιά Bot Talk ανά bot
• Έως 60 αιτήματα ανά λεπτό ανά κλειδί (αλγόριθμος token bucket, χωρητικότητα 60, ομαλή αναπλήρωση με ρυθμό 1 token ανά δευτερόλεπτο). Δυνατότητα προσαρμογής προς τα κάτω κατά τη δημιουργία - ορίστε ένα χαμηλότερο rateLimitPerMinute και το ανώτατο όριο μειώνεται, με τον ρυθμό αναπλήρωσης να προσαρμόζεται ανάλογα.
• Μέγιστο μήκος μηνύματος 4000 χαρακτήρες
• Οι ταυτόχρονες ροές SSE ανά κλειδί υπόκεινται στα όρια του λογαριασμού σας

Endpoints

POST /v1/chat

Στείλτε ένα μήνυμα στο bot και λάβετε την πλήρη απάντηση σε μία ενιαία απόκριση JSON.

Σώμα αιτήματος (Request body)

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}

• message - υποχρεωτικό string, έως 4000 χαρακτήρες.
• conversationId - προαιρετικό UUID. Παραλείψτε το για νέα συνομιλία. Επαναχρησιμοποιήστε την τιμή που επέστρεψε ο διακομιστής προηγουμένως για να συνεχίσετε μια υπάρχουσα.
• metadata - προαιρετικό αντικείμενο: {source, userName, userEmail, userPhone}. Το userEmail χρησιμοποιείται επίσης για την εξαγωγή του εσωτερικού αναγνωριστικού πελάτη (client id).

Σώμα απόκρισης (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 είναι πάντα "assistant", ενώ το message.content είναι η πλήρης απάντηση.
• Το model είναι το αναγνωριστικό του μοντέλου στο οποίο εκτελέστηκε το bot για αυτήν την κλήση.
• Το usage.creditsUsed αντιστοιχεί στο μήνυμα χρήστη + απάντηση bot (συνήθως 2), συν ένα επιπλέον credit ανά εκτελεσμένη κλήση εργαλείου (tool call).
• Το actions παραθέτει τις εκτελέσεις εργαλείων που έτρεξαν κατά τη διάρκεια αυτής της αλληλεπίδρασης. Προς το παρόν αποστέλλονται μόνο εγγραφές function_call (με type, name, status: "completed").

POST /v1/chat/stream

Παραλλαγή συνεχούς ροής (streaming) του /v1/chat. Επιστρέφει Content-Type: text/event-stream με συμβάντα Server-Sent Events.

Σώμα αιτήματος (Request body)

Ίδια δομή με το POST /v1/chat. Η παράμετρος stream στο σώμα δεν είναι απαραίτητη - η χρήση αυτής της διαδρομής ενεργοποιεί το SSE.

Σώμα απόκρισης (συμβάντα SSE)

• message.delta - απόσπασμα περιεχομένου { "content": "..." }. Αποστέλλονται πολλαπλά τέτοια συμβάντα καθώς λαμβάνονται τα tokens.
• action - εκτέλεση εργαλείου { "type", "name", "status": "executing" }. Εκπέμπεται όταν το bot ενεργοποιεί μια κλήση συνάρτησης.
• message.done - τελικό συμβάν με conversationId, model, usage και (εφόσον υπάρχουν) τη λίστα των ολοκληρωμένων actions.
• error - αποστέλλεται σε περίπτωση αποτυχίας της δημιουργίας. Η ροή τερματίζεται αμέσως μετά.

Σχόλια διατήρησης σύνδεσης SSE (:keepalive) αποστέλλονται κάθε 15 δευτερόλεπτα κατά τη διάρκεια εκτενών αποκρίσεων. Χρονικά όρια διακομιστή: 30 δευτερόλεπτα για το πρώτο token, 120 δευτερόλεπτα συνολικά ανά ροή.

Παράδειγμα 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

Λάβετε τη λίστα συνομιλιών για το bot που είναι συνδεδεμένο με το κλειδί σας, από όλες τις πηγές (widget, WhatsApp, API κ.λπ.).

Παράμετροι ερωτήματος (Query parameters)

• limit - 1-100, προεπιλογή 20. Οι τιμές εκτός εύρους προσαρμόζονται αυτόματα στα όρια.
• cursor - αδιαφανής τιμή που επιστράφηκε στο nextCursor της προηγούμενης σελίδας. Παραλείψτε το για την πρώτη σελίδα.

Σώμα απόκρισης (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 περικόπτεται στους 100 χαρακτήρες με κατάληξη ....
• Το nextCursor είναι null στην τελευταία σελίδα. Περάστε το ως παράμετρο cursor για να ανακτήσετε την επόμενη.

GET /v1/conversations/{conversation_id}

Πλήρες ιστορικό συνομιλίας.

Σώμα απόκρισης (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"}
  ]
}

Επιστρέφονται μόνο οι ρόλοι user και assistant. Τα εσωτερικά μηνύματα system και τα μηνύματα εργαλείων φιλτράρονται και εξαιρούνται. Επιστρέφει 404 not_found_error εάν η συνομιλία δεν ανήκει στο bot που συνδέεται με το κλειδί σας.

Για να ελέγξετε τις ρυθμίσεις του bot, χρησιμοποιήστε το endpoint του Management API GET /v1/management/bots/{bot_id} με ένα κλειδί Management.

Κεφαλίδες ορίου ρυθμού (Rate limit headers)

Οι αποκρίσεις που φτάνουν στο στάδιο ελέγχου ορίου ρυθμού (δηλ. έχουν περάσει επιτυχώς τον έλεγχο ταυτότητας και τη λίστα επιτρεπόμενων IP) περιλαμβάνουν:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000

• X-RateLimit-Limit - το ανώτατο όριο ανά κλειδί που εφαρμόστηκε πραγματικά σε αυτήν την κλήση (60 από προεπιλογή, ή το ρυθμισμένο rateLimitPerMinute εάν είναι χαμηλότερο).
• X-RateLimit-Remaining - τα tokens που απομένουν στο bucket αμέσως μετά από αυτήν την κλήση.
• X-RateLimit-Reset - δευτερόλεπτα εποχής Unix (Unix epoch seconds) κατά τα οποία το επόμενο token θα είναι διαθέσιμο (δεν πρόκειται για πλήρη επαναφορά του bucket, καθώς το bucket αναπληρώνεται συνεχώς). Όταν το bucket είναι γεμάτο, η τιμή αυτή αντιστοιχεί στην τρέχουσα ώρα.

Στις αποκρίσεις 429 rate_limit_exceeded, ορίζεται επίσης η κεφαλίδα Retry-After, η οποία εκφράζεται σε ακέραια δευτερόλεπτα μέχρι να απελευθερωθεί τουλάχιστον ένα token.

Σφάλματα πριν από τον έλεγχο ταυτότητας (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) καθώς και το 403 ip_not_whitelisted δεν φέρουν τις κεφαλίδες X-RateLimit-* - ο μηχανισμός περιορισμού ελέγχεται μόνο μετά την επιτυχή ολοκλήρωση του ελέγχου ταυτότητας και των επαληθεύσεων IP.

Μορφή σφαλμάτων

Όλα τα σφάλματα ακολουθούν μια κοινή δομή:

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

Συνήθεις κωδικοί HTTP:

• 400 invalid_request_error - μη έγκυρη είσοδος (κωδικοί: invalid_parameter, unsupported_media_type)
• 401 authentication_error - λείπει το κλειδί (missing_api_key), άγνωστο κλειδί (invalid_api_key) ή ανακληθέν κλειδί (revoked_api_key)
• 402 quota_exceeded_error - εξαντλήθηκαν τα credits μηνυμάτων
• 403 permission_error - αποκλεισμένη IP (ip_blocked), η IP δεν περιλαμβάνεται στη λίστα επιτρεπόμενων του κλειδιού (ip_not_whitelisted) ή ο τύπος κλειδιού δεν επιτρέπει αυτό το endpoint (key_type_not_allowed, insufficient_permissions)
• 404 not_found_error - η συνομιλία δεν ανήκει σε αυτό το bot
• 405 invalid_request_error (method_not_allowed) - εσφαλμένη μέθοδος HTTP στο URL
• 429 rate_limit_error - πάρα πολλά αιτήματα (rate_limit_exceeded) ή πάρα πολλές ταυτόχρονες ροές (concurrent_streams_exceeded)
• 500 api_error - εσωτερικό σφάλμα διακομιστή

Σχετικά

Για λειτουργίες σε επίπεδο λογαριασμού (δημιουργία bot, ενημέρωση bot, ανάκτηση δεδομένων χρήσης), δείτε το Management API.