SIP connections

Manage SIP connections of office and cloud PBXs through which the Bitrix24 account receives and places calls.

Scope: telephony | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

What to know before you start

1. Two PBX types. cloud is a cloud PBX, office is an office PBX. The type is set on creation, defaults to cloud, and cannot be changed afterwards. For an office PBX, Bitrix24 issues an address and a login for incoming calls on creation — the incomingServer and incomingLogin fields.
2. Passwords are write-only. password is passed on create and update but never comes back in a response: responses carry the hasPassword and hasIncomingPassword flags instead of passwords. The list cannot be filtered or sorted by these flags.
3. Five fields can be set through the API: type, title, server, login, password. All other connection fields are read-only, and an extra field in the request body returns 400 READONLY_FIELD.
4. Only your own application's connections are visible. The methods in this section work with connections created by the same Bitrix24 application as the key: an application key works with its own application's connections; a personal key works with connections created through the Bitrix24 account's webhooks. Another application's connection does not appear in the list, and the methods return 404 ENTITY_NOT_FOUND for its configId.
5. The type of configId depends on the method. List, get, create and update responses return it as a string; the delete response returns it as a number. In the path the ID is passed as a number: /v1/voximplant-sip/17.

Quick start

List the SIP connections available to the key:

curl "https://vibecode.bitrix24.com/v1/voximplant-sip" \
  -H "X-Api-Key: YOUR_API_KEY"

The response contains an array of connections in data and their count in meta.total. Connection fields are described on the List connections page.

Full example

An office PBX connection from creation to deletion: create it, read it, change the login and password, delete it. Run the script in Node.js 18+ from a file with the .mjs extension.

const BASE = 'https://vibecode.bitrix24.com/v1/voximplant-sip'
const API_KEY = 'YOUR_API_KEY'

async function call(method, path, body) {
  const headers = { 'X-Api-Key': API_KEY }
  if (body) headers['Content-Type'] = 'application/json'
  const res = await fetch(BASE + path, { method, headers, body: body && JSON.stringify(body) })
  const json = await res.json()
  if (!json.success) throw new Error(`${json.error.code}: ${json.error.message}`)
  return json.data
}

// 1. Create an office PBX connection
const created = await call('POST', '', {
  type: 'office',
  title: 'Office PBX',
  server: 'sip.example.com',
  login: 'office-line',
  password: 'EXAMPLE_SIP_PASSWORD',
})
console.log('Created:', created.configId, 'incoming server:', created.incomingServer)

// 2. Read the connection
const sip = await call('GET', `/${created.configId}`)
console.log('Type:', sip.type, 'password set:', sip.hasPassword)

// 3. Change the login and password
const updated = await call('PATCH', `/${created.configId}`, {
  login: 'office-line-2',
  password: 'EXAMPLE_NEW_SIP_PASSWORD',
})
console.log('New login:', updated.login)

// 4. Delete the connection
const removed = await call('DELETE', `/${created.configId}`)
console.log('Deleted:', removed.deleted)

Endpoint reference

Error codes

SIP connection errors

System errors

Full list of common API errors — Errors.

See also

• Default outgoing line
• Employee telephony settings
• Calls
• Telephony