Πώς να καλέσετε έναν πελάτη από ένα workflow του n8n

Μπορείτε να καλέσετε έναν πελάτη από το n8n χωρίς να γράψετε ούτε μία γραμμή κώδικα: προσθέστε στο workflow σας έναν κόμβο HTTP Request, ρυθμίστε τον σε POST https://volai.cz/v1/calls με κεφαλίδα Authorization: Bearer vk_... και σώμα {to, agentId} - και ο φωνητικός σας πράκτορας καλεί τον αριθμό ακριβώς τη στιγμή που το χρειάζεται το workflow. Παρακάτω θα βρείτε ολόκληρη τη διαδικασία: πώς αντιστοιχίζετε τα δεδομένα του workflow στο prompt του πράκτορα, πώς επιστρέφει το αποτέλεσμα της κλήσης στο n8n και πώς καλείτε ακόμη και χωρίς πράκτορα, συνδέοντας απευθείας δύο αριθμούς.

Τι θα χρειαστείτε

• Μια εγκατάσταση n8n - cloud ή self-hosted, σε οποιαδήποτε πρόσφατη έκδοση.
• Έναν λογαριασμό στο volai και ένα κλειδί API από την πύλη (Ρυθμίσεις -> API και MCP), της μορφής vk_.... Αποθηκεύστε το στο n8n ως credential τύπου Header Auth (κεφαλίδα Authorization, τιμή Bearer vk_...), ώστε να μην αντιγράφετε το κλειδί σε κάθε κόμβο ξεχωριστά.
• Δικό σας τηλεφωνικό αριθμό με φωνητικό πράκτορα - τον δημιουργείτε στην πύλη ή μέσω /docs/agent. Χωρίς πράκτορα μπορείτε και πάλι να καλέσετε, συνδέοντας απευθείας δύο αριθμούς (η παραλλαγή from παρακάτω).

1Προσθέστε έναν κόμβο HTTP Request

Μέθοδος POST, URL https://volai.cz/v1/calls, πιστοποίηση μέσω του αποθηκευμένου credential, Body Content Type JSON. Το σώμα χρειάζεται τα to (ο αριθμός του πελάτη) και agentId (το ID του πράκτορα από την πύλη) - και τα δύο υποχρεωτικά, και ακριβώς ΕΝΑ από τα agentId/from/systemPrompt, ποτέ περισσότερα από ένα.

{
  "to": "={{ $json.phone }}",
  "agentId": "ag_kx91fa2b",
  "variables": {
    "customer_name": "={{ $json.name }}",
    "order_number": "={{ $json.order }}"
  },
  "ringingTimeoutSecs": 30
}

Οι τιμές της μορφής ={{...}} είναι εκφράσεις του n8n - το $json διαβάζει πεδία από τον προηγούμενο κόμβο του workflow (για παράδειγμα ένα webhook «νέα παραγγελία» ή μια γραμμή από πίνακα).

2Αντιστοιχίστε τα δεδομένα του workflow στο prompt του πράκτορα

Το variables είναι ένα αντικείμενο συμβολοσειράς προς συμβολοσειρά, που ο πράκτορας λαμβάνει ως δυναμικές μεταβλητές - στο system prompt του τις αναφέρετε ως {{customer_name}}. Όρια: το πολύ 20 κλειδιά, κλειδί έως 64 χαρακτήρες, τιμή έως 512 χαρακτήρες. Τα ονόματα attempt_id, caller_number και called_number είναι δεσμευμένα - τα συμπληρώνει το ίδιο το volai και οι τιμές με το ίδιο όνομα από το workflow σας θα απορριφθούν.

Το ringingTimeoutSecs (5 έως 60 δευτερόλεπτα, προεπιλογή 25) ορίζει για πόση ώρα θα χτυπά το τηλέφωνο, πριν μια κλήση που δεν απαντήθηκε λήξει με endReason: "no_answer". Μεγαλύτερο χρονικό όριο αυξάνει την πιθανότητα να προλάβει ο πελάτης να απαντήσει, αλλά κρατά και περισσότερη ώρα δεσμευμένη μια εξερχόμενη θέση.

3Διαβάστε την απάντηση και, αν θέλετε, περιμένετε το αποτέλεσμα

