IVR Intents

Conversational IVR intents replace traditional DTMF menus (“Press 1 for sales”) with natural-language utterance classification. The caller says what they want; the platform runs the utterance through a per-tenant set of intent buckets and routes the call to the matching ACD queue or AI agent. Each intent is a named bucket (sales, billing, support, …) with a natural-language description that the NLU classifier (Claude Haiku) compares against the live caller utterance. Base path: /api/v1/voice/ivr-intents Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scopes:

Endpoint	Scope	Roles allowed
`GET /`	`voice:read`	any
`POST /test`	`voice:read`	any
`POST /`, `PATCH /:id`, `DELETE /:id`	`voice:write`	`owner` / `admin` / `developer`

Intent object

Field	Type	Notes
`id`	string	`ivri_<32 hex>`. Stable across renames.
`name`	string	Lowercase alphanumeric + `-` / `_`, max 64 chars. Unique per tenant.
`description`	string	Natural-language prompt the classifier evaluates against the utterance (max 500 chars).
`target_queue_id`	string \| null	ACD queue id (1–128 chars, e.g. `que_sales_us`) to route matched calls to.
`target_agent_id`	string \| null	AI-agent id to route matched calls to. Mutually exclusive with `target_queue_id` at the app layer.
`active`	boolean	Inactive intents are excluded from classifier prompts. Default `true`.
`createdAt`	string	ISO-8601.
`updatedAt`	string	ISO-8601.

Both target_queue_id and target_agent_id may be null — that’s a valid pure-analytics intent (the call is classified for reporting but not routed).

DTMF-free speech menus

There are two ways to route on speech, and they compose:

Intent buckets (this page) — tenant-level descriptions the LLM classifier evaluates against the utterance. Best for open-ended routing across a whole tenant (“sales” vs “billing” vs “support”).
Speech Input node grammar — per-node speechIntents phrases edited on the node itself. Matching is deterministic phrase-versus-transcript string math (normalised exact match, word-order tolerance, partial phrase coverage) — no classifier round trip runs in the live gather. Best for a handful of expected utterances at one menu point.

The two layers are independent: a bucket description never feeds a node’s phrase match, and a node’s phrases are never sent to the classifier. For the node-level path, the IVR Builder exposes a keypad fallback toggle and a min-confidence gate on each Speech Input node. Turn the fallback off when you genuinely want speech-only — for example, a menu whose digits were never announced to callers, or an accessibility-led flow where the keypad creates confusion. Before the toggle existed, every speech node silently behaved as if keypad fallback were on; a legacy flow stays digit-enabled until an operator turns it off, and each intent can still carry one optional keypad digit while fallback is on (the digit always wins over speech, so a caller who can’t be understood still routes). The min-confidence gate (0–1) works the same way on both paths: a transcript recognised below the gate is a no-match. On the node path, the walk takes the node’s nomatch edge; set the confidenceThreshold node field alongside the tenant-level classifier threshold so a noisy line falls to a reprompt or an agent rather than a wrong branch. Editing the phrases, the toggle, the provider, and the gate is documented in the grammar-editor section of Build and ship your first IVR flow.

List intents

GET /api/v1/voice/ivr-intents

Returns every intent for the calling tenant, ordered by createdAt ASC. Includes inactive intents so the dashboard can render an enable/disable toggle. Defense-in-depth fallback (DEVOTEL-ORBIT-5H): If the tenant’s 287_ivr_intents migration has not yet applied (new tenant whose just-in-time migration runner is still executing, or a restored-from-backup tenant), this endpoint returns an empty array data: [] rather than a 503. Four Postgres provisioning-gap SQLSTATEs are swallowed: 42P01 (undefined_table), 42703 (undefined_column), 3F000 (invalid_schema_name) and 42704 (undefined_object); any other failure propagates as a normal error. Transient connection blips (pgbouncer drain / Cloud SQL pool pressure — CONNECTION_CLOSED, ECONNRESET, 53300) are retried first (DEVOTEL-ORBIT-6D) and only degrade to the empty-list fallback if they are genuinely a provisioning gap.

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/ivr-intents" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK

