Get an IVR (user, pbx)

Returns the single IVR menu identified by the path parameter.

Auth. Either a user bearer token (abilities ['*']) or an Integrations API key carrying the ivrs scope. That same ivrs scope also covers /ivr-steps: there is deliberately no separate ivr-steps scope. A key without ivrs responds 403.

Tenancy. The lookup is scoped to the PBX resolved from the token, so an id belonging to ANOTHER PBX responds 404 exactly like an id that does not exist at all. The two cases are deliberately indistinguishable: the API never confirms the existence of another tenant's resource.

Shape. Read-only projection: the legacy voip_ivr_id platform mapping is not exposed. The menu's buttons are opt-in through ?include=steps; the steps key is absent from the payload otherwise.

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme: bearer
Bearer format: Bearer <token>

HTTP: IntegrationApiKey

API key created on the Cockpit Integrations page (an "API key" integration). It is a bearer token owned by the customer's PBX and limited to the scopes selected when the key was created (e.g. phone-numbers, push-configuration).

Send it in the Authorization header:

Authorization: Bearer <api_key>

Manage keys (create / reveal / revoke) from Integrations → New integration → API key.

HTTP Authorization Scheme: bearer

id path · string · uuid *

Identifier of the IVR menu, which must belong to the caller's own PBX.

include query · string

Relation to embed. The only allowed value is `steps`, which adds the menu's keypad buttons under `steps`. Anything else responds 422.

enum: steps

accept header · string

example: application/json

Responses

Response schema

allOf

id*string · uuid

Unique identifier of the IVR menu.

read-only

example: 550e8400-e29b-41d4-a716-446655440000

pbx_id*string · uuid

Identifier of the Pbx (tenant) that owns this IVR. Always the caller's own PBX: the endpoint never returns another tenant's menus.

read-only

example: 550e8400-e29b-41d4-a716-446655440001

name*string

Human-readable label for the IVR menu, used to identify it in call-flow configuration.

length: 0–128

example: Customer Support Menu

commentstring | null

Optional free-text note describing the purpose of this IVR. Null when unset.

length: 0–255

example: After-hours routing for the support line

announcement_id*string · uuid

Identifier of the sound file (type `announcement`) played to the caller on entering this menu.

example: 550e8400-e29b-41d4-a716-446655440002

announcement_languagestring | null

Language override for this IVR's announcement. Null (Auto) plays the language variant detected or inherited earlier in the call. An ISO-639-1 code forces that specific variant.

enum: en de fr lb es it pt nl pl ru tr sv da no fi cs sk el hu ro bg hr uk ar he hi ja ko zh id ms th vi null

example: fr

default_actionstring | null

What happens when the caller presses nothing before the menu times out. `hangup` ends the call, `repeat` replays the announcement, `default_step` follows the step whose `option` is `default`. Null when unset.

enum: hangup repeat default_step null

example: repeat

enable_smart_ivr*boolean

Whether the AI voice assistant (Smart IVR) answers this menu instead of the classic keypad prompt.

example:

created_at*string | null · date-time

Timestamp when the IVR was created.

read-only

example: 2024-03-01T08:29:07.000000Z

updated_at*string | null · date-time

Timestamp when the IVR was last updated.

read-only

example: 2024-03-01T08:29:07.000000Z

stepsarray<object>

The menu's keypad buttons. Present ONLY when the request carries `?include=steps`; the key is absent from the payload otherwise. Empty array when the menu has no buttons configured yet.

Each item — A single keypad option inside an IVR (Interactive Voice Response) menu. When a caller reaches the parent IVR, the digit they press is matched against `option` (or the `default` step when no digit is pressed before the timeout) and the call is routed to the resource identified by the polymorphic `target_type` plus `target_id` pair. Legal routing targets are call flows and other IVRs, allowing nested menus. The legacy `voip_ivr_btn_id` platform mapping and the soft-delete timestamp are never serialized by the public API.

id*string · uuid

Unique identifier of the IVR step.

read-only

example: 550e8400-e29b-41d4-a716-446655440000

pbx_id*string · uuid

Identifier of the Pbx (tenant) that owns this IVR step. Always the caller's own PBX: the endpoint never returns another tenant's steps.

read-only

example: 550e8400-e29b-41d4-a716-446655440001

ivr_id*string · uuid

Identifier of the parent IVR menu this step belongs to.

example: 550e8400-e29b-41d4-a716-446655440002

target_type*string

Polymorphic morph class of the routing target, stored as the fully qualified PHP class name. Together with `target_id` it identifies where the call is routed when this option is selected. Valid targets are call flows and IVRs.

enum: App\Models\CallFlow App\Models\Ivr

example: App\Models\CallFlow

target_id*string · uuid

Identifier of the routing target resource. The kind of resource is given by `target_type` (a CallFlow or an Ivr).

example: 550e8400-e29b-41d4-a716-446655440003

namestring | null

Optional human-readable label for this step, shown in the admin UI to describe where the option routes. Null when no label has been set.

example: Sales department

option*string | null

