Підключення через SIP (без номера телефону)

Спрямовуйте дзвінки до агента ThunderPhone безпосередньо з вашої PBX, від оператора або SIP-застосунку, використовуючи одноразовий SIP URI для кожного дзвінка або постійну SIP-адресу.

Якщо ваша система вже обробляє телефонні номери (АТС, платформа контакт-центру або обліковий запис оператора зв’язку, у якому ви змінюєте номери), ви можете надсилати виклики голосовому агенту ThunderPhone через звичайний SIP. Вам не потрібно імпортувати або купувати номер у ThunderPhone. Ваша система набирає SIP-адресу, а агент відповідає.

Існує два типи SIP-адрес:

Обидва типи спрямовують виклики до одного агента у вашій організації, і обидва відображаються в історії викликів як будь-які інші вхідні виклики.

SIP URI для кожного виклику#

1. Зареєструйте виклик#

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"}
  }'

{
  "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}} у промпті агента так само, як для вихідних викликів.
• call_id — це ідентифікатор, який матиме виклик в історії викликів (GET /v1/calls/{call_id}) після підключення.

2. Наберіть URI#

Надішліть виклик на sip_uri протягом 5 хвилин. URI працює лише для одного виклику: щойно виклик його використає, він стає недійсним, навіть якщо цей виклик швидко завершиться.

Наприклад, у Twilio поверніть цей TwiML для виклику, який потрібно передати:

<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>

З АТС наберіть URI як SIP-адресу призначення. Ім’я користувача або пароль не потрібні; токен є обліковими даними, тому поводьтеся з URI як із паролем, доки його не буде використано.

SIP-ендпойнт (постійна адреса)#

1. Створіть ендпойнт#

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"}'

{
  "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"
}

2. Налаштуйте свою систему#

Налаштуйте SIP-транк або призначення з такими параметрами:

Ці налаштування транспорту й кодеків також застосовуються до 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, щоб приймати виклики лише з власних адрес сигналізації, додатково до імені користувача та пароля:

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-адрес сигналізації), а не адреси медіатрафіку.

Що бачать абоненти та ваша система#

• Ідентифікатор абонента: частина користувача заголовка 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" до <Dial>, а цей вебхук має прочитати ReferTransferTarget і повернути TwiML, який набирає адресу переведення (див. посібник Twilio щодо SIP REFER).
• Текстові повідомлення: SIP-адреса та набраний номер не можуть надсилати текстові повідомлення. Агент може надсилати текстові повідомлення під час виклику на SIP-адресу лише за наявності окремого номера з підтримкою SMS, налаштованого для надсилання повідомлень; інакше його інструмент SMS недоступний.
• Реєстрація: ThunderPhone не приймає SIP REGISTER. Надсилайте виклики на адресу; не реєструйтеся на ній.

Ціни#

Виклики на SIP-адресу оплачуються за звичайним похвилинним тарифом агента. Плата за номер телефону не стягується, оскільки виклик не проходить через номер ThunderPhone. Ваш оператор зв’язку, як зазвичай, виставляє рахунок за свою частину виклику. Див. Ціни.

Перевірте#

1. Створіть URI для окремого виклику або кінцеву точку, як описано вище.
2. Зателефонуйте на нього зі своєї системи або з будь-якого SIP-софтфона (для кінцевої точки введіть ім’я користувача та пароль).
3. Після завершення виклику відкрийте його в розділі Виклики на панелі керування або отримайте через GET /v1/calls/{call_id}. Там відображаються абонент, призначення (див. порядок у розділі «Передайте набраний номер») і транскрипт.

Відомості про API: довідник API SIP-адрес.