API телефонии Ringline

Получайте события о звонках в момент, когда они происходят, читайте справочник внутренних номеров, скачивайте записи разговоров и показывайте оператору карточку клиента, пока телефон ещё звонит.

Что можно собрать

Ringline — облачная АТС. Стыковок с внешней системой четыре, и использовать можно любое подмножество:

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

1. Получите ключ. Мы выдаём его и передаём отдельным каналом. Выглядит как rl_live_…, около 51 символа.
2. Проверьте, что он работает.

   curl -H "Authorization: Bearer rl_live_ВАШ_КЛЮЧ" \
        https://app.ringline.uz/api/v1/account

   Код 200 и поле domain_name означают, что связь есть.
3. Подпишите свой адрес. В ответе придёт signing_secret — сохраните его, больше он не показывается.

   curl -X POST https://app.ringline.uz/api/v1/webhooks \
        -H "Authorization: Bearer rl_live_ВАШ_КЛЮЧ" \
        -H "Content-Type: application/json" \
        -d '{"url":"https://crm.example.de/hooks/ringline","events":["*"]}'

4. Убедитесь в доставке, не дожидаясь живого звонка.

   curl -X POST https://app.ringline.uz/api/v1/webhooks/test \
        -H "Authorization: Bearer rl_live_ВАШ_КЛЮЧ" \
        -H "Content-Type: application/json" \
        -d '{"event_type":"call.completed"}'

   В ответ придёт HTTP-код и тело, которые вернул ваш сервер, — видно, прошла ваша проверка подписи или нет.
5. Обрабатывайте события. Проверьте подпись, затем разбирайте call.*. Отвечайте 2xx в пределах 10 секунд.

Аутентификация

В каждом запросе — постоянный API-ключ в виде bearer-токена:

Authorization: Bearer rl_live_4Vb9esauzSwtlt1js-Ati4KV0Nwtp6QirYeGkFgSzU4

Никакого OAuth, обновления токена и срока действия. Ключ живёт до отзыва в панели Ringline, и отзыв действует с первого же следующего запроса.

У нас хранится только SHA-256 от ключа, поэтому потерянный ключ восстановить нельзя — его отзывают и выдают новый. Обращайтесь с ним как с паролем: только на сервере, не в браузере, не в мобильном приложении и не в репозитории.

Области доступа

У ключа есть набор областей. Какие именно — покажет GET /account; на эндпоинт без нужной области придёт 403 insufficient_scope.

Песочница

Разработка идёт на отдельном арендаторе sandbox — на том же хосте, что и продакшен. В нём два внутренних номера (1001, 1002) и два оператора, живого трафика нет, так что испортить данные реального клиента оттуда невозможно.

Ключ песочницы запросите у нас. С ним доступно всё, кроме настоящих звонков: проверка ключа, чтение справочника, подписка и отправка образцов событий через POST /webhooks/test в любом количестве.

Эндпоинты

Проверяет ключ и описывает арендатора, которому он принадлежит. Подходит для кнопки «проверить подключение».

{
  "domain_uuid": "0e0d5944-a54e-4af6-ab27-14f0757851df",
  "domain_name": "sandbox",
  "key": {
    "id": 5,
    "name": "Sandbox - integration partners",
    "prefix": "rl_live_KCYp",
    "scopes": ["calls.read", "recordings.read", "operators.read", "webhooks.manage"],
    "created_at": "2026-11-09 15:20:00+05",
    "last_used_at": "2026-11-09 15:29:24+05"
  },
  "webhook": null,
  "extensions": [
    {
      "number": "1001",
      "label": "Operator: Sandbox One",
      "enabled": true,
      "operator_id": 50,
      "operator_name": "Sandbox One",
      "operator_email": "op1@sandbox.local",
      "medflow_user_id": null
    }
  ]
}

domain_uuid идентифицирует арендатора и приходит в каждом событии, так что мультиарендная интеграция может маршрутизировать события по нему. Поле medflow_user_id игнорируйте — оно от другой интеграции.

Тот же справочник плюс текущая доступность. Для сопоставления своих пользователей с операторами берите operator_email — внутренние номера переназначают, адреса нет.

{
  "extensions": [
    {
      "number": "1001",
      "label": "Operator: Sandbox One",
      "enabled": true,
      "operator_id": 50,
      "operator_name": "Sandbox One",
      "operator_email": "op1@sandbox.local",
      "presence_mode": "full",
      "inbound_enabled": true,
      "outbound_enabled": false
    }
  ]
}

Оператор не в режиме full или с выключенными входящими никогда не появится в событии call.ringing. Это первое, что стоит проверить при вопросе «почему этому человеку не пришёл звонок».

{ "subscribed": true, "url": "https://crm.example.de/hooks/ringline", "events": ["*"] }

