ThunderPhone 2.0 je tu.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Developer cookbook

Povežite se prek SIP (brez telefonske številke)

Klice usmerite do glasovnega agenta ThunderPhone neposredno iz svojega sistema PBX, pri operaterju ali iz aplikacije SIP z enkratnim URI-jem SIP za posamezen klic ali s stalnim naslovom SIP.

Če vaš sistem že upravlja telefonske številke (PBX, platforma kontaktnega centra ali račun pri operaterju, kjer menjate številke), lahko klice pošiljate glasovnemu agentu ThunderPhone prek običajnega SIP-a. V ThunderPhone ne uvozite ali kupite številke. Vaš sistem pokliče naslov SIP in agent se oglasi.

Obstajata dve vrsti naslovov SIP:

SIP URI za posamezen klicSIP-končna točka
Oblikasip:c-<token>@sip.thunderphone.comsip:agent-<id>-<letters>@sip.thunderphone.com
Ustvarjeno zPOST /v1/calls/register-sip, enkrat za vsak klicPOST /v1/sip-endpoints, enkrat
Preverjanje pristnostiEnkratni žeton v naslovuUporabniško ime in geslo za SIP digest (ter po želji seznam dovoljenih izvornih naslovov IP) ali samo seznam dovoljenih izvornih naslovov IP za platforme, ki preverjajo pristnost po naslovu IP
Primerno zaAplikacije, ki pred preusmeritvijo klica že pokličejo API; spremenljivke za posamezen klicPBX-sisteme in operaterje, ki morajo zgolj »usmeriti trunk« v ThunderPhone
Velja5 minut, en klicDo izbrisa

Obe vrsti usmerjata k enemu agentu v vaši organizaciji in obe se v zgodovini klicev prikažeta kot vsak drug dohodni klic.

SIP URI za posamezen klic

1. Registrirajte klic

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 (izbirno) je številka, ki jo je klicatelj poklical na vaši strani. Shrani se kot cilj klica v zgodovini klicev, agent pa jo vidi kot svojo številko.
  • variables (izbirno) izpolnijo {{placeholders}} v pozivu agenta na enak način kot pri odhodnih klicih.
  • call_id je ID, ki ga bo imel klic v zgodovini klicev (GET /v1/calls/{call_id}), ko se poveže.

2. Pokličite URI

Klic pošljite na sip_uri v 5 minutah. URI deluje samo za en klic: ko ga klic uporabi, je porabljen, tudi če se ta klic hitro konča.

V storitvi Twilio na primer za klic, ki ga želite predati, vrnite ta TwiML:

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

Iz PBX-a URI pokličite kot cilj SIP. Uporabniško ime ali geslo ni potrebno; žeton je poverilnica, zato z URI-jem ravnajte kot z geslom, dokler ni uporabljen.

SIP-končna točka (stalni naslov)

1. Ustvarite končno točko

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",
  "auth": "digest",
  "username": "tp409667538f83",
  "password": "8mJ0…",
  "allowed_source_cidrs": [],
  "status": "active",
  "created_at": "2026-09-25T21:46:18Z"
}

2. Usmerite svoj sistem nanjo

Konfigurirajte SIP-trunk ali cilj z naslednjimi nastavitvami:

NastavitevVrednost
SIP URIsip_uri končne točke
Uporabniško ime / geslousername / password (preverjanje pristnosti z digestom; ThunderPhone preveri vsak klic). Ni potrebno za končno točko ip_allowlist (spodaj)
TransportTCP na vratih 5060 ali TLS na vratih 5061 (priporočeno) ali UDP na vratih 5060
KodekiG.711 (PCMU/PCMA) ali G.722

Te nastavitve transporta in kodekov veljajo tudi za URI-je posameznih klicev. Za obe vrsti naslovov sta pomembni dve omrežni podrobnosti:

  • Upoštevajte Record-Route. Po prvem INVITE preostala signalizacija klica (ACK, prekinitev, preusmeritve) poteka do določenega strežnika ThunderPhone, ki je odgovoril in je naveden v glavi Record-Route (sip-1.thunderphone.com ali sip-2.thunderphone.com oziroma njegov naslov IP). Če omejujete odhodni SIP, dovolite te gostitelje in sip.thunderphone.com: 172.170.39.202 (sip), 13.86.104.121 (sip-1) in 20.80.98.90 (sip-2).
  • Zvok poteka drugje. sip.thunderphone.com prenaša samo signalizacijo. Dovolite medijski promet (RTP) do naslovov in vrat v odgovoru SDP.

