Ξεκινώντας

Δημιουργήστε τον πρώτο σας βοηθό

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

Οι διαδρομές, τα ονόματα πεδίων, οι τιμές enum, οι κεφαλίδες και οι κωδικοί σφαλμάτων στα παραδείγματα είναι οι πραγματικοί, ελεγμένοι με την προδιαγραφή του API κατά τη δημιουργία της σελίδας. Τα αναγνωριστικά, ποσά και ονόματα είναι ενδεικτικά. Τα `$WETALK_API_KEY` και `$AGENT` είναι μεταβλητές shell που ορίζετε εσείς.

Πριν ξεκινήσετε

Χρειάζεστε ένα έγγραφο και έναν αριθμό. Το έγγραφο εξαρτάται από το πρότυπο: μενού για διανομή και παραγγελίες, λίστα ερωτήσεων για έρευνα. Ο αριθμός είναι είτε δικός σας, μέσω SIP trunk του παρόχου σας που συνδέετε μόνοι σας στους Αριθμούς & SIP της κονσόλας («Σύνδεση trunk»), είτε αριθμός που δημιουργεί το WeTalk: ζητήστε τον με `POST /v1/numbers/requests` (ή «Αίτημα αριθμού» στην ίδια σελίδα) και τον συνδέουμε με τον βοηθό σας.

Χρειάζεστε επίσης κλειδί API και το πρώτο δεν μπορεί να προέλθει από το API — κάθε αίτημα πρέπει να πιστοποιείται με κάτι. Δημιουργήστε το στην κονσόλα, στις Ρυθμίσεις, στην ενότητα Για προγραμματιστές. Εμφανίζεται ακριβώς μία φορά: διατηρείται μόνο σύνοψη SHA-256, επομένως δεν υπάρχει διαδρομή που να το εμφανίζει ξανά. Αν το χάσετε, πρέπει να το ανακαλέσετε και να δημιουργήσετε άλλο.

Ένα κλειδί ελέγχεται βάσει δικαιωμάτων και ποτέ βάσει ρόλου. Δώστε του το ελάχιστο σύνολο που χρειάζεται.
Τα εννέα δικαιώματα είναι agent:read, agent:write, conversation:read, recording:read, campaign:write, credit:spend, order:read, order:write και conversation:dial.
Το rate_limit_per_minute έχει προεπιλογή 60 και μπορεί να οριστεί από 1 έως 600.

Το πρώτο σας αίτημα

curl https://api.wetalk.io/v1/agents \
  -H "Authorization: Bearer $WETALK_API_KEY"

Κάθε απάντηση έχει κοινό περίβλημα

{
  "data": [
    {
      "voice_agent_id": "0199f1c2-6b40-7a11-9d3e-6c1b5f0a2e77",
      "name": "Roma orders",
      "slug": "roma-orders",
      "state": "live"
    }
  ]
}

Επιλέξτε πρότυπο

Το πρότυπο γνωρίζει ήδη τη δουλειά του: πώς διαβάζεται ένα μενού και επιβεβαιώνεται διεύθυνση ή πώς γίνεται μία ερώτηση κάθε φορά και σταματά όταν κάποιος λέει όχι. Ο κατάλογος είναι δεδομένα και το `code` είναι αυτό που δίνετε κατά τη δημιουργία βοηθού. Δύο πρότυπα είναι διαθέσιμα στην πρώτη κυκλοφορία — `delivery` και `survey`.

Ο ίδιος κατάλογος παρέχει γλώσσες και φωνές. Μια φωνή πρέπει να μιλά κάθε γλώσσα που ζητάτε και κάθε γλωσσικό πακέτο πρέπει να είναι πλήρες: ένα ελλιπές πακέτο κάνει τη γλώσσα μη διαθέσιμη και δεν υπάρχει πουθενά αντικατάσταση από αγγλικά. Γι’ αυτό ελέγχεται πριν αρχίσει η δημιουργία, αντί να ανακαλυφθεί σε μια κλήση.

Ο κατάλογος

curl https://api.wetalk.io/v1/templates \
  -H "Authorization: Bearer $WETALK_API_KEY"

curl https://api.wetalk.io/v1/languages \
  -H "Authorization: Bearer $WETALK_API_KEY"

curl https://api.wetalk.io/v1/voices \
  -H "Authorization: Bearer $WETALK_API_KEY"

Δημιουργήστε τον βοηθό

Η καταχώριση δεν ολοκληρώνει τη δημιουργία. Ένα αίτημα γράφει τον VoiceAgent, την πρώτη έκδοση, την εργασία δημιουργίας και τα βήματά της και βάζει τη δημιουργία στην ουρά — όλα σε μία συναλλαγή βάσης — και μετά απαντά. Το εργοστάσιο είναι μηχανή καταστάσεων που εκτελείται από worker, επομένως η απάντηση επιστρέφει σε χιλιοστά του δευτερολέπτου και η εργασία συνεχίζεται στο παρασκήνιο.

Στείλτε `Idempotency-Key` σε αυτό και σε κάθε POST που ξοδεύει χρήματα ή ξεκινά κάτι. Αποθηκεύεται για 24 ώρες ανά λογαριασμό, διαδρομή και κλειδί. Επανάληψη του ίδιου κλειδιού με διαφορετικό σώμα απορρίπτεται αντί να απαντηθεί από την αποθήκη. Αυτή είναι η επιθυμητή αποτυχία: σημαίνει σφάλμα στον κώδικά σας, όχι διπλό βοηθό.

