Подключения (API v2)

Подключения в API Radist.Online: создание и настройка соединений с Telegram, WhatsApp, MAX, Одноклассниками, VK, Авито и банками, привязка к подписке и примеры авторизации.

Общее

Swagger: https://api.radist.online/v2/docs#/Connections

Необходимые права доступа (scopes) для работы с API: connections

Подключение/connection - сущность, содержащая параметры для соединения с внешним сервисом (telegram/whatsapp/tinkoff/amocrm и т.п.)

Замечания

Через API нельзя удалить подключения. Для удаления необходимо обратиться в поддержку. Имейте в виду, что при удалении также удаляются связанные сущности. Например, при удалении терминала банка, будут удалены все выставленные счета. При удалении мессенджера, будут удалены все чаты и история переписки.
Редактирование параметров доступно не для всех типов подключений. Например, подключения AMOCRM/BITRIX управляются полностью на нашей стороне.
Чтобы подключение работало, оно должно быть в оплаченной подписке.

Примеры

Подключение Telegram

Подключение происходит в несколько шагов:

Создание сессии для авторизации
Авторизация
Ввод пароля двухфакторной авторизации (если есть)
Создание подключения

Подключение через сканирование QR-кода

Создаём сессию авторизации https://api.radist.online/v2/docs#/Telegram/TelegramInitializeSession

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
POST /telegram/init

{"auth_type": "qr"}


Response:
{
  "session_id": "fc9132a1-3992-4b57-a9d3-102e17438ae7",
  "status": "waiting_for_qr",
  "qr_login": {
    "url": "tg://login?token=AQLZrYtmQM3kCsDhxpI8zLlKnBvHu8_4sX7d8AaRCI6PGA",
    "expires": "2024-07-08T09:14:01Z",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAM0AAADNAQAAAAAzx8nEAAABq0lEQVR42u1YMY6DQBAztwUlT9ifhI8hgXQfCz/hCZRboMzZA2lOSneKi8sWqyVbxMzYXi+IV6Phs/Xvt3YAXRw1Hpg3ThOfMUf7wsvx51uCMUes8R1xJwLBqPnb22FM6NedhVi1CtYFnQsGq8HOLGBdzDBYiKW2zgYjuXEAN5TNyA0pZZ8qCXJOHqXkIEXbKIJgeGr57dWo+fp97GVLgrBHYWkKC7GRGwSkiQ5iaMpR07kwipidAI27B8ZjWKp8ozaoGg6l8PX555NWi1Q7CVUYlCJiHmg3dUbStXCDSjlbcfl40eniMHN1gdXAQHZSulv/gOuETQOdL9+w2FeJnpyUTKfKqYSlKWJnp0JcxywfHb6R1UAJ3AYJllrtLb6xiJ0hfUAwlkylHhc9owaQIrHAUOy5synJiNQMrdRh5kKgUD5oJbE6zFyWcR+OStXydBn3qzOe9FXoG3QueVh4InFmUfkGT5eeyaP6bm1nEsTpXL351jY/uWGhqK5LurCRrC3D8eqrhrR6ZOiApynJDbqo5JJY8mDxKKXkHVaWMSkOmnzj89Hps/V76weB4g+4/HjcLwAAAABJRU5ErkJggg=="
  }
}

Отображаем пользователю QR-код для сканирования
Периодически (например, раз в 5 секунд) опрашиваем статус сессии: https://api.radist.online/v2/docs#/Telegram/TelegramSendLoginRequest

1
2
3
4
5
6
POST /telegram/login
{
  "session_id": "fc9132a1-3992-4b57-a9d3-102e17438ae7",
  "code": null,
  "password": null
}

Если в ответ снова получили сессию со status=waiting_for_qr и qr-код изменился, показываем новый код пользователю.
Если в ответ получили сессию со status=waiting_for_password, то показываем пользователю поле ввода пароля для 2FA. Этого шага может не быть, если 2FA отключена.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST /telegram/login
{
  "session_id": "fc9132a1-3992-4b57-a9d3-102e17438ae7",
  "code": null,
  "password": "radist"
}