Η επιτυχής απάντηση έρχεται αμέσως, αλλά η κλήση τη στιγμή εκείνη μόλις ξεκινά - το status είναι initiated, όχι τελική κατάσταση:

{
  "id": "c_9d4e2b7f",
  "status": "initiated"
}

Αν θέλετε να περιμένετε το αποτέλεσμα στο ίδιο workflow αντί για ξεχωριστό webhook, προσθέστε αμέσως μετά τον κόμβο HTTP Request έναν δεύτερο, που καλεί το GET /v1/calls/{id} με την παράμετρο waitSecs (0 έως 45 δευτερόλεπτα) - ο διακομιστής απαντά όταν τελειώσει η κλήση ή όταν εξαντληθεί το χρονικό όριο, όποιο από τα δύο συμβεί πρώτο:

curl "https://volai.cz/v1/calls/c_9d4e2b7f?waitSecs=30" \
  -H "Authorization: Bearer vk_YOUR_KEY"

Το αποτέλεσμα πίσω: webhook προς το n8n

Για ένα workflow παραγωγής είναι πρακτικότερο να μην περιμένετε το αποτέλεσμα στην ίδια εκτέλεση, αλλά να το παραλαμβάνετε ξεχωριστά: προσθέστε στο n8n (άνετα και σε ένα νέο workflow) έναν κόμβο Webhook, αντιγράψτε το Production URL του και καταχωρίστε το μία φορά στο volai:

curl -X PUT https://volai.cz/v1/webhook \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-instance.app.n8n.cloud/webhook/volai-calls",
    "events": ["call.completed", "call.failed", "call.no_answer"]
  }'

Η απάντηση περιέχει ένα secret (της μορφής whsec_...) - αποθηκεύστε το, θα το χρειαστείτε για την επαλήθευση της υπογραφής κάθε εισερχόμενου αιτήματος. Το volai στέλνει την κεφαλίδα Volai-Signature της μορφής t=<unix>,v1=<hex> - τον πλήρη κώδικα επαλήθευσης σε TypeScript και Python θα βρείτε στο /docs/webhooky. Δεν μεταφέρεται αυτούσιος σε κόμβο Code του n8n: το HMAC υπολογίζεται πάνω στο ΑΚΑΤΕΡΓΑΣΤΟ σώμα του αιτήματος, οπότε στον κόμβο Webhook πρέπει να ενεργοποιήσετε την επιλογή Raw Body (χωρίς αυτήν το n8n παραδίδει ήδη αναλυμένο JSON και η υπογραφή δεν ταιριάζει ποτέ) και να εισάγετε το module crypto με require, όχι με import. Μην επεξεργάζεστε το σώμα πριν επαληθεύσετε την υπογραφή.

Παράδειγμα του τι φτάνει στο webhook όταν τελειώσει η κλήση:

{
  "event": "call.completed",
  "ts": 1756111640000,
  "data": {
    "id": "c_9d4e2b7f",
    "direction": "out",
    "from": "+420601234567",
    "to": "+420777123456",
    "status": "completed",
    "durationSecs": 90,
    "priceHal": 513,
    "answeredBy": "human",
    "endReason": "completed",
    "transcript": [
      { "role": "agent", "message": "Γεια σας, σας καλώ για την παραγγελία A-42." },
      { "role": "caller", "message": "Ναι, το γνωρίζω, ευχαριστώ για την υπενθύμιση." }
    ],
    "summary": "Ο πελάτης επιβεβαίωσε την παραλαβή της παραγγελίας A-42.",
    "data": {
      "order_confirmed": true
    }
  }
}

Το κλειδί data μέσα στο data είναι προαιρετικό και περιέχει ακριβώς τα πεδία που ορίσατε για τον πράκτορα στο dataFields του - το παράδειγμα παραπάνω (order_confirmed) είναι μόνο ενδεικτικό, τα δικά σας θα διαφέρουν. Ένας επόμενος κόμβος του n8n μπορεί στη συνέχεια να διακλαδίσει τη ροή με βάση αυτά τα πεδία, για παράδειγμα για να ενημερώσει το CRM ή να προγραμματίσει ξανά την κλήση.

Πώς καλείτε χωρίς πράκτορα;

