Open in
Conectați-vă prin SIP (fără număr de telefon)
Trimiteți apeluri către un agent ThunderPhone direct din PBX-ul, operatorul sau aplicația SIP, folosind un URI SIP unic pentru fiecare apel sau o adresă SIP permanentă.
Dacă propriul dumneavoastră sistem gestionează deja numere de telefon (un PBX, o platformă de centru de contact sau un cont de operator în care rotiți numerele), puteți trimite apeluri către un agent ThunderPhone prin SIP standard. Nu importați și nu cumpărați un număr pe ThunderPhone. Sistemul dumneavoastră apelează o adresă SIP, iar agentul răspunde.
Există două tipuri de adrese SIP:
| URI SIP per apel | Endpoint SIP | |
|---|---|---|
| Arată ca | sip:c-<token>@sip.thunderphone.com | sip:agent-<id>-<letters>@sip.thunderphone.com |
| Creat cu | POST /v1/calls/register-sip, o dată per apel | POST /v1/sip-endpoints, o dată |
| Autentificare | Jetonul de unică folosință din adresă | Nume de utilizator și parolă SIP digest (și, opțional, o listă de permisiuni pentru IP-uri sursă) sau doar o listă de permisiuni pentru IP-uri sursă pentru platformele care se autentifică prin IP |
| Potrivit pentru | Aplicații care apelează deja un API înainte de a transfera un apel; variabile per apel | PBX-uri și operatori care trebuie doar să „direcționeze un trunk” către ThunderPhone |
| Valabil pentru | 5 minute, un apel | Până îl ștergeți |
Ambele tipuri sunt direcționate către un agent din organizația dumneavoastră și ambele apar în istoricul apelurilor ca orice alt apel primit.
URI SIP per apel
1. Înregistrați apelul
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(opțional) este numărul apelat de apelant în sistemul dumneavoastră. Acesta este stocat ca destinație a apelului în istoricul apelurilor, iar agentul îl vede ca propriul său număr.variables(opțional) completează{{placeholders}}din promptul agentului, în același mod ca pentru apelurile efectuate.call_ideste identificatorul pe care îl va avea apelul în istoricul apelurilor (GET /v1/calls/{call_id}) după conectare.
2. Apelați URI-ul
Trimiteți apelul către sip_uri în decurs de 5 minute. URI-ul funcționează pentru un singur apel:
după ce un apel îl utilizează, acesta este consumat, chiar dacă apelul se încheie rapid.
Cu Twilio, de exemplu, returnați acest TwiML pentru apelul pe care doriți să îl transferați:
<Response>
<Dial>
<Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
</Dial>
</Response>Dintr-un PBX, apelați URI-ul ca destinație SIP. Nu este necesar niciun nume de utilizator sau parolă; jetonul este acreditarea, așadar tratați URI-ul ca pe o parolă până când a fost utilizat.
Endpoint SIP (adresă permanentă)
1. Creați endpointul
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. Direcționați sistemul către acesta
Configurați un trunk SIP sau o destinație cu:
| Setare | Valoare |
|---|---|
| URI SIP | sip_uri al endpointului |
| Nume de utilizator / parolă | username / password (autentificare digest; ThunderPhone solicită autentificarea pentru fiecare apel). Niciunul pentru un endpoint ip_allowlist (mai jos) |
| Transport | TCP pe portul 5060 sau TLS pe portul 5061 (recomandat), ori UDP pe portul 5060 |
| Codecuri | G.711 (PCMU/PCMA) sau G.722 |
Aceste setări de transport și codecuri se aplică și URI-urilor per apel. Două detalii de rețea sunt importante pentru ambele tipuri de adresă:
- Respectați Record-Route. După primul INVITE, restul semnalizării apelului
(ACK, închidere, transferuri) este trimis către serverul ThunderPhone specific
care a răspuns, numit în antetul
Record-Route(sip-1.thunderphone.comsausip-2.thunderphone.com, ori adresa sa IP). Dacă restricționați SIP-ul de ieșire, permiteți aceste gazde, precum șisip.thunderphone.com:172.170.39.202(sip),13.86.104.121(sip-1) și20.80.98.90(sip-2). - Audio-ul merge în altă parte.
sip.thunderphone.comtransportă doar semnalizarea. Permiteți media (RTP) către adresele și porturile din răspunsul SDP.
Fiecare apel către adresă ajunge la agentul vocal al endpointului, indiferent ce număr a format apelantul de partea dumneavoastră. Nu importați niciodată numere, astfel că rotirea lor de partea dumneavoastră nu necesită nicio modificare în ThunderPhone.
Transmiteți numărul format (opțional)
Pentru a înregistra care dintre numerele dumneavoastră a fost format de apelant, trimiteți-l în INVITE într-un
antet X-Original-To (de exemplu X-Original-To: +14155550142) sau într-un
antet standard Diversion. ThunderPhone îl stochează drept destinația apelului.
Destinația este aleasă în această ordine: to_number furnizat la înregistrarea unui
URI per apel, apoi un număr din X-Original-To, apoi unul din Diversion.
Dacă niciuna dintre acestea nu oferă un număr, este afișată ca sip:agent-12-jhxmginwjx (adresa
endpointului) pentru un endpoint sau ca sip:call pentru un URI per apel.
Cu Twilio puteți adăuga antetul la URI-ul SIP:
sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142.
Restricționați IP-urile sursă (opțional)
Setați allowed_source_cidrs pentru a accepta apeluri numai de la adresele dumneavoastră
de semnalizare, pe lângă numele de utilizator și parolă:
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"]}'Apelurile de la orice altă adresă sunt refuzate înainte să ajungă la agentul vocal. Folosiți adresele de la care sistemul dumneavoastră trimite semnalizarea SIP (pentru un operator precum Twilio, intervalele sale publicate de IP-uri de semnalizare), nu adresele media.
Platforme care se autentifică prin IP-ul sursă
Unele platforme de centre de contact, precum Talkdesk, Amazon Connect și Amazon
Chime Voice Connector, se identifică doar prin adresele de la care trimit SIP
și nu documentează autentificarea cu parolă. Pentru acestea, creați
endpointul cu auth setat la ip_allowlist și enumerați intervalele de
semnalizare SIP ale platformei:
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"]
}'Răspunsul conține "username": null și nu conține password. Direcționați
platforma către sip_uri prin TLS (portul 5061) sau TCP (portul 5060): un
endpoint ip_allowlist refuză toate apelurile prin UDP, deoarece o adresă
sursă UDP poate fi falsificată.
Lista trebuie să conțină cel puțin o intrare. Fiecare intrare trebuie să fie
un interval IPv4 public de /16 sau mai restrâns ori un interval IPv6 de
/48 sau mai restrâns. Utilizați intervalele de semnalizare publicate de
platformă pentru regiunile pe care le utilizați, nu intervalele sale media și
nici intervalele întregului furnizor de cloud.
Pentru a schimba un endpoint existent, aplicați PATCH cu auth (și
allowed_source_cidrs dacă lista sa nu respectă aceste reguli). Revenirea la
digest returnează o parolă nouă o singură dată.
Platforme care apelează un număr de telefon
Five9, NICE CXone și Zoom Contact Center trimit un apel către un număr de telefon și
nu pot apela adresa agent-… a endpointului. Configurați un endpoint ip_allowlist
cu până la 5 dial_in_numbers: platforma își trimite apoi INVITE-ul către
sip:<number>@sip.thunderphone.com și ajunge la agentul endpointului. Zoom
Contact Center necesită și TLS cu SRTP, deci setați srtp la required (SRTP,
la fel ca numerele de acces, este disponibil numai pentru endpointurile 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"
}'Înlocuiți intervalele din exemplu (adrese de documentație, pe care API-ul le refuză)
cu intervalele de semnalizare SIP ale platformei dumneavoastră. Introduceți fiecare
număr exact așa cum îl apelează platforma, cu sau fără +
(numerele Zoom 999… cu 15 cifre nu îl includ); spațiile, cratimele și parantezele
sunt eliminate. Un număr este tratat ca o adresă, nu ca o parolă: apelurile către
acesta sunt verificate în raport cu allowed_source_cidrs și trebuie să sosească
prin TCP sau TLS, la fel ca apelurile către sip_uri. Un număr nu poate fi deja
utilizat pe ThunderPhone, ca număr de telefon sau pe un alt endpoint SIP; crearea
sau actualizarea cu unul returnează 409. Pentru a modifica lista, aplicați PATCH
endpointului cu întreaga listă nouă dial_in_numbers.
Apelurile către un număr de acces sunt apeluri la adrese SIP: niciun număr
ThunderPhone nu le direcționează, deci nu apar la numerele de telefon și nu au
taxă pentru număr de telefon. Destinația apelului este numărul din X-Original-To
sau Diversion când platforma trimite unul, altfel numărul de acces.
Transmiteți contextul apelului în antetele SIP
O platformă de centru de contact sau un PBX cunoaște de obicei informații despre apel înainte ca acesta să ajungă la agentul vocal: propriul identificator al apelului sau al contactului, ce a ales apelantul în IVR, numărul de cont introdus. Trimiteți-le ca antete SIP în INVITE, iar agentul vocal le poate utiliza.
ThunderPhone citește două tipuri de antete:
- fiecare antet al cărui nume începe cu
X-(de exemplu,X-Amzn-ConnectContactIdsauX-Intent), cu excepțiaX-TP-*șiX-LK-*, pe care propriile servere SIP ale ThunderPhone le utilizează și care sunt eliminate întotdeauna; User-to-User(UUI). O valoare marcată cu;encoding=hexeste decodificată ca text atunci când se decodifică în UTF-8; valoarea trimisă este păstrată, de asemenea.
Aceasta funcționează cu ambele tipuri de adresă SIP și cu numere importate printr-o conexiune SIP manuală. Nu se aplică numerelor ThunderPhone sau numerelor dintr-o conexiune Twilio ori Telnyx.
Utilizați-le în prompt
Fiecare antet devine o variabilă de apel numită sip_
urmată de numele antetului cu litere mici, fiecare secvență de caractere care nu sunt
litere sau cifre fiind transformată într-un singur _:
| Antet | Variabilă |
|---|---|
X-Amzn-ConnectContactId | {{sip_x_amzn_connectcontactid}} |
X-Intent | {{sip_x_intent}} |
User-to-User | {{sip_uui}} (decodificat) și {{sip_uui_raw}} (așa cum a fost trimis, numai dacă a fost codificat hexazecimal) |
Un antet ajunge la agentul vocal numai atunci când promptul său îl menționează; altfel,
nu se adaugă nimic la conversație. O variabilă cu același nume din
register-sip sau din webhook-ul dumneavoastră de configurare a apelului
are prioritate față de antet. Oferiți fiecărui substituent o valoare implicită
({{sip_x_intent|unknown}}), astfel încât apelurile fără antet să fie în continuare formulate bine.
Limite
Maximum 32 de antete per apel, 1,024 caractere per valoare și 8 KB în total; antetele care depășesc aceste limite sunt eliminate. Caracterele de control sunt eliminate.
Unde apar
- Istoricul apelurilor:
GET /v1/calls/{call_id}returneazăsip_headers(numele antetului cu litere mici → valoare) saunullpentru un apel fără antete. - ID-ul apelului din platforma dumneavoastră: primul dintre aceste antete pe care le-a avut apelul este stocat ca
external_call_idal apelului:X-Amzn-ConnectContactId(Amazon Connect),x-inin-cnv(Genesys Cloud, cu setarea Conversation Headers a trunkului activată),X-Talkdesk-Interaction-Id(Talkdesk),X-ZOOM-Call-Sid(Zoom Contact Center),X-CallID(Five9),X-Call-ID(setați-l dumneavoastră pe orice altă platformă) șiX-Genesys-Conversation-Id. Când agentul redirecționează apelul înapoi către platforma dumneavoastră,GET /v1/calls/handoffgăsește apelul după acesta. - Webhookuri: evenimentul
telephony.incomingincludesip_headersatunci când apelul a avut astfel de antete. Pentru numerele de pe o conexiune SIP manuală, le includ și cererea de configurare a apelului blocantă, precum și webhookul de configurare a apelului agentului.
Ce văd apelanții și sistemul dumneavoastră
- ID apelant: partea de utilizator din antetul
Fromeste stocată ca apelant. Un număr de telefon (cifre, opțional cu+, spații, cratime, puncte sau paranteze) este normalizat la E.164; orice altceva, cum ar fi un nume de utilizator SIP, este păstrat așa cum a fost trimis. Se păstrează cel mult 32 de caractere, iar un apelant lipsă este stocat caanonymous. - Apeluri refuzate: un URI necunoscut sau expirat pentru fiecare apel primește SIP
404 Not Found. Un URI pentru fiecare apel deja utilizat, un endpoint dezactivat sau o sursă din afara listei de permise (inclusiv orice apel UDP către un endpoint cu o listă de permise) este deconectată înainte ca agentul să pornească: sistemul dumneavoastră poate vedea apelul eșuând sau conectându-se și apoi încheindu-se imediat. Aceste refuzuri nu creează o înregistrare în istoricul apelurilor. Dacă organizația dumneavoastră nu mai are credit sau a atins limita de cheltuieli, apelul este refuzat și apare în istoricul apelurilor ca apel eșuat, fără cost. Pentru a reîncerca o tentativă pentru fiecare apel, înregistrați un URI nou. - Transferuri: transferurile la rece ale agentului funcționează (ThunderPhone trimite un SIP
REFER, pe care sistemul dumneavoastră trebuie să îl accepte). Un număr de transfer poate fi și o adresă SIP din sistemul dumneavoastră, cum ar fi o coadă, cu antete SIP pe care aceasta să le citească; consultați Transfer către o adresă SIP. Agentul poate, de asemenea, să returneze apelul închizând apelul cu antete de rutare înBYE; consultați Returnați apelul către centrul dumneavoastră de contact. Transferurile asistate nu sunt disponibile pentru apelurile către adrese SIP, deoarece nu există un număr ThunderPhone care să fie afișat ca ID apelant pentru a doua etapă. Cu Twilio, TwiML-ul de mai sus conectează agentul, dar nu gestionează transferurile: adăugațireferUrl="https://YOUR_SERVER/sip-transfer"la<Dial>și faceți ca acel webhook să citeascăReferTransferTargetși să returneze TwiML care apelează destinația transferului (consultați ghidul Twilio SIP REFER). - Mesaje text: adresa SIP și numărul apelat nu pot trimite mesaje text. Agentul poate trimite mesaje text în timpul unui apel către o adresă SIP numai dacă are configurat un număr separat capabil de SMS pentru mesagerie; în caz contrar, instrumentul său SMS este indisponibil.
- Înregistrare: ThunderPhone nu acceptă SIP
REGISTER. Trimiteți apelurile către adresă; nu vă înregistrați la aceasta.
Prețuri
Apelurile către adrese SIP sunt facturate ca orice alt apel. Nu există o componentă de linie telefonică, deoarece niciun număr ThunderPhone nu preia apelul. Operatorul dumneavoastră facturează partea sa din apel în mod obișnuit. Consultați Prețuri.
Testați-l
- Creați un URI per apel sau un endpoint, ca mai sus.
- Apelați-l din sistemul dumneavoastră sau din orice softphone SIP (pentru un endpoint
digest, introduceți numele de utilizator și parola; un endpointip_allowlistrăspunde doar apelurilor din intervalele sale permise). - După încheierea apelului, deschideți apelul în Apeluri din tabloul de bord sau preluați-l cu
GET /v1/calls/{call_id}. Sunt afișate apelantul, destinația (consultați ordinea din „Transmiteți numărul apelat”) și transcrierea.
Detalii API: referința API pentru adrese SIP.