Vsak klic na naslov doseže agenta končne točke, ne glede na to, katero številko je klicatelj poklical na vaši strani. Številk nikoli ne uvozite, zato njihova zamenjava na vaši strani ne zahteva sprememb v ThunderPhone.

Posredujte poklicano številko (izbirno)

Če želite zabeležiti, katero od svojih številk je klicatelj poklical, jo pošljite v INVITE v glavi X-Original-To (na primer X-Original-To: +14155550142) ali v standardni glavi Diversion. ThunderPhone jo shrani kot cilj klica.

Cilj je izbran v tem vrstnem redu: to_number, podan ob registraciji URI-ja posameznega klica, nato številka v X-Original-To, nato številka v Diversion. Če nobena od teh možnosti ne poda številke, je za končno točko prikazano sip:agent-12-jhxmginwjx (naslov končne točke), za URI posameznega klica pa sip:call.

S storitvijo Twilio lahko glavo dodate v SIP URI: sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142.

Omejite izvorne naslove IP (izbirno)

Nastavite allowed_source_cidrs, da poleg uporabniškega imena in gesla sprejemate klice samo z lastnih naslovov za signalizacijo:

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

Klici z vseh drugih naslovov so zavrnjeni, preden dosežejo agenta. Uporabite naslove, s katerih vaš sistem pošilja signalizacijo SIP (pri operaterju, kot je Twilio, njegove objavljene obsege naslovov IP za signalizacijo), in ne svojih medijskih naslovov.

Platforme, ki preverjajo pristnost z izvornim IP-jem

Nekatere platforme za kontaktne centre, kot so Talkdesk, Amazon Connect in Amazon Chime Voice Connector, se prepoznajo samo po naslovih, s katerih pošiljajo SIP, in ne dokumentirajo preverjanja pristnosti z geslom. Za te ustvarite končno točko z možnostjo auth, nastavljeno na ip_allowlist, in navedite obsege signalizacije SIP platforme:

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": "Amazon Chime",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["3.80.16.0/23", "99.77.253.0/24"]
  }'

Odgovor vsebuje "username": null in nima password. Platformo usmerite na sip_uri prek TLS (vrata 5061) ali TCP (vrata 5060): končna točka ip_allowlist zavrne vsak klic prek UDP, ker je mogoče izvorni naslov UDP ponarediti.

Seznam mora imeti vsaj en vnos. Vsak mora biti javni obseg IPv4 z masko /16 ali ožjo oziroma obseg IPv6 z masko /48 ali ožjo. Uporabite obsege signalizacije, ki jih platforma objavlja za regije, ki jih uporabljate, ne njenih medijskih obsegov in ne obsegov celotnega ponudnika oblaka.

Če želite preklopiti obstoječo končno točko, jo posodobite s PATCH z možnostjo auth (in allowed_source_cidrs, če njen seznam ne izpolnjuje teh pravil). Preklop nazaj na digest enkrat vrne novo geslo.

Platforme, ki kličejo telefonsko številko

Five9, NICE CXone in Zoom Contact Center pošljejo klic na telefonsko številko in ne morejo klicati naslova agent-… končne točke. Končni točki z ip_allowlist dodelite do 5 dial_in_numbers: platforma nato pošlje svoj INVITE na sip:<number>@sip.thunderphone.com in doseže glasovnega agenta končne točke. Zoom Contact Center potrebuje tudi TLS s SRTP, zato nastavite srtp na required (SRTP je tako kot številke za dohodno klicanje na voljo samo za končne točke z ip_allowlist):

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": "Zoom Contact Center",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["203.0.113.0/24", "198.51.100.0/24"],
    "dial_in_numbers": ["999123456789012"],
    "srtp": "required"
  }'

