SipSim

Документация Api V1

● Общая информация

Адрес сервера - https://app.sipsim.by/api/v1/

Как получить токен доступа?

Личный кабинет sipsim.by => Интеграции => Кнопка "Подключить" под иконкой API

Зачем нужен токен и как его использовать?

Токен нужен для авторизации вашего запроса. 

Для каждого запроса по API V1 нужно добавить в параметрах токен. 

Пример: /phones?token=Ваш токен

● Health Check

Проверяет корректность переданного токена и доступность API.

GET /health
Request (запрос)

Дополнительных параметров не требуется.

Response (ответ) => 

• 200 OK – токен действителен, API доступно.
• 403 Forbidden – токен отсутствует или неверен.

{
  "status": "ok",
  "client_id": 123
}

● Phones

Phone (телефон) -- это базовый элемент системы. 

Если вам нужно узнать настройки Менеджера, Отдела или IVR в нашей системе, то вам необходим именно phones.

Доступные методы

• GET /phones

GET /phones

Request (запрос)

Дополнительных параметров нет.

Response (ответ) => Массив телефонов

Элемент массива      

calls_record_settings

calls_redirect_settings

phone_group

working_schedule

●Calls

Call (звонок) -- хранит все данные о звонке.

Доступные методы

• GET /calls

GET /calls

Request (запрос)

!Промежуток между датами должен быть меньше 3 месяцев!       

Response (ответ)

Элемент массива звонков

●AI

AI-данные (транскрипция, саммари, рейтинги, теги) доступны только для чтения (GET). 

Все методы требуют token в параметрах запроса.

Идентификатор звонка: для детальных методов используйте external_id и call_type из ответа GET /calls. Поле public_id в URL детальных методов не используется.

external_id — идентификатор звонка в АТС. Для однозначного доступа к записи в SipSim может понадобиться ещё call_type (inbound или outbound).

В большинстве случаев (звонок клиенту или от клиента) в системе одна запись на external_id — параметр call_type можно не передавать.

Если по одному external_id найдены две ноги (например, внутренний звонок менеджер ↔ менеджер), API вернёт 409 Conflict и список доступных значений в поле call_types. Повторите запрос с call_type=inbound или call_type=outbound.

Алиас: direction=incoming (= inbound), direction=outgoing (= outbound).

Детали по одному звонку

• GET /calls/{external_id}/transcription
• GET /calls/{external_id}/summaries
• GET /calls/{external_id}/ratings
• GET /calls/{external_id}/tags

Пример: /calls/AtsA1-a87d19ce-d288-4064-8d76-2f0d91a72a60/ratings?token=Ваш_токен&call_type=inbound

Общие query-параметры (детали по одному звонку)

GET /calls/{external_id}/transcription

Возвращает транскрипцию звонка.

Request — token (обязательный), call_type или direction (опционально, см. таблицу выше).

Response

Элемент массива segments

Если транскрипция не готова — segments будет пустым массивом.

GET /calls/{external_id}/summaries

Все саммари звонка (только с непустым текстом).

Request — те же параметры, что и для transcription.

Элемент массива summaries

GET /calls/{external_id}/ratings

Обработанные рейтинги звонка. Пустой массив ratings — рейтингов нет.

Request — те же параметры, что и для transcription.

Объект call

Элемент массива ratings

Элемент массива criteria_scores

GET /calls/{external_id}/tags

Request — те же параметры, что и для transcription.

Элемент массива tags

Коллекции AI-данных

• GET /ai/ratings
• GET /ai/summaries
• GET /ai/transcriptions
• GET /ai/tags

Request (запрос)

!Промежуток между датами должен быть меньше 3 месяцев!

Номер в phone можно передавать в любом формате — сервер нормализует автоматически.

Response — общий для всех коллекций:

    GET /ai/ratings — рейтинги + контекст звонка (external_id, caller_number, target_number, registration_time).

    GET /ai/summaries — саммари + контекст звонка.

    GET /ai/transcriptions — метаданные готовых транскрипций (без текста segments).

    GET /ai/tags — теги + контекст звонка, вложенный объект tag (name, description).

Примеры запросов

/calls?token=Ваш_токен&start_date=01.05.2026&end_date=31.05.2026

/ai/ratings?token=Ваш_токен&start_date=01.05.2026&end_date=31.05.2026&phone=%2B3752911115&phone_role=caller

/calls/AtsA1-a87d19ce-d288-4064-8d76-2f0d91a72a60/transcription?token=Ваш_токен

/calls/AtsA1-a87d19ce-d288-4064-8d76-2f0d91a72a60/transcription?token=Ваш_токен&call_type=inbound

Коды ошибок (AI)

Пример ответа 409

{
  "code": 409,
  "error": "Conflict",
  "msg": "Multiple calls match external_id, specify call_type",
  "call_types": ["inbound", "outbound"]
}