> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ihren ersten IVR-Flow erstellen und ausliefern

> Erstellen Sie einen IVR-Flow in der Orbit-DSL oder im visuellen Builder, validieren Sie ihn vor dem Publish, simulieren Sie einen skripteten Anrufer, binden Sie ihn an eine DID, übergeben Sie an einen Menschen, wenn nötig, und rollen Sie über die Versionshistorie zurück.

## Sprachhinweis

Diese deutsche Variante ist eine gekürzte Übersetzung: Die Abschnitte „3. Validate before you publish", „7. The visual builder — the same graph, without the JSON" und „8. Version and roll back" existieren nur in der englischen Fassung: [/en/guides/build-ivr-flow](https://docs.orbit.devotel.io/en/guides/build-ivr-flow). Code-Blöcke, Endpoint-Pfade, API-Feldnamen und Fehlercodes bleiben englisch.

# Ihren ersten IVR-Flow erstellen und ausliefern

Ein IVR-Flow ist ein `{ nodes, edges }`-Graph, den Sie an ein einziges Set von Endpoints senden. Beim Anlegen und bei jeder Änderung läuft der Graph-Validator vor der Persistenz, Publish kopiert den Entwurf in den Live-Snapshot, und ein Simulator lässt Sie einen skripteten Anrufer durch den Graphen treiben, bevor je eine DID klingelt.

Wir bauen einen kleinen Flow im Airline-Stil: Anrufer begrüßen, Booking- und Refund-Intents an eine ACD-Queue routen und auf Voicemail zurückfallen, wenn nichts passt.

## 1. IVR-Grundbausteine

Flow-Definitionen werden von der Voice-Runtime gegen die Jambonz-Verb-Pipeline ausgeführt. Der Graph-Validator — der bei jedem Create und Update läuft — prüft genau einen Entry-Knoten (Typ `ivrStart`), mindestens einen Terminal-Knoten (hangup, transfer, voicemail, ringGroup, dialByName, offerCallback, offerSmsCallback, scheduleCallback), dass jede Edge vorhandene Knoten-IDs referenziert, dass jeder Knoten vom Entry aus erreichbar ist und dass kein erreichbarer Knoten in einem Zyklus ohne Weg zu einem Terminal gefangen ist. Die Bausteine spiegeln die programmierbare Voice-DSL — siehe [Programmable Voice DSL reference](https://docs.orbit.devotel.io/reference/programmable-voice-dsl.md).

Sprachintents ergänzen DTMF-Menüs: Die Knotentypen `speechInput` und `dialByName` gleichen frei formulierte Äußerungen gegen `speechIntents` je Knoten ab. Die [IVR-Intents-Konzeptseite](https://docs.orbit.devotel.io/voice/ivr-intents.md) erklärt diese Buckets.

> [!WARNING]
>
> Outbound-Termination läuft ausschließlich über Devotel. Ein `transfer`-Knoten mit roher SIP-URI als Ziel wird vom Validator mit `transfer_external_sip` abgelehnt — verwenden Sie eine E.164-Rufnummer oder eine On-Net-Nebenstelle.

## 2. Flow erstellen

Senden Sie die Definition an `POST /api/v1/voice/ivr-flows`. Der Body akzeptiert `name`, den `definition`-Graphen und ein optionales `active`-Flag. Der Validator läuft vor der Persistenz, ein fehlerhafter Graph liefert `422 IVR_FLOW_GRAPH_INVALID` und nichts wird gespeichert.

```bash cURL theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/ivr-flows" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Airline inbound router",
    "definition": {
      "nodes": [
        { "id": "start", "type": "ivrStart" },
        { "id": "welcome", "type": "playAudio", "data": { "ttsText": "Welcome to Horizon Airlines." } },
        {
          "id": "menu",
          "type": "menu",
          "data": {
            "menuOptions": [
              { "key": "1", "label": "Bookings" },
              { "key": "2", "label": "Support agent" }
            ]
          }
        },
        { "id": "bookings", "type": "queue", "data": { "label": "Bookings queue" } },
        { "id": "support", "type": "queue", "data": { "label": "Support queue" } },
        { "id": "fallback", "type": "voicemail", "data": { "label": "Voicemail fallback" } },
        { "id": "end", "type": "hangup" }
      ],
      "edges": [
        { "source": "start", "target": "welcome" },
        { "source": "welcome", "target": "menu" },
        { "source": "menu", "target": "bookings", "sourceHandle": "1" },
        { "source": "menu", "target": "support", "sourceHandle": "2" },
        { "source": "menu", "target": "fallback", "sourceHandle": "default" },
        { "source": "fallback", "target": "end" }
      ]
    }
  }'
```

Die Antwort trägt die `id` des neuen Flows (eine `ivr_*`-Kennung) — bewahren Sie sie auf; jeder spätere Schritt nutzt sie.

Menü-Knoten verzweigen mit einer Edge pro DTMF-Taste in `menuOptions`; der Validator lehnt leere, doppelte oder Nicht-DTMF-Keys mit `menu_empty_key`, `menu_duplicate_key` oder `menu_invalid_key` ab.

## 4. Mit dem Simulator testen

Treiben Sie einen skripteten Anrufer durch den Graphen, bevor Sie den Flow an eine DID binden. `POST /api/v1/voice/ivr-flows/:id/simulate` nimmt `turns` entgegen (je mit `digits`, `speech` und/oder `intent`) und liefert pro Schritt die besuchte Knoten-ID, den gewählten Handle, die emittierten Verb-Kategorien und den `termination_reason`.

```bash cURL theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/ivr-flows/ivr_01h.../simulate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "turns": [{ "digits": "1" }],
    "max_steps": 50
  }'
```

**200 OK** — erwarten Sie `reached_nodes: ["start","welcome","menu","bookings"]`, `emitted_verbs` mit `gather` am Menü und `enqueue` an der Queue sowie `termination_reason: "queue_answered"`. Eine rote Simulation fängt Routing-Regressionen, bevor Sie eine Live-Minute verbrennen.

Nützliche Optionen: `source: "published"` geht den Live-Snapshot ab, `source: "draft"` (Standard) den ungespeicherten Entwurf.

## 5. Flow an eine DID binden

Die Inbound-Routing-Konfiguration jeder DID trägt die Flow-Referenz. Setzen Sie `type: "ivr"` mit `config.flowId`:

```bash cURL theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/+14155550123/routing" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "type": "ivr", "config": { "flowId": "ivr_01h..." } }'
```

Das Voice-Gateway löst den Flow bei jedem eingehenden Anruf auf — die Bindung wirkt sofort. Publishen Sie vor dem Binden, dann trifft der erste Anrufer den Live-Snapshot.

## 6. An einen Agenten übergeben

Routen Sie den `support`-Zweig über einen `queue`-Knoten an eine ACD-Queue, damit ein Teammitglied den Anruf im Dashboard übernimmt, oder richten Sie den ganzen Flow auf einen [AI-Agenten](https://docs.orbit.devotel.io/voice/ai-agent-handback.md) aus, dessen Handback-Endpoint das Gespräch behält und nach der menschlichen Klärung zurück zum AI eskaliert.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.