Направления API
API телефонии закрывает несколько задач: подтверждение номера, сообщения и работа со звонками. У каждой группы свой базовый адрес, а правила одинаковые — токен клиента в пути, JSON в ответе, коды ошибок по HTTP.
Подтверждение номера: звонок, обратный звонок, код в SMS или Telegram, push от оператора.
К методам → 02 · Сообщения WhatsAppОтправка сообщений через подключённый WhatsApp.
К методам → 03 · Звонки VOIP APIИстория звонков и записи разговоров.
К методам → 04 · Инструменты PostmanКоллекция запросов и параметры для разработки.
К методам →Общие сведения
| Группа | Базовый URL | Назначение |
|---|---|---|
| Авторизация | https://api.telefon-ip.ru/api/v1/authcalls/ | Flash Calls, Back Calls, SMS и Telegram: коды, статусы, биллинг |
| MobileID | https://api.telefon-ip.ru/mobileid/v1/ | Подтверждение номера через оператора МТС: push или SMS-код |
| Сообщения | https://api.telefon-ip.ru/whatsapp/ | Отправка сообщений WhatsApp |
| Звонки | https://api.telefon-ip.ru/api/v1/voip/ | История звонков и записи разговоров |
Токен клиента передаётся в пути запроса. Он выдаётся в личном кабинете; для методов авторизации доступно 50 тестовых запросов.
https://api.telefon-ip.ru/api/v1/authcalls/{token}/{action}/{params}| Правило | Что означает |
|---|---|
| Формат номера | Авторизация звонком и SMS — 89XXXXXXXXX (11 цифр). MobileID принимает +7…, 8… и 10 цифр |
| Формат ответа | Всегда JSON {"success": bool, "error": "", "data": …}, кроме выгрузки CSV и записи разговора |
| Ошибки | 401 — неверный токен или клиент заблокирован, 400 — неверный параметр, 429 — превышен лимит отправок |
| Лимит на номер | По умолчанию 3 отправки в сутки на один номер; меняется в настройках клиента |
| Ограничение по IP | Опция ip_access_api_flash_call: если включена, запросы принимаются только с адресов из списка доступа |
{
"success": true,
"error": "",
"data": {}
}
Flash Calls — авторизация звонком
Сервис звонит на номер пользователя и сбрасывает вызов. Код подтверждения — последние четыре цифры номера, с которого пришёл звонок. Так пользователю не нужно ничего вводить, кроме этого кода.
| Метод | Запрос | Назначение |
|---|---|---|
| get_code | GET /{token}/get_code/{phone}/ | Позвонить и получить код |
https://api.telefon-ip.ru/api/v1/authcalls/{token}/get_code/{phone}/| Параметр | Тип | Описание |
|---|---|---|
| token | string | Ключ доступа из личного кабинета |
| phone | string | Номер абонента в формате 89XXXXXXXXX |
| sms | boolean | true — если дозвон не удался, отправить SMS с кодом. По умолчанию берётся настройка клиента |
{
"success": true,
"error": "",
"data": {
"phone": "79244501003",
"code": "1003",
"id": 168,
"operator_name": "ООО «Т2 Мобайл»",
"channel": "auth_call"
}
}
Если дозвониться не удалось, вернётся 400 с текстом ошибки в error. Исчерпан лимит на номер — 429. Включено ограничение по IP, а адрес не в списке — 401 ip address restriction.
Back Calls — обратная авторизация
Пользователь сам звонит на выделенный номер, после чего вызов сбрасывается. Номер пользователя возвращается по вебхуку или через отдельный запрос. Время жизни номера — 120 секунд.
| Метод | Запрос | Назначение |
|---|---|---|
| reverse_auth_phone_get | GET или POST /{token}/reverse_auth_phone_get | Получить номер для звонка и создать авторизацию |
| reverse_auth_phone_post | POST /{token}/reverse_auth_phone_post | То же, но параметры в теле запроса |
| reverse_auth_phone_check | GET /{token}/reverse_auth_phone_check/{id} | Проверить, позвонил ли пользователь |
reverse_auth_phone_get — получить номер
https://api.telefon-ip.ru/api/v1/authcalls/{token}/reverse_auth_phone_get?phone={phone}&webhook={url}| Параметр | Тип | Описание |
|---|---|---|
| phone | string | Номер пользователя в формате 89XXXXXXXXX |
| webhook | string | Необязательный URL: после звонка на него придёт результат |
{
"success": true,
"error": "",
"data": {
"auth_phone": "79644115786",
"id": 122760,
"url_image": "https://api.telefon-ip.ru/api/v1/authcalls/get_qr_image/2841621/",
"url_link": "Позвони для авторизации"
}
}
Параметры можно передать в теле POST — тогда используйте адрес reverse_auth_phone_post, метод работает так же. Без параметра phone вернётся 400 phone field is empty.
reverse_auth_phone_check — проверка звонка
https://api.telefon-ip.ru/api/v1/authcalls/{token}/reverse_auth_phone_check/{id}Значение status | Что значит |
|---|---|
waiting | Пользователь ещё не позвонил |
ok | Позвонил, в phone — его номер |
expired | 120 секунд прошли, ответ 408 |
SMS Code — авторизация по SMS
Оператор отправляет пользователю SMS с кодом. Если код не передан в запросе, он генерируется автоматически (4 цифры). Доставка идёт через подключённые каналы: сначала МегаФон, затем МТС.
https://api.telefon-ip.ru/api/v1/authcalls/{token}/get_sms_code/{phone}/| Параметр | Тип | Описание |
|---|---|---|
| phone | string | Номер в формате 89XXXXXXXXX |
| code | string | Необязательно: свой код из 4 цифр. Если не указан — генерируется |
{
"success": true,
"error": "",
"data": {
"phone": "79244501003",
"code": "4821",
"id": 169,
"operator_name": "ООО «Т2 Мобайл»",
"channel": "sms",
"status": true,
"sender": "megafon",
"status_info": null
}
}
status: false означает, что ни один канал не принял сообщение — причина в status_info, а списание при этом всё равно происходит, как и при успешной отправке. Код в поле code возвращается для проверки на вашей стороне.
TG Code — авторизация в Telegram
Код приходит в Telegram на номер, привязанный к аккаунту. Время отображения кода — 90 секунд. Работает, только если у клиента подключён Telegram-канал.
https://api.telefon-ip.ru/api/v1/authcalls/{token}/get_tg_code/{phone}/| Параметр | Тип | Описание |
|---|---|---|
| phone | string | Номер абонента |
| code | string | Необязательно: свой код из 4 цифр. Если не указан — генерируется |
{
"success": true,
"error": "",
"data": {
"phone": "79243555100",
"code": "6681",
"id": 11084059,
"operator_name": "ООО «МегаФон»",
"channel": "telegram",
"status": true,
"status_info": "send ok"
}
}
Код уходит только тем, кто писал боту. Если Telegram недоступен, вернётся status: false с причиной в status_info. При включённом ограничении по IP действует то же правило, что у Flash Calls.
MobileID — подтверждение номера через МТС
Номер подтверждает оператор: пользователь нажимает «Подтвердить» в push-уведомлении на телефоне. Если push не дошёл, МТС отправляет SMS с кодом, и вы показываете поле ввода. Результат — sub, устойчивый идентификатор абонента: к нему привязывается аккаунт, а не к номеру телефона (номер может перейти другому человеку).
Для клиентов адрес — https://api.telefon-ip.ru/mobileid/v1/{token}/, токен тот же, что у авторизации звонком. Домен mid.telefon-ip.ru — служебный: на него МТС присылает свои уведомления, клиентам он не нужен. Стоимость — 3,60 ₽ за подтверждение push-ом и 7,50 ₽ за SMS-каскад у Т2. Списываем по факту подтверждения: отказ и таймаут не тарифицируются, а цена в ответе на старт — ожидаемая (push).
| Метод | Запрос | Назначение |
|---|---|---|
| auth | POST /auth | Запросить подтверждение номера: отправить push или SMS |
| auth/{id} | GET /auth/{id} | Узнать статус и результат |
| auth/{id}/code | POST /auth/{id}/code | Передать код из SMS, если push не прошёл |
auth — запросить подтверждение номера
Не «отправка кода»: код в MobileID приходит от оператора, а первый запрос лишь просит МТС подтвердить номер. Обычно пользователь подтверждает вход в приложении МТС; SMS с кодом — запасной путь.
https://api.telefon-ip.ru/mobileid/v1/{token}/auth| Параметр | Тип | Описание |
|---|---|---|
| phone | string | Номер абонента: +7…, 8… или 10 цифр. Работают только мобильные номера |
| url_webhook | string | Необязательный HTTPS-адрес: на него придёт результат. Можно задать один раз в личном кабинете |
{
"success": true,
"data": {
"session_id": "f7e71a68-6669-4027-8dc1-0c77020d9785",
"status": "pending",
"phone": "79123456789",
"operator": "mts",
"price": 3.6,
"sub": "",
"amr": "",
"expires_at": "2026-11-07T09:56:29+00:00",
"balance": 100.0
}
}
auth/{id} — статус подтверждения
https://api.telefon-ip.ru/mobileid/v1/{token}/auth/{session_id}Опрашивайте раз в 2 секунды, пока статус не станет финальным. Время жизни входа — 5 минут. Статус обновляется в момент уведомления от МТС, опрос только читает его.
| status | Значение | Что делать |
|---|---|---|
pending | Push отправлен, ждём подтверждения | Продолжать опрос |
sms_sent | Push не прошёл, МТС отправила SMS с кодом | Показать ввод кода и вызвать code |
approved | Номер подтверждён | Взять sub и amr, пустить пользователя |
denied | Пользователь отказался или истёк push | Показать отказ, предложить начать заново |
expired | 5 минут прошли | Начать новый вход |
error | Сбой на стороне оператора | Показать ошибку, начать заново |
amr показывает, чем подтвердили: SIM_OK — push, OTP_OK или SMS_OTP — код из SMS, SEAM_OK — подтверждение сетью оператора.
auth/{id}/code — код из SMS
https://api.telefon-ip.ru/mobileid/v1/{token}/auth/{session_id}/code| Параметр | Тип | Описание |
|---|---|---|
| code | string | Код из SMS. Не более 3 попыток на вход |
{
"success": true,
"data": {
"session_id": "f7e71a68-6669-4027-8dc1-0c77020d9785",
"status": "sms_sent",
"accepted": true
}
}
accepted: true означает «код принят оператором», а не «вход выполнен». Финальный результат — в статусе: дождитесь approved.
Вебхук — результат без опроса
Если при старте передан url_webhook (или он сохранён в настройках клиента), результат приходит POST-запросом на этот адрес. Опрос при этом остаётся доступен как страховка.
| event | Когда приходит |
|---|---|
sms_sent | Push не прошёл, МТС отправила SMS — пора показать ввод кода |
approved | Номер подтверждён |
denied | Отказ или таймаут |
expired | Время ожидания истекло |
Тело — те же поля, что у статуса, плюс event и occurred_at. Подпись — в заголовке X-MobileID-Signature: sha256=… (HMAC-SHA256 на ключе токена клиента): проверяйте её, иначе кто угодно сможет прислать вам фальшивый approved.
{
"event": "approved",
"session_id": "f7e71a68-6669-4027-8dc1-0c77020d9785",
"status": "approved",
"phone": "79123456789",
"operator": "mts",
"sub": "sub-123",
"amr": "SIM_OK",
"price": 3.6,
"error": "",
"occurred_at": "2026-11-07T09:56:52+00:00"
}
Доставка: три попытки — сразу, через 20 и ещё через 20 секунд, таймаут 5 секунд, успех — любой 2xx. После трёх неудач повторов нет: результат забирается опросом. События могут повторяться — дедуплицируйте по session_id и event. Адрес принимается только по HTTPS и только публичный: внутренние и служебные адреса отклоняются.
Ошибки
| HTTP | error | Причина |
|---|---|---|
| 401 | unauthorized | Неизвестный токен |
| 401 | client_blocked | Клиент отключён в личном кабинете |
| 400 | insufficient_funds | Баланс ≤ 0 |
| 400 | phone_limit | Исчерпан суточный лимит запросов на номер (по умолчанию 3) |
| 400 | invalid_phone | Не мобильный номер или мусор вместо номера |
| 400 | invalid_webhook | Адрес вебхука не HTTPS или ведёт во внутреннюю сеть |
| 429 | too_many_requests | Слишком много стартов по одному номеру за час |
| 409 | code_not_requested | Код отправлен до того, как МТС перешла на SMS |
| 409 | code_expired | Оператор уже принял код по этой сессии |
| 400 | code_rejected | Неверный код |
| 429 | too_many_attempts | Больше 3 попыток ввода кода |
| 404 | not_found | Сессии нет или она принадлежит другому клиенту |
Статус и биллинг
Методы для проверки результата и баланса. Базовый URL — https://api.telefon-ip.ru/api/v1/authcalls/{token}/.
| Метод | Запрос | Назначение |
|---|---|---|
| get_status | GET /get_status/{id}/ | Статус авторизации по идентификатору |
| get_balance | GET /get_balance/ | Текущий баланс |
| get_billing_record | GET /get_billing_record/{count}/ | Последние операции, не более 100 |
| get_billing_csv | GET /get_billing_csv/{start_date}/ | Выгрузка операций в CSV с даты YYYY-MM-DD |
get_status — статус авторизации
https://api.telefon-ip.ru/api/v1/authcalls/{token}/get_status/{id}/{
"success": true,
"error": "",
"data": {
"id": 168,
"created_at": "2026-11-07T09:12:41",
"phone": "79244501003",
"status": 1,
"status_info": "200",
"price": 1.5,
"status_sip": "200"
}
}
status: 0 — запрос не выполнен, 1 — отправлен, 2 — подтверждён. status_sip — цифры, извлечённые из status_info (ответ SIP). Неизвестный id — 400 id record not found.
get_balance — баланс
https://api.telefon-ip.ru/api/v1/authcalls/{token}/get_balance/{
"success": true,
"error": "",
"data": {
"balance": 1240.5
}
}
get_billing_record — последние операции
https://api.telefon-ip.ru/api/v1/authcalls/{token}/get_billing_record/{count}/{
"success": true,
"error": "",
"data": [
{
"id": 168,
"created_at": "2026-11-07T09:12:41",
"code_auth": "4821",
"status": 1,
"status_info": null,
"phone": "79244501003",
"price": 7.8
}
]
}
count больше 100 не принимается: вернётся 401 count_record field greater than 100 (так в текущей реализации, хотя логичнее 400).
get_billing_csv — выгрузка в CSV
https://api.telefon-ip.ru/api/v1/authcalls/{token}/get_billing_csv/{start_date}/Ответ — файл billing.csv (Content-Type: text/csv) с колонками: created_at, code_auth, status, status_info, auth_type, phone, price. Дата в формате YYYY-MM-DD; при ошибке формата — 400.
WhatsApp — отправка сообщений
Сообщение ставится в очередь и уходит через подключённый WhatsApp. Ответ содержит идентификатор задачи и время отправки в UTC.
https://api.telefon-ip.ru/whatsapp/send_messages/{token}?phone={phone}&message={text}| Параметр | Тип | Описание |
|---|---|---|
| phone | string | Номер получателя в формате 79XXXXXXXXX |
| message | string | Текст сообщения |
| mess_id | integer | Альтернатива тексту: идентификатор готового шаблона |
| app | integer | Необязательно: приложение WhatsApp; без него берётся первое подключённое |
| first | boolean | Не отправлять, если такое сообщение этому номеру уже уходило |
{
"success": true,
"error": "",
"data": {
"task_detail_id": 12345,
"data_time_utc": "2026-08-01 07:15:30+00:00"
}
}
Отправка асинхронная: task_detail_id — задание в очереди, фактическую доставку подтверждает вебхук приложения WhatsApp. Нет подключённого приложения — 404 not found integration; нет phone или message — 400.
VOIP API
История звонков и записи разговоров. Базовый URL — https://api.telefon-ip.ru/api/v1/voip/.
| Метод | Запрос | Назначение |
|---|---|---|
| app/callhistory | GET /app/callhistory/{token}?start_date=&end_date= | История звонков за период |
| get_mp3 | GET /get_mp3/{mp3_id}/{accountcode}/ | Файл записи разговора |
app/callhistory — история звонков
https://api.telefon-ip.ru/api/v1/voip/app/callhistory/{token}?start_date=YYYYMMDD&end_date=YYYYMMDD| Параметр | Тип | Описание |
|---|---|---|
| start_date | string | Дата начала YYYYMMDD; по умолчанию — вчера |
| end_date | string | Дата окончания YYYYMMDD; по умолчанию — текущий момент |
{
"success": true,
"error": "",
"timezone": "Europe/Moscow",
"data": [
{
"uniqueid": "1597532580.42",
"calldate": "2026-08-01 10:15:30+03:00",
"src": "74951234567",
"dst": "79261234567",
"duration": 85,
"billsec": 80,
"disposition": "ANSWERED",
"userfield": "in-main",
"direction": "in"
}
]
}
duration и billsec — секунды. direction — in или out, disposition — результат звонка. Даты считаются в часовом поясе клиента из timezone. Неверный формат даты — 400. Нет звонков — data: [] и success: true.
get_mp3 — запись разговора
https://api.telefon-ip.ru/api/v1/voip/get_mp3/{mp3_id}/{accountcode}/Возвращает аудиофайл записи. mp3_id — значение uniqueid из истории звонков или ссылка из карточки звонка, accountcode — код клиента. Если записи нет — 404, если файл ещё выгружается — 302 на архив.
Postman
Для разработки можно скачать коллекцию запросов и сгенерировать код под свой проект. В коллекции — все методы из этой страницы и переменные host и token.
host—https://api.telefon-ip.ru;token— ключ из личного кабинета.