Κέντρο βοήθειας
Chat API

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]).

Καρτέλα Bot Talk API

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

Επισημασμένη καρτέλα API, η επιλογή Create API Key βρίσκεται στο περιεχόμενο της σελίδας

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

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

Παράθυρο διαλόγου Create API Key

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

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

  1. Από τον διακομιστή σας, εκτελέστε το παρακάτω παράδειγμα curl με το κλειδί σας και ένα σύντομο δοκιμαστικό μήνυμα. Αποθηκεύστε το conversationId που επιστρέφεται και χρησιμοποιήστε το ξανά για ένα επόμενο μήνυμα. Επιβεβαιώστε την απάντηση και τη συνομιλία στην καρτέλα Chatlogs (Ιστορικό συνομιλιών) του bot.

Διατηρείτε τα κλειδιά ck_ στον διακομιστή σας και όχι στον κώδικα JavaScript του ιστοτόπου ή στα πακέτα εφαρμογών για κινητά. Το δικαίωμα Conversations παρέχει πρόσβαση στις αποθηκευμένες συνομιλίες αυτού του bot για όλους τους επισκέπτες, επομένως η εφαρμογή σας πρέπει να εξουσιοδοτεί κάθε τελικό χρήστη πριν από την επιστροφή αυτών των δεδομένων. Χρησιμοποιήστε την επιλογή Revoke (Ανάκληση) ή Delete (Διαγραφή) στην καρτέλα API για να αποσύρετε ένα κλειδί - καμία από τις δύο ενέργειες δεν εμφανίζει ξανά το αρχικό κείμενό του.

Πριν ξεκινήσετε, δημιουργήστε και εκπαιδεύστε το chatbot σας και βεβαιωθείτε ότι ο λογαριασμός σας περιλαμβάνει πρόσβαση στο API και διαθέτει πιστώσεις μηνυμάτων.

Base URL

https://api.chatlab.com/aichat

Όλα τα endpoints σε αυτό το άρθρο είναι σχετικά με αυτό το base 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.

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

Στέλνετε το κλειδί στην κεφαλίδα 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 - απαιτούμενη συμβολοσειρά, έως 4000 χαρακτήρες.
  • conversationId - προαιρετικό UUID. Παραλείψτε το για νέα συνομιλία. Επαναχρησιμοποιήστε την τιμή που επέστρεψε ο διακομιστής προηγουμένως για να συνεχίσετε μια υπάρχουσα.
  • metadata - προαιρετικό αντικείμενο που δέχεται {source, userName, userEmail, userPhone}. Επί του παρόντος χρησιμοποιείται μόνο το userEmail εδώ, για την εξαγωγή του αναγνωριστικού πελάτη. Το κανάλι καταγράφεται ως API. Μην βασίζεστε στην αποθήκευση των υπόλοιπων πεδίων μεταδεδομένων σε εγγραφή υποψήφιου πελάτη (lead).

Σώμα απόκρισης (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 είναι πάντα "assistant". Το message.content περιέχει την πλήρη απάντηση.
  • Το model είναι το id του μοντέλου στο οποίο εκτελέστηκε το bot για αυτήν την κλήση.
  • Το usage.creditsUsed αναφέρει επί του παρόντος 2 συν μία πίστωση ανά καταγεγραμμένη κλήση εργαλείου για έναν ολοκληρωμένο γύρο συνομιλίας. Αυτός ο μετρητής απόκρισης δεν περιλαμβάνει πολλαπλασιαστές πιστώσεων μοντέλου/πλαισίου (context) και δεν πρέπει να χρησιμοποιείται ως λογιστικό καθολικό χρέωσης. Χρησιμοποιήστε την κατανάλωση του Management API για τη χρήση του λογαριασμού και δείτε τις πιστώσεις μηνυμάτων.
  • Το 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.reset - απορρίπτει το κείμενο που έχει συγκεντρωθεί για την τρέχουσα απάντηση και ξεκινά ξανά τη συλλογή τμημάτων (deltas). Αυτό μπορεί να συμβεί όταν επανεκκινείται η παραγωγή απάντησης. Η προσθήκη και των δύο εκδόσεων θα εμφάνιζε διπλότυπη ή αντικατασταθείσα απάντηση.
  • 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 στην προηγούμενη σελίδα. Παραλείψτε το για την πρώτη σελίδα.

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

GET /v1/conversations/{conversation_id}

Αποθηκευμένα μηνύματα συνομιλίας που εκτίθενται από αυτό το endpoint.

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

Επιστρέφονται μόνο οι ρόλοι 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 epoch στα οποία γίνεται διαθέσιμο το επόμενο 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)
  • 415 invalid_request_error - μη υποστηριζόμενος τύπος περιεχομένου (unsupported_media_type)
  • 401 authentication_error - λείπει το κλειδί (missing_api_key), άγνωστο κλειδί (invalid_api_key) ή ανακληθέν κλειδί (revoked_api_key)
  • 402 quota_exceeded_error - εξαντλήθηκαν οι πιστώσεις μηνυμάτων
  • 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.

Αναζήτηση σε όλα τα άρθραΡωτήστε τον ψηφιακό βοηθό