Секрет подписи здесь намеренно не возвращается: он показывается один раз, при подписке.

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

// запрос
{ "url": "https://crm.example.de/hooks/ringline", "events": ["*"] }

// ответ
{
  "subscribed": true,
  "url": "https://crm.example.de/hooks/ringline",
  "events": ["*"],
  "signing_secret": "v6tZj-XCkc4pMOCL05vthvT8OTRmoYAP2AN_WdjI7-ulG15HSnF3y2l5C_BLFZuU"
}

На ключ приходится одна подписка: повторный POST заменяет адрес и список событий. Секрет привязан к ключу и не меняется — чтобы его сменить, нужно выдать новый ключ.

Требования к адресу, проверяются и при регистрации, и заново перед каждой отправкой:

• только https://, не длиннее 2048 символов;
• должен разрешаться в публичный адрес — loopback, 10/8, 172.16/12, 192.168/16, CGNAT и диапазоны облачных метаданных отклоняются;
• без логина и пароля в URL;
• редиректы не отслеживаются — указывайте конечный адрес.

Отсутствие events равнозначно ["*"]. Неизвестный тип события даёт 422, а не молчаливое игнорирование.

Прекращает доставку. Ключ остаётся действительным, секрет не меняется — подписаться заново можно без перенастройки.

Отправляет на ваш адрес одно подписанное событие сейчас и сообщает, что ответил ваш сервер. Так приёмник проверяется до того, как у клиента пойдёт первый звонок.

// запрос (тело необязательно, по умолчанию минимальный «ping»)
{ "event_type": "call.completed" }

// ответ
{
  "delivered": true,
  "url": "https://crm.example.de/hooks/ringline",
  "event_type": "call.completed",
  "http_status": 200,
  "response_body": "{\"received\":true}",
  "sent_payload": { "...": "ровно то, что было подписано и отправлено" }
}

Отдаёт аудио завершённого звонка. call_uuid — это call.call_uuid из события; готовая ссылка лежит в call.recording.url.

curl -H "Authorization: Bearer rl_live_ВАШ_КЛЮЧ" \
     -o call.mp3 \
     https://app.ringline.uz/api/v1/recordings/71dc4322-a21b-48d7-8adf-b743b4ac4e19

В ответе — само аудио, не JSON:

HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Disposition: attachment; filename="71dc4322-a21b-48d7-8adf-b743b4ac4e19.mp3"
Accept-Ranges: bytes

• Контейнер не фиксирован. Сейчас записи в MP3, старые — в WAV. Смотрите Content-Type или call.recording.format, а не предполагайте расширение.
• Range-запросы поддерживаются — Range: bytes=0-65535 даёт 206, прерванную загрузку можно продолжить.
• Изоляция арендаторов. call_uuid чужого арендатора отвечает 404 — так же, как несуществующий.

Типы событий

Четыре события, все про звонки. Подпишитесь на ["*"], чтобы получать всё, или перечислите нужные.

Групповой обзвон даёт ветки

Когда входящий звонит нескольким операторам сразу, вы получаете сам звонок плюс по одной ветке на каждое плечо оператора. У веток is_branch: true и parent_call_uuid, указывающий на родительский звонок.

Если нужна одна запись на разговор — обычный случай — игнорируйте все события с is_branch: true. Разбирайте ветки только если вам действительно важно знать, какие именно телефоны звонили.

Состав события

У всех событий одинаковая оболочка; поля, которые ещё неизвестны, равны null:

{
  "event_id": "evt_71dc4322-a21b-48d7-8adf-b743b4ac4e19_callcompleted_k5",
  "event_type": "call.completed",
  "occurred_at": "2026-11-09T15:24:45+05:00",
  "domain_uuid": "0e0d5944-a54e-4af6-ab27-14f0757851df",
  "call": {
    "call_uuid": "71dc4322-a21b-48d7-8adf-b743b4ac4e19",
    "is_branch": false,
    "parent_call_uuid": null,
    "direction": "inbound",
    "from_number": "+4930123456",
    "to_number": "+998781136247",
    "customer_number": "+4930123456",
    "status": "completed",
    "answered_by_operator": true,
    "ringing_at": "2026-11-09T15:24:21+05:00",
    "answered_at": "2026-11-09T15:24:26+05:00",
    "ended_at": "2026-11-09T15:24:45+05:00",
    "wait_seconds": 5,
    "talk_seconds": 19,
    "total_seconds": 24,
    "operator": {
      "extension": "1001",
      "name": "Sandbox One",
      "email": "op1@sandbox.local"
    },
    "recording": {
      "available": true,
      "url": "https://app.ringline.uz/api/v1/recordings/71dc4322-a21b-48d7-8adf-b743b4ac4e19",
      "format": "mp3",
      "duration_seconds": 19
    },
    "hangup_cause": "NORMAL_CLEARING"
  }
}