Αν δεν χρειάζεστε φωνητικό πράκτορα, αλλά μόνο μια άμεση σύνδεση δύο αριθμών (για παράδειγμα ενός πωλητή με έναν πελάτη), στείλτε αντί για το agentId το πεδίο from:

{
  "to": "+420777123456",
  "from": "+420601234567"
}

Το volai καλεί πρώτα το from και μόλις το σηκώσει κάποιος, καλεί το to. Και τα δύο σκέλη της κλήσης χρεώνονται ξεχωριστά με 0,92 kr το λεπτό (χωρίς επιβάρυνση πράκτορα). Το from είναι ο αριθμός όπου απαντάτε ΕΣΕΙΣ - συνήθως το κινητό σας - και μπορεί να είναι οποιοσδήποτε τσεχικός ή σλοβακικός αριθμός, ακόμη και εκτός του λογαριασμού σας στο volai. Η πραγματική προϋπόθεση είναι άλλη: ο λογαριασμός σας πρέπει να έχει τουλάχιστον έναν ΔΙΚΟ σας αριθμό στο volai, επειδή από αυτόν χρεώνεται η κλήση και αυτός εμφανίζεται στην οθόνη και των δύο πλευρών (χωρίς αυτόν το volai επιστρέφει σφάλμα bridge_needs_number). Απλώς προσέξτε να μην είναι ο αριθμός στο volai δρομολογημένος σε πράκτορα ή σε SIP - το δίκτυο θα συνέδεε το πρώτο σκέλος με αυτόν και όχι με εσάς, και η κλήση δεν θα χτυπούσε ποτέ στο τηλέφωνό σας.

Πόσο κοστίζει μια τέτοια κλήση;

Μια εξερχόμενη κλήση μέσω πράκτορα χρεώνεται ως άθροισμα δύο τιμών: το εξερχόμενο λεπτό (0,92 kr) και η επιβάρυνση πράκτορα ΕΠΙΠΛΕΟΝ αυτού (2,50 kr), και οι δύο από τον τιμοκατάλογο που ισχύει από τις 2 Σεπτεμβρίου 2026. Μια κλήση ενάμισι λεπτού βγαίνει έτσι 5,13 kr:

Η χρέωση γίνεται ανά δευτερόλεπτο, όχι ανά ολόκληρο λεπτό - μια συντομότερη κλήση κοστίζει αναλογικά λιγότερο. Τον πλήρη τιμοκατάλογο (αριθμοί, πράκτορας, SMS) θα βρείτε στο /cenik.

Ασφαλής επανάληψη (Idempotency-Key)

Το n8n μπορεί να επαναλάβει αυτόματα έναν κόμβο σε περίπτωση σφάλματος (Retry On Fail) - χωρίς δικλίδα ασφαλείας αυτό θα σήμαινε δύο πραγματικές τηλεφωνικές κλήσεις προς τον ίδιο πελάτη. Προσθέστε μια κεφαλίδα Idempotency-Key με τιμή σταθερή για μία εκτέλεση του workflow (το n8n την προσφέρει ως {{ $execution.id }}, ή χρησιμοποιήστε το δικό σας ID παραγγελίας) - με το ίδιο κλειδί εντός 24 ωρών λαμβάνετε πίσω την απάντηση της πρώτης προσπάθειας και η κλήση δεν δημιουργείται δεύτερη φορά:

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reminder-order-A-42" \
  -d '{"to": "+420777123456", "agentId": "ag_kx91fa2b"}'

Τι κάνετε όταν το API επιστρέψει σφάλμα;

Αυτός ο πίνακας καλύπτει τις παραλλαγές με agentId και from - οι καταστάσεις που αφορούν μόνο τη δοκιμαστική κλήση χωρίς δικό σας αριθμό (systemPrompt) παραλείπονται σκόπιμα, είναι διαφορετική ροή.

Τι ακολουθεί

Μια πλήρης επισκόπηση του τι μπορείτε να κάνετε από το n8n (SMS, αριθμοί, λίστα «Να μην καλείται») υπάρχει στον οδηγό ενσωμάτωσης n8n. Η πλήρης αναφορά REST βρίσκεται στο /docs/api, και η πλήρης λίστα των συμβάντων webhook με την επαλήθευση της υπογραφής στο /docs/webhooky.

Τι ακολουθεί