{
  "data": [
    {
      "id": "ivri_3f1c8b2a9d4e5f7a8b6c1d2e3f4a5b6c",
      "name": "sales",
      "description": "Caller wants to buy a product or ask about pricing.",
      "target_queue_id": "que_sales_us",
      "target_agent_id": null,
      "active": true,
      "createdAt": "2026-05-22T10:30:00Z",
      "updatedAt": "2026-05-22T10:30:00Z"
    }
  ],
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Create intent

POST /api/v1/voice/ivr-intents

Scope: voice:write. Role: owner / admin / developer.

string

required

Slug (lowercase alphanumeric + - / _), max 64 chars. Must be unique within the tenant.

string

required

Natural-language description fed to the classifier as the intent prompt. 1–500 chars.

string

ACD queue id (1–128 chars, e.g. que_billing_eu). Mutually exclusive with target_agent_id (enforced at the app layer; both may be omitted for analytics-only intents).

string

AI-agent id (agt_*).

boolean

default:"true"

Whether the classifier should evaluate this intent on live calls.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/ivr-intents" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing",
    "description": "Caller has a question about an invoice, charge, or payment.",
    "target_queue_id": "que_billing_eu",
    "active": true
  }'

201 Created — returns the created row. Errors

Status	`error.code`	Cause
`409`	`IVR_INTENT_NAME_CONFLICT`	An intent with this `name` already exists for the tenant.
`422`	`VALIDATION_ERROR`	`name` fails the regex, `description` is empty/too long, or both `target_*` keys are set.
`500`	`IVR_INTENT_CREATE_ERROR`	Unexpected DB error. Cause chain preserved in Sentry.

Update intent

PATCH /api/v1/voice/ivr-intents/{id}

Scope: voice:write. Role: owner / admin / developer. Partial update. Only fields present in the body overwrite the existing row. Send target_queue_id: null to clear a route.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/ivr-intents/ivri_3f1c8b2a9d4e5f7a8b6c1d2e3f4a5b6c" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

200 OK — returns the updated row. 404 NOT_FOUND — id not found in the tenant schema.

Delete intent

DELETE /api/v1/voice/ivr-intents/{id}

Scope: voice:write. Role: owner / admin / developer. Hard delete. The intent will no longer appear in any future classifier prompt or list response. Existing call routings already in flight are not affected (routing decisions are recorded on call_logs at decision time, not by FK reference).

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/ivr-intents/ivri_3f1c8b2a9d4e5f7a8b6c1d2e3f4a5b6c" \
  -H "X-API-Key: dv_live_sk_your_key_here"

204 No Content on success. 404 NOT_FOUND — id not found.

Test classification

POST /api/v1/voice/ivr-intents/test

Ad-hoc classifier preview. Runs the supplied utterance against the tenant’s active intents and returns the matched intent (if any) plus the classifier’s confidence. Use this from the dashboard’s IVR studio to validate a new intent description without placing a real call.

string

required

Caller utterance to classify. Max 500 chars (utterances beyond this are truncated by the classifier).

string

default:"en"

IETF BCP-47 language tag (en, en-US, tr, es-419, …). Influences classifier prompt locale.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/ivr-intents/test" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "utterance": "I would like to ask about my last invoice",
    "language": "en"
  }'

200 OK