Проверка подписи

В каждой доставке приходят такие заголовки:

X-Ringline-Event: call.completed
X-Ringline-Timestamp: 1794219829
X-Ringline-Signature: t=1794219829,v1=1f6b1093b401382ef7bae0a324e6d1bb2bb9a5fa9ae7bd86fb7366cb45160ab8
User-Agent: Ringline-Webhook/1.0

Подпись — это HMAC-SHA256 от строки "<t>.<сырое тело запроса>" на вашем signing_secret, в шестнадцатеричном виде.

<?php
$secret = getenv('RINGLINE_SIGNING_SECRET');
$raw    = file_get_contents('php://input');          // сырые байты, не разобранные
$header = $_SERVER['HTTP_X_RINGLINE_SIGNATURE'] ?? '';

$parts = [];
foreach (explode(',', $header) as $p) {
    [$k, $v] = array_pad(explode('=', trim($p), 2), 2, '');
    $parts[$k] = $v;
}

$ts = (int) ($parts['t'] ?? 0);
if (abs(time() - $ts) > 300) {                       // окно воспроизведения
    http_response_code(400);
    exit('stale timestamp');
}

$expected = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($expected, $parts['v1'] ?? '')) {   // сравнение за одно время
    http_response_code(401);
    exit('bad signature');
}

$event = json_decode($raw, true);
// ... обработка $event, затем ответ 2xx
http_response_code(200);
echo '{"received":true}';

import hashlib, hmac, time
from flask import Flask, request

app = Flask(__name__)
SECRET = b"ваш-signing-secret"

@app.post("/hooks/ringline")
def ringline():
    raw = request.get_data()                      # сырые байты, не request.json
    header = request.headers.get("X-Ringline-Signature", "")
    parts = dict(
        p.strip().split("=", 1) for p in header.split(",") if "=" in p
    )

    ts = int(parts.get("t", 0))
    if abs(time.time() - ts) > 300:               # окно воспроизведения
        return "stale timestamp", 400

    expected = hmac.new(
        SECRET, f"{ts}.".encode() + raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        return "bad signature", 401

    event = request.get_json()
    # ... обработка события
    return {"received": True}, 200

// ASP.NET Core minimal API
app.MapPost("/hooks/ringline", async (HttpRequest req) =>
{
    using var reader = new StreamReader(req.Body);
    var raw = await reader.ReadToEndAsync();          // сырое тело

    var header = req.Headers["X-Ringline-Signature"].ToString();
    var parts = header.Split(',')
        .Select(p => p.Trim().Split('=', 2))
        .Where(p => p.Length == 2)
        .ToDictionary(p => p[0], p => p[1]);

    var ts = long.Parse(parts.GetValueOrDefault("t", "0"));
    var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    if (Math.Abs(now - ts) > 300)
        return Results.BadRequest("stale timestamp");

    var secret = Encoding.UTF8.GetBytes(
        Environment.GetEnvironmentVariable("RINGLINE_SIGNING_SECRET")!);
    using var hmac = new HMACSHA256(secret);
    var computed = Convert.ToHexString(
        hmac.ComputeHash(Encoding.UTF8.GetBytes($"{ts}.{raw}"))
    ).ToLowerInvariant();

    if (!CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(computed),
            Encoding.UTF8.GetBytes(parts.GetValueOrDefault("v1", ""))))
        return Results.Unauthorized();

    // ... обработка события
    return Results.Ok(new { received = true });
});

const crypto = require('crypto');
const express = require('express');
const app = express();

// нужно именно сырое тело — express.json() его потеряет
app.post('/hooks/ringline',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const header = req.get('X-Ringline-Signature') || '';
    const parts = Object.fromEntries(
      header.split(',').map(p => p.trim().split('='))
    );

    const ts = Number(parts.t || 0);
    if (Math.abs(Date.now() / 1000 - ts) > 300) {
      return res.status(400).send('stale timestamp');
    }

    const expected = crypto
      .createHmac('sha256', process.env.RINGLINE_SIGNING_SECRET)
      .update(`${ts}.`)
      .update(req.body)                    // Buffer, без преобразований
      .digest('hex');

    const ok = crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(parts.v1 || '')
    );
    if (!ok) return res.status(401).send('bad signature');

    const event = JSON.parse(req.body.toString('utf8'));
    // ... обработка события
    res.json({ received: true });
  });

Доставка и повторы

Что из этого следует для приёмника:

• Будьте идемпотентны. Отсеивайте дубли по event_id. Доставка повторится, если ваш 2xx потерялся по дороге обратно.
• Сначала ответ, потом работа. Положите событие в очередь и сразу ответьте 2xx: десять секунд — это немного, если внутри обработчика вы дёргаете другие сервисы.
• Не упорядочивайте по времени прихода. Сортируйте по occurred_at или считайте call.completed итоговой записью о звонке.
• Отдавайте 4xx только на действительно некорректный запрос. 4xx означает «больше это не присылайте». Если вы временно сломаны, отвечайте 5xx — событие вернётся.