Primerne obsege (naslove iz dokumentacije, ki jih API zavrne) zamenjajte s SIP-signalizacijskimi obsegi svoje platforme. Vsako številko vnesite natanko tako, kot jo kliče platforma, z + ali brez njega (Zoomove 15-mestne številke 999… ga nimajo); presledki, pomišljaji in oklepaji se odstranijo. Številka se obravnava kot naslov, ne kot geslo: klici nanjo se preverijo glede na allowed_source_cidrs in morajo prispeti prek TCP ali TLS, enako kot klici na sip_uri. Številka ne sme biti že v uporabi v ThunderPhone, kot telefonska številka ali na drugi končni točki SIP; ustvarjanje ali posodabljanje s takšno številko vrne 409. Če želite spremeniti seznam, končni točki pošljite PATCH s celotnim novim dial_in_numbers.

Klici na številko za dohodno klicanje so klici na naslove SIP: ne prenaša jih nobena številka ThunderPhone, zato niso prikazani med telefonskimi številkami in zanje ni stroška telefonske številke. Cilj klica je številka v X-Original-To ali Diversion, kadar jo platforma pošlje, sicer pa številka za dohodno klicanje.

Posredujte kontekst klica v glavah SIP

Platforma kontaktnega centra ali PBX običajno pozna določene informacije o klicu, preden ta doseže agenta: lasten ID klica ali stika, izbiro klicatelja v IVR-ju, številko računa, ki jo je vnesel. Pošljite jih kot glave SIP v povabilu INVITE, da jih lahko agent uporabi.

ThunderPhone prebere dve vrsti glav:

  • vsako glavo, katere ime se začne z X- (na primer X-Amzn-ConnectContactId ali X-Intent), razen X-TP-* in X-LK-*, ki ju uporabljajo lastni SIP-strežniki ThunderPhone in se vedno zavržeta;
  • User-to-User (UUI). Vrednost, označena z ;encoding=hex, se dekodira v besedilo, kadar se dekodira v UTF-8; ohrani se tudi poslana vrednost.

To deluje pri obeh vrstah SIP-naslovov in pri številkah, uvoženih prek ročne povezave SIP. Ne velja za številke ThunderPhone ali številke v povezavi Twilio ali Telnyx.

Uporabite jih v pozivu

Vsaka glava postane spremenljivka klica z imenom sip_ in imenom glave z malimi črkami, pri čemer se vsak niz znakov, ki niso črke ali števke, pretvori v en _:

GlavaSpremenljivka
X-Amzn-ConnectContactId{{sip_x_amzn_connectcontactid}}
X-Intent{{sip_x_intent}}
User-to-User{{sip_uui}} (dekodirano) in {{sip_uui_raw}} (kot poslano, samo kadar je bilo kodirano šestnajstiško)

Glava doseže agenta samo, kadar je navedena v njegovem pozivu; sicer se pogovoru ne doda nič. Spremenljivka z enakim imenom iz register-sip ali iz vašega spletnega kavlja za nastavitev klica ima prednost pred glavo. Vsakemu nadomestnemu znaku določite privzeto vrednost ({{sip_x_intent|unknown}}), da se klici brez glave še vedno berejo naravno.

Omejitve

Na klic je dovoljenih največ 32 glav, 1.024 znakov na vrednost in skupaj 8 KB; glave, ki presegajo te omejitve, se zavržejo. Kontrolni znaki se odstranijo.

Kje se prikažejo

  • Zgodovina klicev: GET /v1/calls/{call_id} vrne sip_headers (ime glave z malimi črkami → vrednost) ali null za klic brez njih.
  • ID klica vaše platforme: prvi od teh naslovov, ki jih je klic vseboval, je shranjen kot external_call_id klica: X-Amzn-ConnectContactId (Amazon Connect), x-inin-cnv (Genesys Cloud z vključeno nastavitvijo Conversation Headers za trunk), X-Talkdesk-Interaction-Id (Talkdesk), X-ZOOM-Call-Sid (Zoom Contact Center), X-CallID (Five9), X-Call-ID (nastavite ga sami na kateri koli drugi platformi) in X-Genesys-Conversation-Id. Ko agent preda klic nazaj vaši platformi, GET /v1/calls/handoff poišče klic po njem.
  • Spletni kavlji: dogodek telephony.incoming vključuje sip_headers, kadar jih je klic vseboval. Za številke pri ročni povezavi SIP ju vključujeta tudi blokirajoča zahteva za konfiguracijo klica in spletni kavelj za nastavitev klica agenta.

