Συναρτήσεις

Χρησιμοποιήστε το συμβόλαιο OpenAPI για να δημιουργήσετε έναν client ενσωμάτωσης. Το δημόσιο API, ο πίνακας ελέγχου και το endpoint διαχείρισης MCP λειτουργούν στους ίδιους πόρους και τα ίδια δικαιώματα του χώρου εργασίας.

Δυνατότητα	Endpoint
Επαναχρησιμοποιήσιμα εργαλεία	GET / POST /api/v1/voice/tools
Ανάγνωση / ενημέρωση / διαγραφή εργαλείου	GET / PATCH / DELETE /api/v1/voice/tools/{id}
Προεπισκόπηση ή δοκιμή εργαλείου	POST /api/v1/voice/tools/{id}/test
Σύνδεση εργαλείων σε πράκτορα	PUT /api/v1/voice/agents/{id}/tools
Βάσεις γνώσης	GET / POST /api/v1/voice/knowledge-bases
Ανάγνωση / ενημέρωση / διαγραφή βάσης γνώσης	GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id}
Προσθήκη / λίστα εγγράφων	POST / GET /api/v1/voice/knowledge-bases/{id}/documents
Ανάγνωση / διαγραφή εγγράφου	GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id}
Συνδρομές σε συμβάντα κλήσεων	GET / POST /api/v1/voice/webhooks
Ανάγνωση / ενημέρωση / διαγραφή συνδρομής	GET / PATCH / DELETE /api/v1/voice/webhooks/{id}
Αποστολή υπογεγραμμένου δοκιμαστικού συμβάντος	POST /api/v1/voice/webhooks/{id}/test
Ανακάλυψη απομακρυσμένων εργαλείων MCP	POST /api/v1/voice/mcp/discover
Endpoint διαχείρισης MCP	/api/v1/voice/mcp

Καταχωρίστε ένα εργαλείο HTTP που ρωτά τον προσαρμογέα CRM σας:

{
  "name": "lookup_customer",
  "description": "Find a customer after confirming their customer ID.",
  "kind": "http",
  "url": "https://crm.example.com/customers/{{customer_id}}",
  "method": "GET",
  "read_only": true,
  "credential_ref": "crm",
  "input_schema": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"],
    "additionalProperties": false
  },
  "response_path": "data"
}

Το POST /tools επιστρέφει { "data": { "id": "TOOL_ID", ... } }. Συνδέστε τον ορισμό του σε έναν πράκτορα με PUT /agents/AGENT_ID/tools και { "tool_ids": ["TOOL_ID"] }. Αυτό αντικαθιστά ολόκληρη τη λίστα εργαλείων με στιγμιότυπα· συνδέστε ξανά όταν αλλάζει ένα εργαλείο της βιβλιοθήκης. Η διαγραφή ενός ορισμού της βιβλιοθήκης διατηρεί τα υπάρχοντα στιγμιότυπα. Μπορείτε επίσης να διαβάζετε και να αντικαθιστάτε ενσωματωμένους ορισμούς με το πεδίο tools του API πρακτόρων. Χρησιμοποιήστε τα analysis_config και widget_config για να ρυθμίσετε την ανάλυση και το widget μέσω του API πρακτόρων.

