Οδηγοί

Συνδέσεις

Ο βοηθός AI σας (Claude, ChatGPT) και ο φωνητικός πράκτορας στην κλήση μπορούν να διαβάσουν το Google Calendar και το Apple Calendar και, μετά την έγκρισή σας, να ενημερώσουν ένα υπάρχον συμβάν - ενώ ο φωνητικός πράκτορας στη δική μηχανή του volai μπορεί επιπλέον να βρει ελεύθερη ώρα και να καταχωρίσει αμέσως το ραντεβού μέσα στην ίδια την κλήση. Στο Apple πρέπει να διατηρείτε τα αδιαφανή αναγνωριστικά και να προσέχετε τις επαναλαμβανόμενες σειρές.

Τι μπορεί και τι δεν μπορεί να κάνει

• Εμφανίζει τη λίστα των συνδεδεμένων ημερολογίων και των συμβάντων τους.
• Αλλάζει τον τίτλο, την έναρξη ή τη λήξη ενός υπάρχοντος συμβάντος.
• Ο φωνητικός πράκτορας στη δική μηχανή του volai βρίσκει στην κλήση ελεύθερη ώρα και καταχωρίζει αμέσως το ραντεβού.
• Βρίσκει ελεύθερες ώρες και δημιουργεί ραντεβού και εκτός κλήσης, μέσω REST και MCP.

Δεν μπορεί

• Δεν διαγράφει κανένα συμβάν.
• Δεν αναζητά ελεύθερες ώρες ανάμεσα σε περισσότερους συμμετέχοντες.

Σύνδεση λογαριασμού Google

Τον λογαριασμό Google τον συνδέετε στην πύλη, στην ενότητα Συνδέσεις (στο αγγλικό μενού της πύλης το στοιχείο «Integrations»). Μόλις συνδεθεί ο λογαριασμός, το ίδιο κλειδί API βλέπει τα ίδια δεδομένα μέσω REST και MCP - χωρίς δεύτερη σύνδεση.

Τον λογαριασμό μπορείτε να τον αποσυνδέσετε στην πύλη ή μέσω REST DELETE /v1/integrations/{id}. Το REST αποσυνδέει την ενσωμάτωση αμέσως και χωρίς επιπλέον πεδίο επιβεβαίωσης, γι' αυτό καλέστε το μόνο μετά από ρητή έγκριση του χρήστη. Το MCP δεν διαθέτει εργαλείο αποσύνδεσης.

Apple Calendar

Συνδέεται με κωδικό για συγκεκριμένη εφαρμογή (όχι με τον συνήθη κωδικό του λογαριασμού Apple) στην πύλη, στην ενότητα Δεδομένα και ενσωματώσεις. Τη σύνδεση μπορεί να κάνει και το REST POST /v1/integrations με {provider: "apple-calendar", username, appPassword, calendarUrl?}· το MCP δεν δέχεται διαπιστευτήρια και χρησιμοποιεί τον λογαριασμό μόνο αφού συνδεθεί.

Το list_calendar_events και το REST GET /v1/integrations/{id}/events υποστηρίζουν το Apple Calendar. Το αδιαφανές externalId που επιστρέφεται περάστε το αμετάβλητο ως eventId στο get_calendar_event και στις ενημερώσεις· δεν είναι UID του iCalendar. Γραμμή με recurring: true αντιπροσωπεύει ολόκληρη την επαναλαμβανόμενη σειρά και η ενημέρωσή της αλλάζει τη βάση της σειράς, όχι ένα μεμονωμένο περιστατικό· οι μεμονωμένες εξαιρέσεις διατηρούνται.

Το calendarId πρέπει να είναι μία από τις διευθύνσεις που επιστρέφει το list_calendars - οτιδήποτε άλλο το API το απορρίπτει με σφάλμα 400 calendar_invalid_calendar.

Ραντεβού μέσα στην κλήση

Ο φωνητικός πράκτορας στη δική μηχανή του volai μπορεί μέσα στην ίδια την τηλεφωνική κλήση να βρει ελεύθερη ώρα και να καταχωρίσει αμέσως το ραντεβού - δεν πρόκειται για βοηθό AI σε συνομιλία, αλλά για κλήση που διεξάγει ο ίδιος ο φωνητικός πράκτορας. Ενεργοποιείται στον επεξεργαστή του πράκτορα, στην καρτέλα Ημερολόγιο: επιλέγετε τη σύνδεση, το ημερολόγιο και τους κανόνες διαθεσιμότητας (παράθυρα ανά ημέρα της εβδομάδας, διάρκεια ραντεβού, περιθώριο μεταξύ ραντεβού, ελάχιστη προειδοποίηση, ορίζοντας αναζήτησης).