Kaj vidijo klicatelji in vaš sistem

  • ID klicatelja: uporabniški del glave From se shrani kot klicatelj. Telefonska številka (števke, po želji z znakom +, presledki, vezaji, pikami ali oklepaji) se normalizira v E.164; vse drugo, na primer uporabniško ime SIP, se ohrani, kot je poslano. Ohrani se največ 32 znakov, manjkajoči klicatelj pa se shrani kot anonymous.
  • Zavrnjeni klici: neznani ali potekli URI za posamezen klic prejme SIP 404 Not Found. URI za posamezen klic, ki je že bil uporabljen, onemogočena končna točka ali vir zunaj seznama dovoljenih (vključno z vsakim klicem UDP na končno točko s seznamom dovoljenih) se prekine pred zagonom agenta: vaš sistem lahko zazna neuspeh klica ali pa se klic poveže in nato takoj konča. Te zavrnitve ne ustvarijo vnosa v zgodovini klicev. Če vaši organizaciji zmanjka dobroimetja ali je dosegla omejitev porabe, se klic zavrne in se v zgodovini klicev prikaže kot neuspešen klic brez zaračunanega stroška. Če želite ponoviti poskus posameznega klica, registrirajte nov URI.
  • Prenosi: hladni prenosi agenta delujejo (ThunderPhone pošlje SIP REFER, ki ga mora vaš sistem sprejeti). Številka za prenos je lahko tudi naslov SIP v vašem sistemu, na primer čakalna vrsta, z glavami SIP, ki jih lahko prebere; glejte Prenos na naslov SIP. Agent lahko klic tudi vrne tako, da prekine povezavo z usmerjevalnimi glavami v BYE; glejte Vrnitev klica v vaš kontaktni center. Topli prenosi niso na voljo pri klicih na naslov SIP, ker ni številke ThunderPhone, ki bi jo bilo mogoče prikazati kot ID klicatelja za drugo povezavo. Pri Twilio zgornji TwiML poveže agenta, vendar ne upravlja prenosov: dodajte referUrl="https://YOUR_SERVER/sip-transfer" v <Dial> in naj ta webhook prebere ReferTransferTarget ter vrne TwiML, ki pokliče cilj prenosa (glejte Twiliojev vodnik za SIP REFER).
  • Besedilna sporočila: naslov SIP in klicana številka ne moreta pošiljati besedilnih sporočil. Agent lahko med klicem na naslov SIP pošilja besedilna sporočila le, če ima za pošiljanje sporočil nastavljeno ločeno številko, ki podpira SMS; sicer njegovo orodje za SMS ni na voljo.
  • Registracija: ThunderPhone ne sprejema SIP REGISTER. Klice pošljite na naslov; ne registrirajte se nanj.

Cene

Klici na naslove SIP se obračunajo kot vsi drugi klici. Del za telefonsko linijo ni vključen, ker klica ne prenaša nobena številka ThunderPhone. Vaš lastni operater svojo stran klica zaračuna kot običajno. Glejte Cenik.

Preizkusite

  1. Ustvarite URI za posamezen klic ali končno točko, kot je opisano zgoraj.
  2. Pokličite ga iz svojega sistema ali iz katere koli programske opreme SIP (za končno točko digest vnesite uporabniško ime in geslo; končna točka ip_allowlist sprejema klice samo iz dovoljenih obsegov).
  3. Po koncu klica ga odprite v razdelku Klici na nadzorni plošči ali ga pridobite z GET /v1/calls/{call_id}. Prikazani so klicatelj, cilj (glejte vrstni red v razdelku »Posredujte klicano številko«) in prepis.

Podrobnosti API-ja: referenca API-ja za naslove SIP.