Ένα εργαλείο μπορεί να χρησιμοποιεί GET, POST, PUT, PATCH ή DELETE. Τα query και request_body δέχονται εμφωλευμένα πρότυπα JSON όπως { "customer": { "id": "{{customer_id}}" } }. Ένα ολόκληρο δεσμευτικό θέσης διατηρεί τον αρχικό τύπο JSON. Τα δεσμευτικά θέσης στο URL κωδικοποιούνται και μπορούν να εμφανίζονται μόνο μετά από έναν σταθερό δημόσιο διακομιστή HTTPS. Χωρίς request_body, τα εργαλεία που δεν είναι GET λαμβάνουν { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. Το response_path επιλέγει ένα πεδίο με συμβολισμό τελείας. Οι απλές parameters εξακολουθούν να γίνονται δεκτές· το input_schema υποστηρίζει επιπλέον εμφωλευμένα αντικείμενα, πίνακες, απαριθμήσεις και αριθμητικά όρια. Εξωτερικές αναφορές σε σχήματα και κανονικές εκφράσεις δεν γίνονται δεκτές.

Σταθερές τιμές, μεταφορά τιμών και κανόνες απόρριψης

• static_args: τιμές που στέλνονται με κάθε κλήση ό,τι κι αν γράψει το μοντέλο, όπως ένα αναγνωριστικό καταστήματος· συμπληρώνουν επίσης το {{name}} στη διεύθυνση και στο σώμα.
• extract: το [{name, path}] διατηρεί πεδία από την απάντηση μιας συνάρτησης (data.id) για το {{name}} των επόμενων συναρτήσεων, ώστε το customer_id μιας αναζήτησης να περάσει στην παραγγελία που ακολουθεί χωρίς να το επαναλάβει το μοντέλο. Τα πεδία μιας αναζήτησης έναρξης διατηρούνται με τον ίδιο τρόπο.
• reject_when: έως 5 κανόνες {on: caller|agent, pattern, negate}· όσο ισχύουν όλοι για τις τελευταίες λέξεις, η συνάρτηση δεν εκτελείται και ο πράκτορας λαμβάνει το reject_message.
• model_says: σε κάθε κλήση το μοντέλο γράφει μία πρόταση που λέγεται ενώ εκτελείται η συνάρτηση, αντί για το σταθερό speak_before.

Έτοιμες συναρτήσεις: κρατήσεις, υπολογιστικά φύλλα, Slack

Συνδέστε μια εφαρμογή στο Ενσωματώσεις → Webhooks και ειδοποιήσεις → Συνδεδεμένες εφαρμογές και μετά χρησιμοποιήστε το «Προσθήκη έτοιμης συνάρτησης» στην καρτέλα Γνώση και εργαλεία του πράκτορα· δεν χρειάζεστε δικό σας endpoint:

• Κρατήσεις (Google Calendar / Cal.com): προσθέτει τα check_availability (ελεύθερες ώρες σε μια ημερομηνία) και book_appointment (κλείνει την ώρα που διάλεξε ο καλών). Οι ώρες του Google Calendar ακολουθούν τη ζώνη ώρας, τις ανοιχτές ημέρες, τις ώρες και τη διάρκεια ραντεβού που ορίζετε· το Cal.com χρησιμοποιεί τη δική του διαθεσιμότητα του τύπου συμβάντος και ένα εναλλακτικό email που ορίζετε για όταν ο καλών δεν δίνει κανένα.
• Αποθήκευση στο Google Sheets: προσθέτει το save_to_sheet, που προσθέτει μια γραμμή με τις στήλες που αναφέρετε, συν το ID και την ώρα της κλήσης.
• Ειδοποίηση της ομάδας (Slack): προσθέτει το notify_team, που δημοσιεύει ένα μήνυμα που γράφει ο πράκτορας σε κανάλι Slack (incoming webhook).

Το επίπεδο ελέγχου της EvaSay εκτελεί αυτές τις συναρτήσεις με τον λογαριασμό που συνδέσατε· ούτε ο worker ούτε ο ορισμός του πράκτορα κρατούν τα διαπιστευτήρια της εφαρμογής. Η ανάγνωση ενός πράκτορα μέσω του API τις εμφανίζει ως kind: "app" (με app, action, connection_id, app_config)· στείλτε τις πίσω αμετάβλητες όταν αντικαθιστάτε τα tools για να τις κρατήσετε. Οι εφαρμογές συνδέονται μόνο στον πίνακα ελέγχου.

Αναζήτηση του καλούντος κατά την έναρξη μιας κλήσης

Ορίστε run_at_start: true σε ένα από τα εργαλεία ενός πράκτορα και καλείται όταν ξεκινά κάθε κλήση, πριν χαιρετήσει ή απαντήσει ο πράκτορας. Οι παράμετροι με ονόματα caller_number, called_number, direction, channel ή call_id συμπληρώνονται γι' αυτό. Τα πεδία που επιστρέφει συμπληρώνουν τα {{variables}} στα first_message, system_prompt και idle_messages (πεδία ένα επίπεδο πιο κάτω ως {{customer.name}}), και ολόκληρη η απάντηση δίνεται στον πράκτορα ως πλαίσιο. Ένας χαιρετισμός με μεταβλητές περιμένει την απάντηση έως 3 δευτερόλεπτα· ό,τι δεν βρεθεί μένει κενό. Ένα εργαλείο ανά πράκτορα μπορεί να εκτελείται στην έναρξη.

Τα διαπιστευτήρια ρυθμίζονται στο περιβάλλον του διακομιστή για τον χώρο εργασίας και τον προορισμό σας· ζητήστε από το support@evasay.com να δημιουργήσει ένα credential_ref. Μην βάζετε κλειδιά API σε ορισμούς πρακτόρων, κεφαλίδες, prompts ή παραμέτρους εργαλείων. Ο προσαρμογέας σας μπορεί να κρατά τα διαπιστευτήρια του CRM στο δικό του περιβάλλον.

Κάντε προεπισκόπηση ενός εργαλείου πριν στείλετε αιτήματα στο επιχειρηματικό σύστημα:

{
  "arguments": { "customer_id": "customer-123" },
  "dry_run": true,
  "mock_result": { "name": "Alex", "order_status": "shipped" }
}

Μια προεπισκόπηση επικυρώνει τις παραμέτρους και δείχνει το αντιστοιχισμένο αίτημα· δεν εκτελεί συνομιλία ούτε επικοινωνεί με το επιχειρηματικό σύστημα. Ορίστε dry_run=false για πραγματική εκτέλεση. Μια ζωντανή δοκιμή εγγραφής απαιτεί επίσης confirmed=true και idempotency_key (8–128 γράμματα, αριθμοί, τελείες, κάτω παύλες, άνω και κάτω τελείες ή παύλες). Οι απαντήσεις δοκιμών περιλαμβάνουν ok, status, duration_ms και ένα περιορισμένο αποτέλεσμα. Δεν επιστρέφουν διαπιστευτήρια. Οι δοκιμές ανάγνωσης και εγγραφής απαιτούν δικαίωμα εγγραφής στον χώρο εργασίας.

Κατά τη διάρκεια μιας κλήσης, τα επιχειρηματικά αιτήματα φέρουν ένα σταθερό Idempotency-Key. Το επιχειρηματικό σας endpoint πρέπει να το τηρεί. Πανομοιότυπες εγγραφές μέσα σε μια κλήση αποδιπλασιάζονται, συμπεριλαμβανομένων λειτουργιών με άγνωστο αποτέλεσμα μετά από timeout. Μια διαφορετική σκόπιμη λειτουργία χρειάζεται ξεχωριστό επιχειρηματικό όρισμα, όπως operation_id. Η EvaSay δεν επαναλαμβάνει αυτόματα τις εγγραφές. Τα συμβάντα εκτέλεσης εργαλείων περιλαμβάνουν κατάσταση και διάρκεια· η λειτουργία δοκιμής συνομιλίας παραμένει προσομοίωση κειμένου, όχι δοκιμή εκτέλεσης εργαλείων.

Επιτρέψτε στον φωνητικό πράκτορα να καλεί έναν εξωτερικό διακομιστή MCP

Το POST /mcp/discover δέχεται { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } και επιστρέφει τα εργαλεία και τα σχήματα του διακομιστή. Καταχωρίστε μόνο το επιλεγμένο εργαλείο:

{
  "name": "lookup_customer",
  "description": "Find a CRM customer by confirmed ID.",
  "kind": "mcp",
  "url": "https://crm.example.com/mcp",
  "mcp_tool": "get_customer",
  "credential_ref": "crm",
  "read_only": true,
  "input_schema": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"]
  }
}

Μόνο τα καταχωρισμένα εργαλεία γίνονται διαθέσιμα στον πράκτορα. Οι απομακρυσμένες συνδέσεις υποστηρίζουν Streamable HTTP με απαντήσεις JSON ή SSE στα αιτήματα, δημόσιους προορισμούς HTTPS και προρυθμισμένα διαπιστευτήρια. Τα παλαιά endpoints SSE, η διαπραγμάτευση OAuth, το sampling/elicitation που ξεκινά ο διακομιστής και τα δυαδικά συνημμένα δεν υποστηρίζονται. Η ανακάλυψη δεν παρέχει αυτόματα πρόσβαση σε όλα τα εργαλεία του διακομιστή. Το σχήμα του απομακρυσμένου εργαλείου πρέπει να είναι ενσωματωμένο και να χρησιμοποιεί το υποστηριζόμενο υποσύνολο του JSON Schema.