• Λειτουργεί μόνο σε πράκτορα στη δική μηχανή φωνής του volai - σε πράκτορα στο ElevenLabs η ρύθμιση αποθηκεύεται και περιμένει την αυτόματη αλλαγή μηχανής.
• Ο πράκτορας δεν λέει ποτέ τι είναι καταχωρισμένο στο ημερολόγιο - μόνο αν μια συγκεκριμένη ώρα είναι ελεύθερη.
• Το τηλέφωνο του καλούντος γράφεται στο συμβάν μόνο όταν το γνωρίζει ο πράκτορας· κρυφός αριθμός σημαίνει συμβάν χωρίς τηλέφωνο.
• Η ίδια αναζήτηση ελεύθερων ωρών και η καταχώριση ραντεβού γίνονται και εκτός κλήσης μέσω REST (POST .../availability, POST .../events) και MCP (find_free_slots, create_calendar_event).

Fakturoid και ABRA Flexi

Αυτή η σελίδα καλύπτει μόνο τα ημερολόγια. Το Fakturoid και το ABRA Flexi συνδέονται στο ίδιο σημείο (list_integrations/GET /v1/integrations, ενότητα Δεδομένα και ενσωματώσεις στην πύλη), αλλά η ανάγνωση τιμολογίων και η χρήση τους στις Εργασίες υπενθύμισης έχουν δικό τους οδηγό, Τιμολόγια.

Διαδικασία για πράκτορα

Η ενημέρωση ενός συμβάντος έχει πάντα έξι βήματα, με αυτή τη σειρά:

• 1. list_integrations - τα συνδεδεμένα ημερολόγια και το integrationId τους.
• 2. list_calendars - τα ημερολόγια της συγκεκριμένης σύνδεσης και το calendarId τους.
• 3. list_calendar_events, έπειτα get_calendar_event με το externalId που επιστράφηκε ως eventId - διαβάζει το συμβάν και το τρέχον sourceRevision του.
• 4. propose_calendar_update - ετοιμάζει πρόταση αλλαγής, δεν γράφει ακόμη τίποτα.
• 5. Έγκριση από τον χρήστη - ο πράκτορας δείχνει τις αρχικές τιμές και την πρόταση και μόνο τότε συνεχίζει.
• 6. confirm_calendar_update με confirm: true - μόνο αυτό το βήμα γράφει την αλλαγή στο Google/Apple.

Ισοδύναμα REST: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, έπειτα POST /v1/integrations/{id}/events/{eventId}/propose με {calendarId, sourceRevision, patch} και μετά την έγκριση PATCH /v1/integrations/{id}/events/{eventId} με τις ίδιες τιμές και confirm: true.

Σφάλματα

• calendar_stale_revision - Το συμβάν άλλαξε στο μεταξύ αλλού - διαβάστε το ξανά (get_calendar_event) και αφήστε τον χρήστη να εγκρίνει τη νέα πρόταση.
• calendar_oauth_failed - Το Google απέρριψε τη σύνδεση - η σύνδεση πρέπει να γίνει ξανά στην πύλη.
• calendar_unauthorized - Η σύνδεση έπαψε να ισχύει (ανακληθείσα πρόσβαση, ληγμένο διακριτικό) - συνδέστε ξανά τον λογαριασμό.
• calendar_confirmation_required - Εγγραφή χωρίς confirm: true - επιβεβαιώστε την πρόταση μόνο μετά την έγκριση του χρήστη.
• calendar_verification_failed - Η εγγραφή έγινε, αλλά η νέα ανάγνωση δεν ταιριάζει με την αλλαγή που στάλθηκε - ελέγξτε την κατάσταση χειροκίνητα, μην ξαναεπεξεργαστείτε στα τυφλά.

Τον πλήρη πίνακα με όλους τους κωδικούς θα βρείτε στην ενότητα Ημερολόγια στην αναφορά του REST API και στα σφάλματα MCP.

Ασφάλεια

Τα διακριτικά πρόσβασης σε λογαριασμό Google ή Apple δεν επιστρέφονται ποτέ από το REST API ή το MCP και αποθηκεύονται κρυπτογραφημένα. Το appPassword του Apple στείλτε το μέσω REST μόνο αν ο χρήστης το έχει ήδη αποθηκεύσει με ασφάλεια σε μεταβλητή περιβάλλοντος ή σε αρχείο που ονόμασε ο ίδιος - μην το ζητάτε ποτέ σε συνομιλία και μην το επαναλαμβάνετε. Την ενσωμάτωση την αποσυνδέετε στην πύλη ή μέσω REST DELETE /v1/integrations/{id} μετά από ρητή έγκριση του χρήστη· το MCP δεν προσφέρει αποσύνδεση.