POST /v1/agents

curl https://api.wetalk.io/v1/agents \
  -X POST \
  -H "Authorization: Bearer $WETALK_API_KEY"
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0199f1c2-6b40-7a11-9d3e-6c1b5f0a2e77" \
  -d '{
    "agent_template_code": "delivery",
    "name": "Roma orders",
    "language_code": ["el", "en"],
    "voice_id": "0199f1c2-7000-7000-8000-00000000000a",
    "greeting": "Roma Pizzeria, good evening. What can I get for you?",
    "number_choice": "new_number",
    "medium": ["voice"],
    "channel_unit_count": 4,
    "field_value": {
      "delivery_fee": "2.50",
      "opening_hours": "Tue to Sun, 17:00 to 23:30"
    }
  }'

201 Created

{
  "data": {
    "voice_agent_id": "0199f1c2-6b40-7a11-9d3e-6c1b5f0a2e77",
    "agent_version_id": "0199f1c2-6b41-7c02-b8aa-1d9f4e2c7b10",
    "build_job_id": "0199f1c2-6b41-7c02-b8aa-2f0e5a3d8c21",
    "slug": "roma-orders"
  }
}

Παρακολουθήστε τη δημιουργία

Η εργασία δημιουργίας εκπέμπει ροή. Ανοίξτε ροή συμβάντων από τον διακομιστή με το αναγνωριστικό που λάβατε και θα δείτε τα ίδια βήματα με την κονσόλα. Χρησιμοποιείται SSE αντί WebSocket επειδή η κίνηση είναι μονόδρομη, περνά από proxies και το `Last-Event-ID` επιτρέπει συνέχιση μετά από διακοπή σύνδεσης.

Μια γραμμή σχολίου φτάνει κάθε δεκαπέντε δευτερόλεπτα, ώστε ένας αδρανής proxy να μην κλείσει τη ροή. Αν προτιμάτε περιοδικό έλεγχο, διαβάστε τον βοηθό· η δημιουργία δεν απαιτεί τη ροή.

build.step και build.progress κατά την εκτέλεση.
build.succeeded όταν η έκδοση είναι έτοιμη για δημοσίευση.
build.failed με την αιτία, η οποία εμφανίζεται και στην έκδοση.

GET /v1/stream/build/{build_job_id}

curl -N https://api.wetalk.io/v1/stream/build/0199f1c2-6b41-7c02-b8aa-2f0e5a3d8c21 \
  -H "Authorization: Bearer $WETALK_API_KEY"
  -H "Accept: text/event-stream"

Δημοσιεύστε και κατευθύνετε την κίνηση σε αυτόν

Μια έτοιμη έκδοση δεν είναι ενεργή. Η δημοσίευση λαμβάνει τον τελευταίο αριθμό ακολουθίας που διαβάσατε και απορρίπτεται με `409 live_version_seq_stale` αν κάποιος δημοσίευσε όσο αποφασίζατε — δεν αντικαθιστά σιωπηλά την απόφασή του. Η επαναφορά είναι η ίδια λειτουργία σε παλαιότερη έκδοση και έχει την ίδια εγγύηση: οι τρέχουσες συνομιλίες παραμένουν στην έκδοση με την οποία ξεκίνησαν και μόνο οι νέες χρησιμοποιούν τη νέα ενεργή έκδοση.

Μετά συνδέστε τη γραμμή. Ένας αριθμός στο δικό σας SIP trunk συνδέεται με τον βοηθό στην καρτέλα Κανάλια. Ένας αριθμός που δημιούργησε το WeTalk δεσμεύεται στον βοηθό κατά τη σύνδεση και δεν χρειάζεται άλλη ενέργεια. Οι Αριθμοί & SIP καλύπτουν και τα δύο.

POST /v1/agents/{voice_agent_id}/versions/{agent_version_id}/publish

curl https://api.wetalk.io/v1/agents/$AGENT/versions/$VERSION/publish \
  -X POST \
  -H "Authorization: Bearer $WETALK_API_KEY"
  -H "Content-Type: application/json" \
  -d '{ "expected_live_version_seq": 0 }'

Όταν κάτι απορρίπτεται

Κάθε αποτυχημένη απάντηση έχει το ίδιο περίβλημα και το `code` είναι το μόνο πεδίο στο οποίο πρέπει να βασίζετε διακλαδώσεις. Το ανθρώπινο `message` μπορεί να αλλάξει διατύπωση μεταξύ κυκλοφοριών· ο κωδικός ποτέ, επειδή τον χρησιμοποιεί ο καταναλωτής. Το `field` κατονομάζει την προβληματική είσοδο όπου υπάρχει και το `request_id` είναι αυτό που αναφέρετε όταν μας ρωτάτε τι συνέβη.

Η κοινή μορφή σφάλματος

{
  "error": {
    "code": "language_pack_incomplete",
    "message": "That language is not available yet.",
    "field": "language_code",
    "request_id": "0199f1c2-6b42-7d14-9e55-3a1b6c4d9e32"
  }
}