ThunderPhone 2.0 este acum disponibil.Self-service, de la 2 ¢/min.Citiți anunțul

Developer cookbook

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 apelEndpoint SIP
Arată casip:c-<token>@sip.thunderphone.comsip:agent-<id>-<letters>@sip.thunderphone.com
Creat cuPOST /v1/calls/register-sip, o dată per apelPOST /v1/sip-endpoints, o dată
AutentificareJetonul 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 pentruAplicații care apelează deja un API înainte de a transfera un apel; variabile per apelPBX-uri și operatori care trebuie doar să „direcționeze un trunk” către ThunderPhone
Valabil pentru5 minute, un apelPâ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_id este 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:

SetareValoare
URI SIPsip_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)
TransportTCP pe portul 5060 sau TLS pe portul 5061 (recomandat), ori UDP pe portul 5060
CodecuriG.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.com sau sip-2.thunderphone.com, ori adresa sa IP). Dacă restricționați SIP-ul de ieșire, permiteți aceste gazde, precum și sip.thunderphone.com: 172.170.39.202 (sip), 13.86.104.121 (sip-1) și 20.80.98.90 (sip-2).
  • Audio-ul merge în altă parte. sip.thunderphone.com transportă 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-ConnectContactId sau X-Intent), cu excepția X-TP-* și X-LK-*, pe care propriile servere SIP ale ThunderPhone le utilizează și care sunt eliminate întotdeauna;
  • User-to-User (UUI). O valoare marcată cu ;encoding=hex este 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 _:

AntetVariabilă
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) sau null pentru 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_id al 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ă) și X-Genesys-Conversation-Id. Când agentul redirecționează apelul înapoi către platforma dumneavoastră, GET /v1/calls/handoff găsește apelul după acesta.
  • Webhookuri: evenimentul telephony.incoming include sip_headers atunci 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 From este 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 ca anonymous.
  • 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 în BYE; 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ți referUrl="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

  1. Creați un URI per apel sau un endpoint, ca mai sus.
  2. Apelați-l din sistemul dumneavoastră sau din orice softphone SIP (pentru un endpoint digest, introduceți numele de utilizator și parola; un endpoint ip_allowlist răspunde doar apelurilor din intervalele sale permise).
  3. 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.