Create an IVR (user)

# Copy for LLM

Create an IVR menu. announcement is the SoundFile of type announcement played when entering the menu; musicOnHold is an optional SoundFile of type music. default_action controls what happens on caller timeout.

User token only. This route sits behind the token.user guard and is NOT reachable with an Integrations API key: the ivrs scope grants read access only. An API key presented here responds 403 whatever its scopes. IVR menus are normally created and edited in the cockpit UI.

Authorization Headers

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>

accept header · string

example: application/json

Request body · required · application/json

Request schema

pbx_id*string · uuid

Pbx identifier (tenant). Must match the authenticated user's PBX.

name*string

length: 3–64

commentstring | null

length: 0–255

announcement*string · uuid

Sound file (type=announcement) played at the start of the menu

musicOnHoldstring | null · uuid

Sound file (type=music) played while caller is on hold

default_actionstring

Behaviour on caller timeout

enum: hangup repeat default_step

Responses

201 401 403 422 5XX

Response schema

dataobject

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

Response schema

errorstring

Error message

example: Authorization Token is missing

Forbidden. This route is confined to USER-owned bearer tokens (the `token.user` guard). The request presented a customer Integrations API key, which is a Pbx-owned token: no scope grants write access here. Read operations on the same resource are open to API keys; creating or editing is done with a user token or in the cockpit UI.

Response schema

messagestring

Unprocessable Parameters. This error is returned when a parameter is not valid.

Response schema

Expand allCollapse all

messagestring

example: The given data was invalid.

errorsobject

filterarray<string>

[]string

sortarray<string>

[]string

pagearray<string>

[]string

per_pagearray<string>

[]string

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.

post https://cockpit.voxbi.com/api/v1/ivrs

Base URL The production API server The staging API server The development API server

Request sample cURL JavaScript Python PHP

Copy

curl -X POST 'https://cockpit.voxbi.com/api/v1/ivrs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"pbx_id":"550e8400-e29b-41d4-a716-446655440001","name":"Support IVR","comment":"Routes calls to sales or technical support","announcement":"550e8400-e29b-41d4-a716-446655440010","musicOnHold":"550e8400-e29b-41d4-a716-446655440011","default_action":"repeat"}'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/ivrs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "pbx_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Support IVR",
    "comment": "Routes calls to sales or technical support",
    "announcement": "550e8400-e29b-41d4-a716-446655440010",
    "musicOnHold": "550e8400-e29b-41d4-a716-446655440011",
    "default_action": "repeat"
}),
});

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

Copy

import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/ivrs',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "pbx_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Support IVR",
    "comment": "Routes calls to sales or technical support",
    "announcement": "550e8400-e29b-41d4-a716-446655440010",
    "musicOnHold": "550e8400-e29b-41d4-a716-446655440011",
    "default_action": "repeat"
}
)
response.raise_for_status()
data = response.json()
print(data)

Copy

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"pbx_id\": \"550e8400-e29b-41d4-a716-446655440001\",
    \"name\": \"Support IVR\",
    \"comment\": \"Routes calls to sales or technical support\",
    \"announcement\": \"550e8400-e29b-41d4-a716-446655440010\",
    \"musicOnHold\": \"550e8400-e29b-41d4-a716-446655440011\",
    \"default_action\": \"repeat\"
}',
    ],
]);

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

Sample request

Expand all Collapse all Copy

{ … }

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

"name": "Support IVR",

"comment": "Routes calls to sales or technical support",

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

"musicOnHold": "550e8400-e29b-41d4-a716-446655440011",

"default_action": "repeat"

}

Sample response

Expand all Collapse all Copy

{ … }

"data": { … }

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

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

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

"name": "Support IVR",

"comment": "Routes calls to sales or technical support",

"default_action": "repeat"

}

}

Sample response Response headers

Expand all Collapse all Copy

{ … }

"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

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": ""

}

Content-Type string

example: application/json

Sample response Response headers

Expand all Collapse all Copy

{ … }

"errors": { … }

"filter": [ … ],

"The filter field must be an array."

],

"sort": [ … ],

"The sort field must be a string."

],

"page": [ … ],

"The page field must be an integer."

],

"per_page": [ … ]

"The per page field must be an integer."

]

}

}

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

Sample response

Expand all Collapse all Copy

{ … }

"message": "Server Error"

}