API ВойсЛайнс

API ВойсЛайнс позволяет вашим системам — CRM, сайту, BI — работать с ВойсЛайнс без ручных действий в личном кабинете: добавлять контакты в Базы, включать и выключать обзвон, получать итоги звонков и настраивать webhook-уведомления. Для запросов нужен API-ключ: его создаёт Владелец организации в «Настройки → API».

API-ключ#

Ключ создаёт Владелец организации: раздел «Настройки», вкладка «API», кнопка «Создать ключ». Полный ключ показывается один раз — сохраните его в надёжном месте. Там же показан ID организации: подставьте его в адреса запросов вместо {orgId}, например /api/v1/partner-api/client-orgs/{orgId}/call-lists.

В адресах есть partner-api и client-orgs: так они названы с тех времён, когда API было только у партнёров. Запросы к своей организации идут по тем же адресам — с ID вашей организации.

Если доступ к клиентским организациям выключен, ключ партнёра работает как ключ обычной организации.

Запрос с чужим ID получает 404 CLIENT_ORG_NOT_FOUND. Роботы своей организации через API доступны только для чтения — их настраивают в кабинете; изменение даёт 403 INSUFFICIENT_SCOPE. Операции партнёра у обычной организации или при выключенном доступе к клиентским организациям — 403 PARTNER_API_DISABLED. Отозванный ключ перестаёт работать сразу; время последнего запроса видно в списке ключей. Клиентам партнёров ключ не выдаётся: доступ по API им даёт партнёр.

Храните ключ в секрете: отправляйте запросы только со своего сервера и не размещайте ключ в коде страниц сайта или мобильного приложения. Сотрудники ВойсЛайнс никогда не просят прислать ключ. Если ключ мог попасть к посторонним, отзовите его и создайте новый.

Чтобы передавать заявки с сайта в одну Базу, ключ не нужен: в Базе на вкладке «Интеграции» есть готовый адрес загрузки контактов по API.

Первый запрос#

Ключ создаётся в кабинете: «Настройки → API». Первый запрос проверяет, что API доступно, а ключ действует.

curl https://voicelines.ru/api/v1/partner-api/health \
  -H "Authorization: Bearer vlp_live_xxxxxxxxxxxxxxxxx"

Ответ:

{
  "status": "ok",
  "partnerOrgId": "guid",
  "partnerName": "Партнёр",
  "keyId": "guid",
  "keyName": "Основной ключ",
  "timestampUtc": "2026-04-27T10:00:00Z",
  "keyType": "partner"
}

partnerOrgId и partnerName — ID и название организации ключа: имена полей остались от партнёрской версии API. keyType — partner, если ключу доступны клиентские организации, иначе organization. Базовый адрес всех запросов — https://voicelines.ru/api/v1/partner-api. Заголовок с ключом нужен в каждом.

Что умеет API#

Всего 34 операции на 24 адресах. Поля запросов и ответов — в OpenAPI JSON и PDF-контракте.

Робота можно удалить только после отвязки от всех неудалённых Баз, включая выключенные. Запрет тестовых звонков блокирует звонок на добавочный номер Робота, но не отключает обычные исходящие звонки и входящие в Базу. Уже начатые разговоры продолжаются.

В финансовой выдаче входящий звонок Роботу без Базы, включая демонстрационный, отмечен как test. Данные звонка могут отсутствовать, а его полная длительность повторяется в каждой связанной операции — это не оплачиваемые минуты. Правила сверки и nullable-поля описаны в PDF.

Звонки#

Звонки за период — до 31 дня, по 100 на странице, сначала ранние. Следующую страницу запрашивайте с теми же from и to и значением nextCursor в параметре cursor; nextCursor: null — страниц больше нет. Поля — как в webhook о звонке: номер, итог, резюме, длительность, стоимость и ссылка на запись; id звонка — тот же callId, что в webhook. Идущий звонок появляется в выдаче после завершения, поэтому для сверки запрашивайте уже закончившийся период. Параметры callListId и status сужают выдачу.

curl "https://voicelines.ru/api/v1/partner-api/client-orgs/{orgId}/calls?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z&status=GoalAchieved" \
  -H "Authorization: Bearer vlp_live_xxxxxxxxxxxxxxxxx"

Один звонок — GET /client-orgs/{orgId}/calls/{callId}: те же поля, а ещё имя и поля контакта, как в webhook, и полная расшифровка разговора. Звонки отключённой организации, как и её Базы и контакты, не выдаются: ответ 403 CLIENT_ORG_INACTIVE.

Лимиты#

Значения по умолчанию. Фактические лимиты партнёра — в кабинете: «Настройки → API». Лимиты Роботов, Баз и контактов действуют только для запросов через API в клиентских организациях партнёра: в своей организации и в кабинете их нет. Контакты Базы одним массивом — до 5 000, по страницам (limit и cursor) — без ограничения размера Базы.

Лимиты запросов общие для всех ключей организации: десять ключей не дают в десять раз больше запросов. У партнёра в них входят и запросы ко всем его клиентским организациям. При превышении API возвращает 429 и RATE_LIMIT_EXCEEDED. Прежде чем повторять запрос, учитывайте заголовок Retry-After.

Ошибки#

Ошибки возвращаются простым JSON-объектом. HTTP-статус остаётся основным, а errorCode нужен для программной обработки: разбирайте ошибки по нему, текст message может меняться.

{
  "errorCode": "PHONE_INVALID",
  "message": "Неверный формат телефона",
  "traceId": "00-...",
  "details": {
    "field": "phoneE164"
  }
}

Коды с префиксом PARTNER_ относятся к любому ключу: их имена остались от партнёрской версии API. Все 29 кодов — в PDF-контракте.

Где взять доступ#

Ключ создаёт Владелец организации в «Настройки → API». Чтобы ключ работал и с клиентскими организациями, нужны партнёрский режим и доступ к клиентским организациям по API: их включает менеджер ВойсЛайнс.