--- title: "Підключення через SIP (без номера телефону)" description: "Спрямовуйте дзвінки до агента ThunderPhone безпосередньо з вашої PBX, від оператора або 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}}` у промпті агента так само, як для [вихідних викликів](/uk/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` повертається лише один раз — під час створення ендпойнта. Відразу збережіть його в конфігурації своєї АТС або оператора. Якщо ви його втратите, змініть його за допомогою `POST /v1/sip-endpoints/{id}/rotate-password`. ### 2. Налаштуйте свою систему Налаштуйте SIP-транк або призначення з такими параметрами: | Налаштування | Значення | |---|---| | SIP URI | `sip_uri` ендпойнта | | Ім’я користувача / пароль | `username` / `password` (дайджест-автентифікація; 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. - **Переведення викликів:** холодне переведення, яке виконує агент, працює (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. Ваш оператор зв’язку, як зазвичай, виставляє рахунок за свою частину виклику. Див. [Ціни](/uk/guides/pricing). ## Перевірте 1. Створіть URI для окремого виклику або кінцеву точку, як описано вище. 2. Зателефонуйте на нього зі своєї системи або з будь-якого SIP-софтфона (для кінцевої точки введіть ім’я користувача та пароль). 3. Після завершення виклику відкрийте його в розділі **Виклики** на панелі керування або отримайте через `GET /v1/calls/{call_id}`. Там відображаються абонент, призначення (див. порядок у розділі «Передайте набраний номер») і транскрипт. Відомості про API: [довідник API SIP-адрес](/api-reference/sip-addresses).