{
  "data": {
    "matched_intent_id": "billing",
    "confidence": 0.93,
    "reasoning": "Utterance explicitly mentions 'invoice', a direct billing concept."
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

On a match, fallback_reason is absent. When no active intent matches above the confidence threshold (0.7), matched_intent_id is null and fallback_reason carries one of "low_confidence" (a candidate scored below threshold), "no_match" (no plausible mapping), or "ambiguous" (two or more intents tied). There is no boolean fallback field. An empty active intent set (no rows or all active: false) is a valid state — the classifier still runs and returns fallback_reason: "no_match":

{
  "data": {
    "matched_intent_id": null,
    "confidence": 0.41,
    "reasoning": "No active intent describes a request to reset a password.",
    "fallback_reason": "no_match"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Performance: P95 < 1s (Haiku call ~250ms + intent fetch + audit log).

Error model

All errors follow the platform envelope:

{
  "error": {
    "code": "IVR_INTENT_NAME_CONFLICT",
    "message": "An intent with name 'sales' already exists.",
    "status": 409
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-05-24T12:00:00Z"
  }
}

Branch on error.code, not error.message (messages may be localised).

Observability

Every state change (create, update, delete, test) writes a structured audit log with action=voice.ivr_intent.<verb> and the resource id, available via the Audit Logs API.

Speech-gather grammar (DTMF-free routing, NLU-tuned)

The tenant intent buckets above are one way to route by speech — a classifier decision per utterance. For menus that need a deterministic, no-LLM match and true DTMF-free operation, the flow’s Speech node (speechInput) also accepts an inline grammar of caller phrases: matching is exact phrase matching against the transcript, not a model call, so the same phrase routes the same way on every call. Declare the grammar on the Speech node’s data under speechIntents; each intent’s name is the branch handle you wire out of the node:

{
  "id": "ask",
  "type": "speechInput",
  "data": {
    "prompt": "How can we help today?",
    "speechIntents": [
      { "name": "sales", "phrases": ["sales", "buy a product"], "dtmfKey": "1" },
      { "name": "billing", "phrases": ["billing", "invoice"], "dtmfKey": "2" },
      { "name": "agent", "phrases": ["agent", "human"], "dtmfKey": "0" }
    ]
  }
}

Field	Notes
`speechIntents[].name`	Branch handle — wire an edge with `sourceHandle` set to this name from the Speech node. Max 32 intents per node.
`speechIntents[].phrases`	Caller sayings for this intent (max 16 per intent, 100 chars each). Phrases are boosted as recognition hints, so speak your callers’ vocabulary. Matching is case- and punctuation-insensitive; a multi-word phrase matches when it appears as whole words inside the utterance, and the longest matching phrase wins ties.
`speechIntents[].dtmfKey`	Optional single digit (`0`–`9`, `*`, `#`) the caller can press as a fallback for the same branch.
`dtmfFallbackEnabled`	Default `true` — a wired `dtmfKey` stays available for callers who prefer the keypad or are in a loud environment. Set `false` for a strictly DTMF-free gate.
`confidenceThreshold`	`0`–`1`. Transcripts below the threshold take the `nomatch` branch instead of matching a phrase.

Edge precedence at the Speech node: a pressed digit routing to a wired dtmfKey wins; otherwise the transcript is matched against the phrases; no match (or confidence below the threshold) takes the nomatch branch, then default; a silent caller retries within the gather’s retry budget and then takes the timeout branch, then default. Pick the inline grammar for short, closed menus (“press or say”) and the tenant intent buckets for open-ended requests — the two can share one flow (guide). Turn on detectLanguage on the Speech node to pin a multilingual caller’s language for the rest of the call.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

IVR intents: NLU routing for inbound voice callers

IVR Intents

Intent object

DTMF-free speech menus

List intents

Create intent

Update intent

Delete intent

Test classification

Error model

Observability

Speech-gather grammar (DTMF-free routing, NLU-tuned)

See also

​IVR Intents

​Intent object

​DTMF-free speech menus

​List intents

​Create intent

​Update intent

​Delete intent

​Test classification

​Error model

​Observability

​Speech-gather grammar (DTMF-free routing, NLU-tuned)

​See also

IVR Intents

Intent object

DTMF-free speech menus

List intents

Create intent

Update intent

Delete intent

Test classification

Error model

Observability

Speech-gather grammar (DTMF-free routing, NLU-tuned)

See also