SIP-подключения

Управление SIP-подключениями офисных и облачных АТС, через которые портал Битрикс24 принимает и совершает звонки.

Скоуп: telephony | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Что нужно знать перед работой

1. Два типа АТС. cloud — облачная АТС, office — офисная. Тип задаётся при создании, по умолчанию cloud, и потом не меняется. Офисной АТС Битрикс24 при создании выдаёт адрес и логин для входящих вызовов — поля incomingServer и incomingLogin.
2. Пароли только на запись. password передаётся при создании и изменении, но в ответ не попадает: вместо паролей приходят признаки hasPassword и hasIncomingPassword. По этим признакам нельзя фильтровать и сортировать список.
3. Через API задаются пять полей: type, title, server, login, password. Остальные поля подключения только для чтения, а лишнее поле в теле запроса даёт 400 READONLY_FIELD.
4. Видны только подключения своего приложения. Методы раздела работают с подключениями, созданными тем же приложением Битрикс24, что и ключ: ключ приложения — с подключениями своего приложения, личный ключ — с подключениями, созданными через вебхуки портала. Подключение другого приложения не попадает в список, а по его configId методы отвечают 404 ENTITY_NOT_FOUND.
5. Тип configId зависит от метода. В ответах списка, получения, создания и изменения это строка, в ответе удаления — число. В пути ID передаётся числом: /v1/voximplant-sip/17.

Быстрый старт

Список SIP-подключений, доступных ключу:

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

Ответ содержит массив подключений в data и их число в meta.total. Поля подключения описаны на странице Список подключений.

Полный пример

Подключение офисной АТС от создания до удаления: создать, прочитать, сменить логин и пароль, удалить. Скрипт запускается в Node.js 18+ из файла с расширением .mjs.

const BASE = 'https://vibecode.bitrix24.tech/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. Создать подключение офисной АТС
const created = await call('POST', '', {
  type: 'office',
  title: 'Офисная АТС',
  server: 'sip.example.com',
  login: 'office-line',
  password: 'EXAMPLE_SIP_PASSWORD',
})
console.log('Создано:', created.configId, 'сервер для входящих:', created.incomingServer)

// 2. Прочитать подключение
const sip = await call('GET', `/${created.configId}`)
console.log('Тип:', sip.type, 'пароль задан:', sip.hasPassword)

// 3. Сменить логин и пароль
const updated = await call('PATCH', `/${created.configId}`, {
  login: 'office-line-2',
  password: 'EXAMPLE_NEW_SIP_PASSWORD',
})
console.log('Новый логин:', updated.login)

// 4. Удалить подключение
const removed = await call('DELETE', `/${created.configId}`)
console.log('Удалено:', removed.deleted)

Справочник эндпоинтов

Коды ошибок

Ошибки SIP-подключений

Системные ошибки

Полный список общих ошибок API — Ошибки.

Смотрите также

• Исходящая линия по умолчанию
• Телефония сотрудников
• Звонки
• Телефония