Skip to main content

​
Note de langue

Cette version française est une traduction abrégée : les sections « 3. Validate before you publish », « 7. The visual builder — the same graph, without the JSON » et « 8. Version and roll back » n’existent qu’en anglais : /en/guides/build-ivr-flow. Les blocs de code, chemins d’endpoints, noms de champs API et codes d’erreur restent en anglais.

​
Construire et publier votre premier flux IVR

Un flux IVR est un graphe { nodes, edges } que vous soumettez à un unique jeu d’endpoints. À la création comme à chaque modification, le validateur de graphe s’exécute avant la persistance ; la publication copie le brouillon dans le snapshot live ; et un simulateur vous fait piloter un appelant scripté dans le graphe avant qu’un DID ne sonne. Nous construisons un petit flux de type compagnie aérienne : accueillir l’appelant, router les intents réservation ou remboursement vers une file ACD, et retomber sur la messagerie vocale si rien ne correspond.

​
1. Les primitives IVR

Les définitions de flux sont exécutées par le runtime voice contre le pipeline de verbes Jambonz. Le validateur de graphe — qui tourne à chaque create et update — vérifie exactement un nœud d’entrée (type ivrStart), au moins un nœud terminal (hangup, transfer, voicemail, ringGroup, dialByName, offerCallback, offerSmsCallback, scheduleCallback), que chaque edge référence des ids de nœuds existants, que tout nœud est atteignable depuis l’entrée et qu’aucun nœud atteignable n’est piégé dans un cycle sans route vers un terminal. Les briques reflètent la DSL voice programmable — voir la Programmable Voice DSL reference. Les intents vocaux complètent les menus DTMF : les types de nœud speechInput et dialByName comparent un énoncé libre aux speechIntents par nœud. La page concept IVR intents explique ces buckets.
La terminaison sortante est exclusivement Devotel. Un nœud transfer dont la destination est une SIP URI brute est rejeté par le validateur avec transfer_external_sip — utilisez un numéro E.164 ou un poste interne.

​
2. Construire le flux

Envoyez la définition à POST /api/v1/voice/ivr-flows. Le corps accepte name, le graphe definition et un drapeau active optionnel. Le validateur tourne avant la persistance : un graphe malformé rend 422 IVR_FLOW_GRAPH_INVALID et rien n’est stocké.
cURL
La réponse porte l’id du nouveau flux (un identifiant ivr_*) — gardez-le ; chaque étape suivante l’utilise. Les nœuds menu branchent une edge par touche DTMF présente dans menuOptions ; le validateur rejette les clés vides, dupliquées ou non-DTMF avec menu_empty_key, menu_duplicate_key ou menu_invalid_key.

​
4. Tester avec le simulateur

Pilotez un appelant scripté dans le graphe avant de l’attacher à un DID. POST /api/v1/voice/ivr-flows/:id/simulate consomme des turns (chacun avec digits, speech et/ou intent) et rend, pour chaque étape, l’id du nœud visité, le handle pris, les catégories de verbes émises et le termination_reason.
cURL
200 OK — attendez reached_nodes: ["start","welcome","menu","bookings"], emitted_verbs incluant gather au menu et enqueue à la file, et termination_reason: "queue_answered". Une simulation rouge attrape les régressions de routage avant de brûler une minute live. Options utiles : source: "published" parcourt le snapshot live, source: "draft" (défaut) le brouillon non sauvegardé.

​
5. Attacher le flux à un DID

La configuration de routage entrant de chaque DID porte la référence du flux. Posez type: "ivr" avec config.flowId :
cURL
La passerelle voice résout le flux à chaque appel entrant — l’attachement est immédiat. Publiez avant d’attacher, et le premier appelant touchera le snapshot live.

​
6. Transférer à un agent

Routez la branche support vers une file ACD via un nœud queue pour qu’un membre de l’équipe prenne l’appel depuis le dashboard, ou dirigez tout le flux vers un agent IA dont l’endpoint de handback conserve la conversation et rend la main à l’IA une fois l’exception résolue par un humain.