API документация

Направления API

API телефонии закрывает несколько задач. Сейчас в разделе доступны методы авторизации, отправки сообщений и работы со звонками, а также инструменты для разработчиков. Список будет пополняться.

Общие сведения

API решает несколько групп задач: авторизация, сообщения и звонки. У каждой группы свой базовый адрес, а общие правила — токен, формат JSON и обработка ошибок — совпадают.

Для методов авторизации используется адрес:

Токен выдаётся в личном кабинете. Для методов авторизации доступно 50 тестовых запросов. Для защиты от спама используйте капчу и ограничивайте число отправок на один номер.

{
  "success": true,
  "error": "",
  "data": {}
}

Ошибка 401 означает неверный токен. Ошибка 400 — неверный формат номера или отсутствует обязательный параметр. По умолчанию действует лимит 3 отправки в сутки на один номер; лимит можно изменить при подключении.

Flash Calls — авторизация звонком

Сервис звонит на указанный номер. Код подтверждения — последние четыре цифры номера, с которого поступил звонок. Пользователь вводит их в интерфейсе. Если включён параметр sms=true, при неудачном дозвоне автоматически отправляется SMS с кодом.

get_code — получение кода

{
  "success": true,
  "error": "",
  "data": {
    "phone": "79244501003",
    "code": "1003",
    "id": 168
  }
}

Пример запроса с резервной SMS:

Back Calls — обратная авторизация

Пользователь сам звонит на выделенный номер, после чего вызов сбрасывается. Номер пользователя возвращается по webhook или через отдельный GET-запрос. Время жизни номера для авторизации — 120 секунд.

reverse_auth_phone_get — получить номер для звонка

{
  "success": true,
  "error": "",
  "data": {
    "auth_phone": "79644115786",
    "id": 122760,
    "url_image": "https://api.telefon-ip.ru/api/v1/authcalls/get_qr_image/2841621/"
  }
}

reverse_auth_phone_post — получить номер с webhook

После звонка на указанный webhook приходит запрос с параметрами success, phone и id.

reverse_auth_phone_check — проверить номер

{
  "success": true,
  "error": "",
  "data": {
    "phone": "89243555100",
    "id": 122760,
    "status": "ok"
  }
}

Пока абонент не позвонил, ответ 200 с status: "waiting" и пустым phone. Если id не найден или истёк — 408 (status: "expired"), неверный id — 400; 401 — неверный токен.

SMS Code — авторизация по SMS

Код подтверждения отправляется в SMS на указанный номер. Подпись в тексте SMS согласовывается по адресу support@telefon-ip.ru.

get_sms_code — запросить SMS с кодом

{
  "success": true,
  "error": "",
  "data": {
    "phone": "79244501003",
    "code": "1003",
    "id": 168
  }
}

TG Code — авторизация в Telegram

Код отправляется в Telegram на номер, привязанный к аккаунту. Время отображения кода в чате — 90 секунд.

get_tg_code — отправить код в Telegram

{
  "success": true,
  "error": "",
  "data": {
    "phone": "79243555100",
    "code": "6681",
    "id": 11084059,
    "operator_name": "ООО «МегаФон»",
    "channel": "telegram",
    "status": true,
    "status_info": "send ok"
  }
}

MobileID — подтверждение номера

Номер подтверждает оператор: пользователь не вводит код, а нажимает «Подтвердить» в push-уведомлении на телефоне. Если push не дошёл, оператор отправляет SMS с кодом, и вы показываете поле ввода. Результат — sub, устойчивый идентификатор абонента: к нему привязывается аккаунт, а не к номеру телефона (номер может перейти другому человеку).

Адрес — https://api.telefon-ip.ru/mobileid/v1/{token}/, токен тот же, что у авторизации звонком.

auth — начать вход

{
  "success": true,
  "data": {
    "session_id": "f7e71a68-6669-4027-8dc1-0c77020d9785",
    "status": "pending",
    "phone": "79123456789",
    "sub": "",
    "amr": "",
    "expires_at": "2026-11-07T09:56:29+00:00"
  }
}

auth/{id} — статус входа

Статус опрашивается раз в 2 секунды, пока не станет финальным. Время жизни входа — 5 минут. Статус меняется в момент уведомления от оператора, опрос только читает его.

amr показывает, чем подтвердили: SIM_OK — push, OTP_OK или SMS_OTP — код из SMS, SEAM_OK — подтверждение сетью оператора.

auth/{id}/code — SMS-код

{
  "success": true,
  "data": {
    "session_id": "f7e71a68-6669-4027-8dc1-0c77020d9785",
    "status": "sms_sent",
    "accepted": true
  }
}

accepted: true означает «код принят оператором», а не «вход выполнен». Финальный результат — в статусе: дождитесь approved.

Вебхук — результат без опроса

Если при старте передан url_webhook, результат приходит POST-запросом на этот адрес. Опрос при этом остаётся доступен как страховка.

Запрос содержит те же поля, что и статус, плюс event и occurred_at. Подпись тела — в заголовке X-MobileID-Signature: sha256=… (HMAC-SHA256 на ключе токена клиента): проверяйте её, иначе кто угодно сможет прислать вам фальшивый approved.

{
  "event": "approved",
  "session_id": "f7e71a68-6669-4027-8dc1-0c77020d9785",
  "status": "approved",
  "phone": "79123456789",
  "sub": "sub-123",
  "amr": "SIM_OK",
  "error": "",
  "occurred_at": "2026-11-07T09:56:52+00:00"
}

Правила доставки: три попытки — сразу, через 20 и ещё через 20 секунд, таймаут 5 секунд на попытку, успех — любой ответ 2xx. После трёх неудач повторов нет: результат забирается опросом. События могут повторяться — дедуплицируйте по session_id и event. Адрес принимается только по HTTPS и только публичный: внутренние и служебные адреса отклоняются.

Ошибки

Вспомогательные функции

Методы для проверки статуса, баланса и истории операций. Базовый URL — тот же: https://api.telefon-ip.ru/api/v1/authcalls/{token}/.

get_status — статус авторизации

{
  "success": true,
  "error": "",
  "data": {
    "id": 454733,
    "created_at": "2023-04-02T12:54:31",
    "phone": "89243555100",
    "status": 1,
    "status_info": "Ok: SIP 200 OK",
    "price": 0.2
  }
}

get_balance — баланс

{
  "success": true,
  "error": "",
  "data": {
    "balance": 5.0
  }
}

Для get_billing_record количество записей не должно превышать 100. Для get_billing_csv дата передаётся в формате YYYY-MM-DD; в ответ приходит CSV-файл.

WhatsApp — отправка сообщений

Отправка сообщений через WhatsApp. В личном кабинете TELEFON-IP.RU привяжите WhatsApp через связанные устройства в разделе рассылок. Сообщение ставится в очередь рассылки и уходит через подключённое приложение.

send_messages — отправить сообщение

{
  "success": true,
  "error": "",
  "data": {
    "task_detail_id": 12345,
    "data_time_utc": "2026-08-01T10:15:30"
  }
}

VOIP API

API для управления звонками. В текущей версии доступна история звонков за период.

Получение истории звонков

{
  "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 — направление звонка, disposition — результат. При неверном формате даты вернётся ошибка 400.

Postman

Для разработки можно скачать коллекцию запросов и сгенерировать код под свой проект. Коллекция обновлена 2026-11-06: в ней все методы из этой страницы и переменные host и token.

• host — https://api.telefon-ip.ru;
• token — ключ из личного кабинета.

Скачать коллекцию Postman