Response:
{
  "session_id": "fc9132a1-3992-4b57-a9d3-102e17438ae7",
  "status": "authenticated",
  "qr_login": null
}

После того, как получили сессию со status=authenticated, можно создавать подключение: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
POST /connections/
{
  "name": "demo",
  "type": "telegram",
  "params": {
    "session_id": "fc9132a1-3992-4b57-a9d3-102e17438ae7"
  }
}

Response:
{
  "id": 12345,
  "name": "demo",
  "radist_token": "4bdb7858-cd5e-4d61-b544-c56b3382ab9b",
  "last_status": {
    "status_type": "good",
    "status_subtype": "normal"
  },
  "integrations": [],
  "subscription_id": 12,
  "type": "telegram",
  "params": {
    "user_id": "12345678",
    "username": null,
    "phone": "+79001234567",
    "group_chats_enabled": false
  }
}

Подключение через код в чате Telegram

Создаём сессию авторизации https://api.radist.online/v2/docs#/Telegram/TelegramInitializeSession

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST /telegram/init

{
  "auth_type": "code",
  "phone": "+79001234567"
}


Response:
{
  "session_id": "08661526-6318-4694-bbcd-c9634616ade4",
  "status": "waiting_for_code"
}

Показываем пользователю поле для ввода кода
Когда получили код, авторизуемся: https://api.radist.online/v2/docs#/Telegram/TelegramSendLoginRequest

1
2
3
4
5
POST /telegram/login
{
  "session_id": "08661526-6318-4694-bbcd-c9634616ade4",
  "code": 44472
}

Если в ответ получили сессию со status=waiting_for_password, то показываем пользователю поле ввода пароля для 2FA. Этого шага может не быть, если 2FA отключена.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
POST /telegram/login
{
  "session_id": "08661526-6318-4694-bbcd-c9634616ade4",
  "code": 44472,
  "password": "radist"
}

Response:
{
  "session_id": "08661526-6318-4694-bbcd-c9634616ade4",
  "status": "authenticated"
}

После того, как получили сессию со status=authenticated, можно создавать подключение: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
POST /connections/
{
  "name": "demo",
  "type": "telegram",
  "params": {
    "session_id": "08661526-6318-4694-bbcd-c9634616ade4"
  }
}

Response:
{
  "id": 12345,
  "name": "demo",
  "radist_token": "4bdb7858-cd5e-4d61-b544-c56b3382ab9b",
  "last_status": {
    "status_type": "good",
    "status_subtype": "normal"
  },
  "integrations": [],
  "subscription_id": 12,
  "type": "telegram",
  "params": {
    "user_id": "12345678",
    "username": null,
    "phone": "+79001234567",
    "group_chats_enabled": false
  }
}

Повторная авторизация

В некоторых случаях может быть необходимо повторить авторизацию. Например, если в приложении Telegram принудительно завершили сессию, которую открыл наш сервис.

Это делается аналогично тому, как происходит первое подключение (см. примеры выше), только при создании сессии для авторизации нужно обязательно передать connection_id и после успешной авторизации не нужно создавать новое подключение.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
POST /telegram/init
{
  "auth_type": "qr",
  "connection_id": 44378
}

Response:
{
  "session_id": "9bc32742-94d5-4ff1-98c8-0239c3ae43f0",
  "status": "waiting_for_qr",
  "qr_login": {
    "url": "tg://login?token=AQJ1s4tmLweHr81U7_dHuP2F71vbNCREIR9mHZb48bABOQ",
    "expires": "2024-07-08T09:37:57Z",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAM0AAADNAQAAAAAzx8nEAAABvElEQVR42u1YMY6EMAwcjiIlT8hP4GNIQcrH4Cd5AmUKtL6xvXfFSdutcHGbAgXSjOyZyRjIq9XxOfr3RyeA4RxFHigN83TxHUX6F16utx8pjCJyKKZDriw71mzfboexIh0nC8EaNJZkzSxOFIyxyT5VwcCSBMLgbsfYsJxR1TBuVEnCkiQjSAg3TClrZkn8EaMUX7VpSZSi5anl+6shh3YBahmz8TSkKbkvtK++yIauSuFrQFM2mH0RBrU6Uy5enNsFm5P5+EAsJl1EVMNkaval7FRAiur+ptTWZ6yQB9nZBwV0BChFRE2L+lgcwaWAAmBcoDRA5yIg8rS2EMFSKelw+9oy24NsZL0fRiYxR9HEY7ugalw57aaPaXPnwhJh5oVKIYKkeYOAgBRBUWXnPonH0PSbCQNij/qG+jgfIEt6CDdEgGmjhStZLRLvES662Z0iHgcf3h4JCYGMoaL2pUkwiKK2/H4rfsezRxKTRc3R1cyNpzG+IX6hGTE1DccMjzqnmJVSLmZfMU3xqY089UjMzgQOj9oPZKNozICg3CBPGcqr7kqLyaLPqY1zSm0/U0KQb3x+On2O/h59A0RWFuNAeCv9AAAAAElFTkSuQmCC"
  }
}