Карточка клиента из вашей CRM

Обратное направление: при входящем звонке Ringline спрашивает вашу систему и показывает результат оператору до того, как он снял трубку, — имя клиента, уровень членства, ближайшую бронь.

Вы отдаёте один HTTP-эндпоинт, запрос и сопоставление полей мы настраиваем у себя, отдельно для каждого арендатора. Под новую CRM ничего разрабатывать не нужно, так что настройка занимает минуты, как только ваш эндпоинт готов.

Что отправляем мы

Метод GET или POST, ваши заголовки (обычно токен) и ваш шаблон тела. В них подставляются такие метки:

Девятизначный узбекский номер дополняется до +998…; всё остальное передаётся как есть с ведущим +, так что зарубежные звонящие приходят без искажений.

Пример настроенного POST-запроса:

POST https://crm.example.de/api/phone-lookup
Authorization: Bearer ВАШ_ТОКЕН_CRM
Content-Type: application/json

{ "msisdn": "{phone_e164}", "tenant": "{domain_uuid}" }

Если выбран GET и метки в URL нет, мы сами добавим ?phone=….

Что возвращаете вы

Любой JSON, который у вас уже есть. Мы достаём из него значения простыми путями — $.customer.name, $.bookings[0].area — и раскладываем по карточке из пяти полей, которую софтфон показывает как есть:

Для такого ответа:

{
  "success": true,
  "customer": {
    "id": 8821,
    "name": "Klaus Berger",
    "membership": { "level": "Gold", "valid_until": "2027-03-01" },
    "bookings": [
      { "date": "2026-11-12", "area": "Sauna Panorama", "guests": 2 }
    ],
    "profile_url": "https://crm.example.de/customers/8821"
  }
}

сопоставление будет таким:

title    = $.customer.name                 → «Klaus Berger»
subtitle = $.customer.membership.level     → «Gold»
info_1   = $.customer.bookings[0].area     → «Sauna Panorama»
info_2   = $.customer.bookings[0].date     → «2026-11-12»
url      = $.customer.profile_url          → ссылка
found    = $.success                       → false означает «такого клиента нет»

Синтаксис путей намеренно простой: $.a.b, $.a[0].b, $["ключ с пробелами"]. Без фильтров, подстановочных знаков и рекурсивного спуска.

Требования

• Отвечайте быстро. Таймаут настраивается от 1 до 30 секунд, но запрос идёт, пока телефон звонит, — всё, что дольше примерно 2 секунд, уже бесполезно.
• Сообщайте «не найдено» явно, если можете, — логическим полем, на которое мы укажем found. Иначе пустая карточка трактуется как «не найдено».
• Публичный адрес. http:// допускается для систем, стоящих на своём сервере, но хост не должен разрешаться во внутреннюю сеть.
• Ожидайте повторов. Результаты кэшируются по номеру, так что постоянный клиент не дёргает ваш API при каждом звонке.

Пришлите адрес эндпоинта, заголовок авторизации, пример ответа и то, какое поле в какую строку карточки положить. Мы настроим и проверим на живом эндпоинте прямо из панели.

Ошибки

Аутентификация и права — 401, 403:

{ "error": "invalid_token", "error_description": "api key invalid or revoked" }
{ "error": "insufficient_scope", "error_description": "required scope: recordings.read" }

Проверка данных и состояние — 409, 422:

{ "success": false, "message": "url must be an absolute https:// URL" }

Ограничения и хранение

Эндпоинта для вытягивания истории звонков в этом канале нет, поэтому вебхуки — единственный источник данных о звонках. Если приёмник недоступен дольше окна повторов, те звонки отсюда уже не восстановить — напишите нам, мы можем выслать их повторно из журнала доставок.

Чек-лист запуска

1. GET /api/v1/account с ключом песочницы отвечает 200.
2. Ваш адрес подписан, а POST /api/v1/webhooks/test сообщает "delivered": true.
3. Ваша проверка подписи отклоняет подменённое тело — проверьте, изменив один байт.
4. Обработчик отсеивает дубли по event_id и игнорирует is_branch: true.
5. Вы отвечаете 2xx заметно быстрее 10 секунд, а настоящую работу делаете асинхронно.
6. Скачивание записи работает, и вы сохраняете то, что нужно, — помните про окно в 90 дней.
7. Если используете карточку клиента: ваш эндпоинт отвечает быстрее 2 секунд и явно сообщает «не найдено».
8. Запросите продакшен-ключ и замените строку. Больше ничего менять не нужно.