The DTMF key that selects this step. The special value `default` is the fallback applied when the caller does not press any key before the IVR timeout.

enum: default 0 1 2 3 4 5 6 7 8 9 * # null

example: 1

languagestring | null

Announcement language override applied from this step onward. `null` (Auto) means the language detected/inherited earlier in the call is kept. ISO-639-1 code otherwise.

enum: en de fr lb es it pt nl pl ru tr sv da no fi cs sk el hu ro bg hr uk ar he hi ja ko zh id ms th vi null

example: fr

created_at*string | null · date-time

Timestamp when the IVR step was created.

read-only

example: 2024-03-01T08:29:07.000000Z

updated_at*string | null · date-time

Timestamp when the IVR step was last updated.

read-only

example: 2024-03-01T08:29:07.000000Z

ivrobject

The parent IVR menu. Present ONLY when the request carries `?include=ivr`; the key is absent from the payload otherwise. Serialised without its own `steps`, so the two resources cannot recurse into each other.

Authorization Token Missing. This error is returned when the authorization token is missing.

Response schema

errorstring

Error message

example: Authorization Token is missing

Forbidden. The bearer token authenticated successfully but does not carry the scope this endpoint requires. Re-create the Integrations API key with the missing scope selected (Integrations > New integration > API key).

Response schema

messagestring

Not Found. No IVR with this id exists inside the caller's own PBX. The same 404 is returned when the id is unknown and when it belongs to another PBX: the API does not disclose which.

Response schema

messagestring

Unprocessable Query. Two different problems share this status on the read endpoints: * a query parameter has the wrong TYPE (`page` / `per_page` not an integer, `filter` not an array, `sort` not a string). The body carries an `errors` map keyed by parameter name. * a `filter[...]` key, a `sort` field or an `include` relation that the endpoint does not allow was requested. The body carries a single `message` naming the allowed values. Nothing is returned and no partial result is produced: correct the query string and retry.

Response schema

messagestring

Present when an unsupported filter, sort or include was requested. The values it enumerates are the allow-list of the endpoint that returned it, so they differ per endpoint; the examples below show the `/ivrs` allow-list.

errorsobject

Present when a query parameter has the wrong type. Keyed by parameter name.

Free-form object

Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.

Response schema

messagestring

exceptionstring

Only present in non-production environments.

filestring

Only present in non-production environments.

lineinteger

Only present in non-production environments.

get https://cockpit.voxbi.com/api/v1/ivrs/{id}

Base URL

Request sample

curl -X GET 'https://cockpit.voxbi.com/api/v1/ivrs/{id}' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cockpit.voxbi.com/api/v1/ivrs/{id}', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

import requests

response = requests.get('https://cockpit.voxbi.com/api/v1/ivrs/{id}',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/ivrs/{id}', false, $context);
$data = json_decode($response, true);
print_r($data);

{ … }

"id": "550e8400-e29b-41d4-a716-446655440000",

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"name": "Customer Support Menu",

"comment": "After-hours routing for the support line",

"announcement_id": "550e8400-e29b-41d4-a716-446655440002",

"announcement_language": null,

"default_action": "repeat",

"enable_smart_ivr": false,

"created_at": "2024-03-01T08:29:07.000000Z",

"updated_at": "2024-03-01T08:29:07.000000Z",

"steps": [ … ]

{ … }

"id": "550e8400-e29b-41d4-a716-446655440010",

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"ivr_id": "550e8400-e29b-41d4-a716-446655440000",

"name": "Sales department",

"option": "1",

"language": null,

"target_type": "App\Models\CallFlow",

"target_id": "550e8400-e29b-41d4-a716-446655440003",

"created_at": "2024-03-01T08:29:07.000000Z",

"updated_at": "2024-03-01T08:29:07.000000Z"

}

]

}

Host string

example: cockpit.voxbi.com

Date string

example: Mon, 16 Oct 2023 14:08:48 GMT

Connection string

example: close

Cache-Control string

example: no-cache, private

Content-Type string

example: application/json

X-RateLimit-Limit integer

example: 60

X-RateLimit-Remaining integer

example: 59

Vary string

example: Origin

{ … }

"error": "Authorization Token is missing"

}

Cache-Control string

example: private, must-revalidate

Connection string

example: keep-alive

Content-Type string

example: application/json

Vary string

example: Origin

X-RateLimit-Limit integer

Max requests allowed in the current rate-limit window.

example: 60

X-RateLimit-Remaining integer

Requests remaining in the current rate-limit window.

example: 57

{ … }

"message": "Invalid ability provided."

}

Content-Type string

example: application/json

{ … }

"message": "No query results for model [App\Models\Ivr] 550e8400-e29b-41d4-a716-446655440099"

}

Content-Type string

example: application/json

{ … }

"errors": { … }

"per_page": [ … ],

"The per page field must be an integer."

"sort": [ … ]

"The sort field must be a string."

]

}

Content-Type string

example: application/json

{ … }

"message": "Server Error"

}

No matching endpoints

Get an IVR (user, pbx)

Responses