Подключение Telegram Bot

Подключение

Необходимо создать подключение с типом telegram_bot, передав API ключ от бота: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

1
2
3
4
5
6
7
{
  "name": "demo",
  "params": {
    "bot_token": "1738456161:AAERS_R5S2cly6u4DkWY0oeTq4zWWu54lxw"
  },
  "type": "telegram_bot"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "id": 12345,
  "name": "demo",
  "radist_token": "12bbecfc-5701-4d60-ba61-d6bf2a346870",
  "last_status": null,
  "integrations": [],
  "subscription_id": 618,
  "type": "telegram_bot",
  "params": {
    "bot_id": "1738456161",
    "bot_username": "demo_bot"
  }
}

Подключение WhatsApp

Авторизация, подключение

Необходимо создать подключение с типом whatsapp: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

1
2
3
4
{
  "name": "some name",
  "type": "whatsapp"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "id": 6271,
  "name": "some name",
  "radist_token": "a091b49b-055b-4e62-a913-19544b829c64",
  "last_status": {
    "status_type": "bad",
    "status_subtype": "whatsapp_qr_not_scanned"
  },
  "integrations": null,
  "subscription_id": 616,
  "type": "whatsapp",
  "params": {
    "phone": null,
    "qr_url": "https://services.radist.online/whatsapp/qr/Vw9WE5XjWyK3"
  }
}

После создания подключение ещё не авторизовано (last_status.status_subtype = whatsapp_qr_not_scanned). Авторизуйте его методом WhatsAppInitWhatsappLogin — он поддерживает два способа авторизации, выбираемых параметром auth_type: по QR-коду (qr, по умолчанию) или по коду на телефон (phone).

Способ 1 — по QR-коду (auth_type=qr). В ответе возвращается qr_code (data-URI) и срок его действия expires_at. Отобразите QR-код пользователю — он сканирует его в мобильном приложении WhatsApp: Настройки → Связанные устройства → Привязка устройства.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /whatsapp/{connection_id}/login
{
  "auth_type": "qr"
}

Response:
{
  "status": "qr",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_at": "2026-06-23T09:14:01Z"
}

Способ 2 — по коду на телефон (auth_type=phone). Параметр phone обязателен. В ответе возвращается восьмизначный код подтверждения auth_code (в формате XXXX-XXXX) и срок действия expires_at. Покажите auth_code пользователю — он вводит его в приложении WhatsApp при привязке устройства по номеру телефона: Настройки → Связанные устройства → Привязка устройства → Связать по номеру телефона.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
POST /whatsapp/{connection_id}/login
{
  "auth_type": "phone",
  "phone": "+79001234567"
}

Response:
{
  "status": "phone",
  "auth_code": "ABCD-2345",
  "expires_at": "2026-06-23T09:14:01Z"
}

В обоих случаях после истечения expires_at вызовите метод повторно, чтобы получить новый код/QR. Если подключение уже авторизовано, метод вернёт 409.

Опрашивайте статус авторизации методом WhatsAppGetWhatsappInstanceStatus (например, раз в 5 секунд), пока не получите status=ok:

1
2
3
4
5
6
GET /whatsapp/{connection_id}/status

Response:
{
  "status": "ok"
}

status=ok — подключение авторизовано, status=loading — ожидаем подтверждения кода/QR или запуск инстанса. QR-код и код подтверждения этот метод не возвращает — для их получения используйте login.

