--- title: "Подключение по SIP (без номера телефона)" description: "Направляйте звонки агенту ThunderPhone напрямую из вашей УАТС, от оператора связи или из SIP-приложения, используя одноразовый SIP URI для каждого звонка или постоянный SIP-адрес." --- Если ваша система уже работает с телефонными номерами (АТС, платформа контакт-центра или аккаунт оператора, где вы меняете номера), вы можете отправлять звонки агенту ThunderPhone через обычный SIP. Вам не нужно импортировать или покупать номер в ThunderPhone. Ваша система набирает SIP-адрес, а агент отвечает. Существует два типа SIP-адресов: | | **SIP URI для каждого звонка** | **SIP-эндпоинт** | |---|---|---| | Выглядит как | `sip:c-@sip.thunderphone.com` | `sip:agent--@sip.thunderphone.com` | | Создаётся с помощью | `POST /v1/calls/register-sip`, один раз для каждого звонка | `POST /v1/sip-endpoints`, один раз | | Аутентификация | Одноразовый токен в адресе | Имя пользователя и пароль SIP digest (а также, при необходимости, список разрешённых исходных IP-адресов) | | Подходит для | Приложений, которые уже вызывают API перед переводом звонка; переменных для каждого звонка | АТС и операторов, которым нужно просто «направить транк» на ThunderPhone | | Действителен | 5 минут, один звонок | Пока вы его не удалите | Оба типа направляют звонки одному агенту в вашей организации и отображаются в истории звонков как любые другие входящие звонки. ## SIP URI для каждого звонка ### 1. Зарегистрируйте звонок ```bash curl -X POST https://api.thunderphone.com/v1/calls/register-sip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": 12, "to_number": "+14155550142", "variables": {"customer_name": "Ada"} }' ``` ```json { "call_id": 862197007562, "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com", "expires_at": "2026-09-25T21:49:52Z", "agent_id": 12, "to_number": "+14155550142" } ``` - `to_number` (необязательно) — номер, который звонящий набрал на вашей стороне. Он сохраняется как номер назначения звонка в истории звонков, а агент видит его как свой номер. - `variables` (необязательно) заполняют `{{placeholders}}` в промпте агента так же, как для [исходящих звонков](/ru/guides/call-variables). - `call_id` — идентификатор, который звонок получит в истории звонков (`GET /v1/calls/{call_id}`) после соединения. ### 2. Наберите URI Отправьте звонок на `sip_uri` в течение 5 минут. URI работает только для одного звонка: после использования звонком он становится недействительным, даже если этот звонок быстро завершится. Например, в Twilio верните этот TwiML для звонка, который вы хотите передать: ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` В АТС наберите URI как SIP-адрес назначения. Имя пользователя или пароль не нужны: токен служит учётными данными, поэтому обращайтесь с URI как с паролем, пока он не будет использован. ## SIP-конечная точка (постоянный адрес) ### 1. Создайте конечную точку ```bash curl -X POST https://api.thunderphone.com/v1/sip-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"agent_id": 12, "name": "Main PBX"}' ``` ```json { "id": 7, "name": "Main PBX", "agent_id": 12, "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com", "username": "tp409667538f83", "password": "8mJ0…", "allowed_source_cidrs": [], "status": "active", "created_at": "2026-09-25T21:46:18Z" } ``` `password` возвращается только один раз — при создании конечной точки. Сразу сохраните его в конфигурации вашей PBX или оператора. Если вы его потеряете, смените пароль с помощью `POST /v1/sip-endpoints/{id}/rotate-password`. ### 2. Настройте систему на этот адрес Настройте SIP-транк или назначение со следующими параметрами: | Параметр | Значение | |---|---| | SIP URI | `sip_uri` конечной точки | | Имя пользователя / пароль | `username` / `password` (digest-аутентификация; ThunderPhone запрашивает аутентификацию для каждого вызова) | | Транспорт | TCP на порту 5060 или TLS на порту 5061 (рекомендуется), либо UDP на порту 5060 | | Кодеки | G.711 (PCMU/PCMA) или G.722 | Предпочтительно используйте TCP или TLS. UDP работает с публичных адресов и из большинства NAT, но за «симметричным» NAT (который использует новый порт для каждого назначения) завершение вызовов и переводы агента могут не доходить до вашей системы. Для списка разрешённых IP-адресов источников (ниже) также требуется TCP или TLS. При использовании TLS SIP-сигнализация остаётся зашифрованной и после `sip.thunderphone.com` — вплоть до серверов, обрабатывающих вызов. Эти настройки транспорта и кодеков также применяются к URI для отдельных вызовов. Для обоих типов адресов важны две особенности сети: - **Следуйте Record-Route.** После первого INVITE остальная сигнализация вызова (ACK, завершение вызова, переводы) направляется на конкретный сервер ThunderPhone, который принял вызов и указан в заголовке `Record-Route` (`sip-1.thunderphone.com` или `sip-2.thunderphone.com`, либо его IP-адрес). Если вы ограничиваете исходящий SIP-трафик, разрешите эти хосты наряду с `sip.thunderphone.com`: `172.170.39.202` (`sip`), `13.86.104.121` (`sip-1`) и `20.80.98.90` (`sip-2`). - **Аудио передаётся по другим адресам.** `sip.thunderphone.com` передаёт только сигнализацию. Разрешите медиатрафик (RTP) к адресам и портам из SDP-ответа. Каждый вызов на этот адрес поступает агенту конечной точки независимо от номера, набранного звонящим в вашей системе. Номера не нужно импортировать, поэтому при их смене на вашей стороне в ThunderPhone ничего менять не нужно. ### Передача набранного номера (необязательно) Чтобы записывать, на какой из ваших номеров позвонил звонящий, передайте его в INVITE в заголовке `X-Original-To` (например, `X-Original-To: +14155550142`) или в стандартном заголовке `Diversion`. ThunderPhone сохраняет его как назначение вызова. Назначение выбирается в следующем порядке: `to_number`, указанный при регистрации URI для отдельного вызова, затем номер из `X-Original-To`, затем номер из `Diversion`. Если ни один из этих вариантов не содержит номера, для конечной точки отображается `sip:agent-12-jhxmginwjx` (адрес конечной точки), а для URI отдельного вызова — `sip:call`. В Twilio можно добавить заголовок в SIP URI: `sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142`. ### Ограничение IP-адресов источников (необязательно) Задайте `allowed_source_cidrs`, чтобы в дополнение к имени пользователя и паролю принимать вызовы только с ваших адресов сигнализации: ```bash curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}' ``` Вызовы с любых других адресов отклоняются до того, как попадут к агенту. Используйте адреса, с которых ваша система отправляет SIP-сигнализацию (для оператора, такого как Twilio, — опубликованные диапазоны IP-адресов сигнализации), а не адреса для медиатрафика. Список разрешённых адресов проверяется только для вызовов по TCP или TLS. Адрес источника UDP можно подделать, поэтому конечная точка со списком разрешённых адресов отклоняет каждый вызов, поступающий по UDP. Отправляйте вызовы на неё с `;transport=tcp` (порт 5060) или по TLS (порт 5061). ## Что видят звонящие и ваша система - **Идентификатор звонящего:** пользовательская часть заголовка `From` сохраняется как звонящий. Номер телефона (цифры, при необходимости с `+`, пробелами, дефисами, точками или скобками) нормализуется до E.164; всё остальное, например имя пользователя SIP, сохраняется в отправленном виде. Сохраняется не более 32 символов, а при отсутствии звонящего сохраняется значение `anonymous`. - **Отклонённые вызовы:** неизвестный или истёкший URI для вызова получает SIP `404 Not Found`. Уже использованный URI для вызова, отключённый эндпоинт или источник вне списка разрешённых (включая любой UDP-вызов на эндпоинт со списком разрешённых) отключается до запуска агента: ваша система может увидеть сбой вызова либо подключение с немедленным завершением. Такие отказы не создают запись в истории вызовов. Если у вашей организации закончились средства или достигнут лимит расходов, вызов отклоняется и отображается в истории вызовов как неуспешный вызов без списания. Чтобы повторить попытку с URI для вызова, зарегистрируйте новый URI. - **Переводы:** холодные переводы агента работают (ThunderPhone отправляет SIP `REFER`, который должна принять ваша система). Тёплые переводы недоступны для вызовов на SIP-адреса, поскольку для второго этапа нет номера ThunderPhone, который можно показать как идентификатор звонящего. При использовании Twilio указанный выше TwiML подключает агента, но не обрабатывает переводы: добавьте `referUrl="https://YOUR_SERVER/sip-transfer"` в ``, а в этом вебхуке прочитайте `ReferTransferTarget` и верните TwiML, который набирает адрес перевода (см. [руководство Twilio по SIP REFER](https://www.twilio.com/docs/voice/api/refer-to-twilio)). - **Текстовые сообщения:** SIP-адрес и набранный номер не могут отправлять сообщения. Агент может отправлять сообщения во время вызова на SIP-адрес, только если для отправки сообщений у него настроен отдельный номер с поддержкой SMS; в противном случае его инструмент SMS недоступен. - **Регистрация:** ThunderPhone не принимает SIP `REGISTER`. Отправляйте вызовы на адрес, а не регистрируйтесь на нём. ## Тарифы Вызовы на SIP-адреса тарифицируются по обычной поминутной ставке агента. Плата за номер телефона не взимается, поскольку вызов не проходит через номер ThunderPhone. Ваш оператор тарифицирует свою сторону вызова как обычно. См. [Тарифы](/ru/guides/pricing). ## Тестирование 1. Создайте URI для вызова или эндпоинт, как описано выше. 2. Наберите его из вашей системы или с любого SIP-софтфона (для эндпоинта введите имя пользователя и пароль). 3. После завершения вызова откройте его в разделе **Вызовы** на панели управления или получите через `GET /v1/calls/{call_id}`. Здесь отображаются звонящий, адрес назначения (см. порядок в разделе «Передайте набранный номер») и расшифровка. Сведения об API: [справочник API SIP-адресов](/api-reference/sip-addresses).