Для переподключения повторно вызовите login и заново отсканируйте QR-код или введите код.

Подключение MAX

Первое подключение

Создаём сессию авторизации:
https://api.radist.online/v2/docs#/Max%20personal/Max%20personalInitializeSession

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /max_personal/init
{
  "phone": "+79001234567"
}


Response:
{
  "session_id": "08661526-6318-4694-bbcd-c9634616ade4",
  "status": "waiting_for_code"
}

Показываем пользователю поле для ввода кода
Когда получили код, авторизуемся:

https://api.radist.online/v2/docs#/Max%20personal/Max%20personalSendLoginRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /max_personal/login
{
  "session_id": "08661526-6318-4694-bbcd-c9634616ade4",
  "code": "44472"
}

Response:
{
  "session_id": "08661526-6318-4694-bbcd-c9634616ade4",
  "status": "authenticated"
}

После того, как получили сессию со status=authenticated, можно создавать подключение: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
POST /connections/
{
  "name": "demo",
  "type": "max_personal",
  "params": {
    "session_id": "08661526-6318-4694-bbcd-c9634616ade4"
  }
}

Response:
{
  "id": 12345,
  "name": "demo",
  "radist_token": "4bdb7858-cd5e-4d61-b544-c56b3382ab9b",
  "last_status": {
    "status_type": "good",
    "status_subtype": "normal"
  },
  "integrations": [],
  "subscription_id": 12,
  "type": "max_personal",
  "params": {
    "user_id": "12345678",
    "phone": "+79001234567"
  }
}

Подключение MAX Bot

Подключение

Необходимо создать подключение с типом max_bot, передав токен бота: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
POST /connections/
{
  "name": "demo",
  "type": "max_bot",
  "params": {
    "bot_token": "1738456161:AAERS_R5S2cly6u24DkWY01oeTq4zWWu54lxw"
  }
}

Response:
{
  "id": 12346,
  "name": "demo",
  "radist_token": "5cbecfc-5701-4d60-ba61-d6bf2a346871",
  "last_status": null,
  "integrations": [],
  "subscription_id": 619,
  "type": "max_bot",
  "params": {
    "bot_id": "1738456161",
    "bot_username": "demo_max_bot"
  }
}

Подключение Одноклассников

Первое подключение

Необходимо создать подключение с типом odnoklassniki, передав API ключ от группы: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

1
2
3
4
5
6
7
{
  "name": "ok demo",
  "type": "odnoklassniki",
  "params": {
    "ok_api_key": "tkn1YMi1UuraOrb5DpqmD9TYEFAabPg3mlaRHK4hfusrud5oVIee0LlAxNJ7jJA33FQR1:CLEQNMJGDIHBABABA"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "id": 6272,
  "name": "ok demo",
  "radist_token": "73def00f-22fa-4541-a5c1-a15eb347a959",
  "last_status": {
    "status_type": "good",
    "status_subtype": "normal"
  },
  "integrations": null,
  "subscription_id": 617,
  "type": "odnoklassniki",
  "params": {
    "group_id": "group:59129296584917"
  }
}

Изменение API-ключа

Необходимость изменить API-ключ может возникнуть по разным причинам:

В настройках группы сбросили ключ
Ключ давно не использовался и стал неактивен

Для его обновления можно использовать метод: https://api.radist.online/v2/docs#/Connections/ConnectionsUpdateConnection

Подключение VK (группа)

Первое подключение

Необходимо создать подключение с типом vk_group, передав ключ доступа сообщества (Настройки сообщества → Работа с API → Ключи доступа, права messages): https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
POST /connections/
{
  "name": "vk demo",
  "type": "vk_group",
  "params": {
    "access_token": "vk1.a.Ab1Cd2Ef3...redacted"
  }
}

Response:
{
  "id": 6273,
  "name": "vk demo",
  "radist_token": "84efc00f-33fa-4551-b5c1-b25eb347a960",
  "last_status": {
    "status_type": "good",
    "status_subtype": "normal"
  },
  "integrations": [],
  "subscription_id": 620,
  "type": "vk_group",
  "params": {
    "group_id": "218400244",
    "name": "Demo Group",
    "screen_name": "demo_group",
    "group_chats_enabled": false
  }
}

Подключение VK (Direct, личный аккаунт)

Авторизация происходит через QR-код (аналогично Telegram), с дополнительным шагом валидации, если VK посчитает вход подозрительным.

Первое подключение

Создаём сессию авторизации и получаем QR-код: https://api.radist.online/v2/docs#/VK%20Direct/VK%20DirectInitializeSession

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST /vk_direct/init
{}

Response:
{
  "session_id": "a1b2c3",
  "status": "waiting_for_qr_scan",
  "qr_login": {
    "url": "https://id.vk.com/auth/qr?...",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAM0...",
    "expires": "2026-07-06T10:29:00Z"
  }
}

Отображаем пользователю QR-код для сканирования в мобильном приложении VK
Периодически (например, раз в 2-3 секунды) опрашиваем статус сессии: https://api.radist.online/v2/docs#/VK%20Direct/VK%20DirectPollLogin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
POST /vk_direct/login
{
  "session_id": "a1b2c3"
}

Response:
{
  "session_id": "a1b2c3",
  "status": "waiting_for_qr_scan"
}

Пока пользователь не отсканировал код, status остаётся waiting_for_qr_scan. Если сессия протухла, отменена или недействительна, придёт status=need_refresh_qr — нужно заново вызвать /vk_direct/init.
Если VK посчитал вход подозрительным, придёт status=need_validation_code. Запросите у пользователя код подтверждения и повторите /vk_direct/login, дополнительно передав validation_code:

1
2
3
4
5
POST /vk_direct/login
{
  "session_id": "a1b2c3",
  "validation_code": "123456"
}

Когда пользователь подтвердил вход в мобильном приложении, status станет authenticated:

1
2
3
4
5
Response:
{
  "session_id": "a1b2c3",
  "status": "authenticated"
}

После этого можно создавать подключение, передав тот же session_id: https://api.radist.online/v2/docs#/Connections/ConnectionsCreateConnection

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
POST /connections/
{
  "name": "vk direct demo",
  "type": "vk_direct",
  "params": {
    "session_id": "a1b2c3"
  }
}

Response:
{
  "id": 6274,
  "name": "vk direct demo",
  "radist_token": "95efc00f-44fa-4661-c6c1-c36eb347a961",
  "last_status": {
    "status_type": "good",
    "status_subtype": "normal"
  },
  "integrations": [],
  "subscription_id": 621,
  "type": "vk_direct",
  "params": {
    "user_id": "123456789",
    "phone": "+79001234567",
    "profile_url": "https://vk.com/id123456789",
    "first_name": "Иван",
    "last_name": "Иванов",
    "group_chats_enabled": false,
    "screen_name": null
  }
}

Повторная авторизация

Аналогично Telegram: при вызове /vk_direct/init передайте connection_id уже существующего подключения — сессия будет привязана к тому же устройству (device_id), и повторно создавать подключение после успешной авторизации не нужно.

1
2
3
4
POST /vk_direct/init
{
  "connection_id": 6274
}

Подключение Авито

В отличие от остальных мессенджеров, Авито подключается через OAuth — создать подключение одним запросом нельзя, нужен переход пользователя на страницу авторизации Авито.

Подключение

Получаем ссылку для авторизации: https://api.radist.online/v2/docs#/Avito/AvitoGetAvitoAuthUrl

1
2
3
4
5
6
GET /avito/auth_url

Response:
{
  "auth_url": "https://avito.ru/oauth?response_type=code&client_id=...&state=..."
}

Открываем auth_url в браузере пользователя (например, во всплывающем окне). Пользователь авторизуется и разрешает доступ на стороне Авито.
Авито перенаправляет пользователя на наш callback-адрес — он не является частью публичного API и вызывается только со стороны Авито. После успешной авторизации подключение с типом avito создаётся автоматически, без дополнительных запросов с вашей стороны.
Дождитесь появления нового подключения (например, опросив список подключений) или подпишитесь на вебхук connections.status_changed.

Последнее обновление 10 июля 2026 г.

Авторизация в API Интеграции (API v2)