Getting Started

Concepte de bază

O hartă a tuturor elementelor din platformă — ce face fiecare obiect, unde se află în tabloul de bord și ce API îl accesează.

ThunderPhone este o platformă completă pentru crearea, rularea și îmbunătățirea agenților vocali cu IA. Această pagină este harta: fiecare concept pe care îl veți întâlni, câte o secțiune scurtă pentru fiecare, cu interfața din tabloul de bord și API-ul care o susține. Parcurgeți-o o dată, apoi reveniți ori de câte ori un termen necesită explicații.

Bara laterală a tabloului de bord reflectă această structură:

Organizații#

O organizație este unitatea de găzduire separată. Toate celelalte resurse — agenți, numere de telefon, apeluri, chei — aparțin exact unei organizații. Contul dumneavoastră poate aparține mai multor organizații; fiecare are propriul sold, propriile chei și propria listă de membri.

Cheia API sk_live_ pe care o creați în Organizație → Chei este asociată unei organizații. Această asociere face ca API-ul REST să fie atât de simplu: nu introduceți niciodată un ID de organizație în căile URL, deoarece cheia dumneavoastră o identifică deja.

În tabloul de bord: selectorul de organizație (în subsolul barei laterale) și setările Organizație — file pentru Contul meu, General, Chei, Alerte, Setări de facturare și Istoric facturare. Consultați referința pentru setările organizației.

În API: /v1/orgs, /v1/developer/api-keys.

Agenți#

Un agent este configurația de IA care gestionează un apel. Acesta include:

• Un prompt care stabilește ce spune agentul și cum se comportă — inclusiv acțiuni în apel, precum transferuri, apăsări de taste și închideri de apel, care sunt linii simple în prompt, nu configurații separate.
• Un nivel de motor (spark, bolt, storm-*): Spark este optimizat pentru cost, Bolt pentru viteză, iar Storm pentru inteligență în cazul prompturilor complexe.
• O voce, o limbă principală și limbi suplimentare opționale — agentul schimbă automat limba atunci când apelantul schimbă limba. Consultați Limbile acceptate.
• Capacități atașate: aplicații conectate, conexiuni API, baze de cunoștințe, servere MCP și instrumente de funcții integrate.
• Setări de comportament: ordinea vorbirii, modul de confirmare, pista de fundal, timpul-limită pentru așteptare.

Modificările din builder se salvează automat într-o schiță; nimic nu devine activ până când nu faceți clic pe Publicare. Fiecare publicare este salvată ca instantaneu în fila Istoric a builderului, astfel încât să puteți inspecta și restaura orice versiune anterioară.

În tabloul de bord: Agenți vocali → builderul de agenți (/dashboard/agents). Consultați Creați primul agent vocal.

În API: /v1/agents — CRUD, duplicare, transfer, istoric al versiunilor și ajutoare pentru prompturi.

Voci#

Biblioteca de voci conține vocile pe care le poate utiliza un agent, mostrele lor care pot fi redate, limbile compatibile, grupările după gen și accent, precum și orice suprataxă pentru voci sau limbi premium. Un instrument de testare contra cost poate sintetiza propria frază de 1–500 de caractere înainte de a alege.

Organizațiile eligibile pot crea și voci personalizate dintr-o mostră WAV sau MP3 scurtă. Vocile personalizate au o cotă și un status de creare asincron; odată pregătite, apar în același selector de agenți ca vocile din bibliotecă.

În tabloul de bord: Voci (/dashboard/voices). Consultați Biblioteca de voci și vocile personalizate.

În API: /v1/voices, mostre vocale și voci personalizate.

Numere de telefon#

Un număr de telefon aparține unei organizații și direcționează apelurile primite către un agent (și poate transporta apeluri efectuate). Există două surse:

• Numere demo — numere reale din SUA, furnizate din grupul de numere al ThunderPhone, active în câteva secunde. Doar pentru apeluri primite, răspund cu o scurtă declinare a responsabilității rostită, iar tabloul de bord limitează o organizație la 10 astfel de numere. Perfecte pentru un prim test; nu pentru producție.
• Numere VoIP — aduse de la propriul furnizor printr-o conexiune VoIP. Twilio și Telnyx se conectează direct (Telnyx are o configurare ghidată); SignalWire și Vonage vor fi disponibile în curând — în prezent le puteți utiliza prin configurare SIP manuală, care acceptă orice trunchi SIP. După importare și verificare, numerele VoIP acceptă apeluri primite și efectuate.

Fiecare rând de număr vă permite să setați un mod de rutare, să selectați agentul pentru apelurile primite și să etichetați numărul.

În tabloul de bord: Numere de telefon (/dashboard/phone-numbers). Consultați Obțineți un număr de telefon.

În API: /v1/phone-numbers, /v1/voip-connections, /v1/phone-number-labels.

Apeluri#

Fiecare apel primit, apel efectuat, simulare și sesiune de widget devine un jurnal de apeluri. Un apel include transcrierea completă cu roluri etichetate, istoricul structurat al schimburilor de replici (inclusiv apelurile de instrumente), o înregistrare, totalul facturării și, opțional, evaluări AI și rapoarte de probleme.

Cât timp un apel este în desfășurare, îl puteți deschide și asculta în direct — vă alăturați în mod silențios, iar nimeni din apel nu vă aude. După ce ascultați, puteți șopti: introduceți o instrucțiune care ajunge direct la agentul dumneavoastră în timpul apelului; apelantul nu o aude niciodată, iar agentul o urmează în timp real.

În tabloul de bord: Istoric apeluri (/dashboard/call-history) pentru arhivă și detalii pentru fiecare apel; În desfășurare pentru apelurile active. Consultați Revizuiți, ascultați și îndrumați apelurile.

În API: /v1/calls — listă, transcriere, istoric, audio, evaluare, export; /v1/issue-reports.

Portaluri pentru clienți#

Un portal pentru clienți este o vizualizare de istoric al apelurilor, personalizată cu marcă și doar pentru citire, destinată unui client extern. Administratorii organizației aleg agenții ale căror apeluri apar, adaugă adresele de e-mail ale vizualizatorilor aprobați, încarcă un logo și o culoare de accent și, opțional, verifică un domeniu personalizat. Vizualizatorii portalului pot inspecta detaliile apelurilor, transcrierile și înregistrările disponibile fără a primi acces la tabloul de bord.

În tabloul de bord: Portaluri pentru clienți (/dashboard/client-portals). Consultați Portaluri pentru clienți.

În API: /v1/client-portals pentru interfața de administrare.

Widgeturi web#

Widgetul web oferă vizitatorilor site-ului dumneavoastră o conversație bazată pe microfon cu un agent — fără număr de telefon. Se autentifică folosind o cheie publicabilă (pk_live_...) restricționată la originile domeniilor permise, astfel încât poate fi utilizată în siguranță în codul client.

Cheile funcționează într-unul dintre două moduri: agent (asociată static cu un agent) sau webhook (serverul dumneavoastră alege configurația pentru fiecare vizitator — consultați Configurație dinamică per apel). Sesiunile widgetului trec prin aceeași infrastructură de apeluri ca apelurile telefonice.

În tabloul de bord: Widgeturi web (/dashboard/web-widgets) — creați widgeturi, setați modul și agentul, gestionați domeniile permise și copiați fragmentul de încorporare. Consultați Creați un widget web.

În API: /v1/publishable-key, /v1/mic-session și documentația SDK pentru widget.

Baze de cunoștințe#

O bază de cunoștințe este un set de documente pe care agentul dumneavoastră le poate căuta în timpul apelului pentru a-și fundamenta răspunsurile — încărcați fișiere, lipiți text sau importați pagini web după URL, apoi atașați baza de cunoștințe la un agent în constructor. Agentul o interoghează cu un instrument de căutare integrat ori de câte ori conversația o necesită.

În tabloul de bord: Cunoștințe (/dashboard/knowledge) pentru biblioteca de documente; secțiunea Cunoștințe din constructor pentru a atașa una la un agent. Consultați Oferiți agentului dumneavoastră o bază de cunoștințe.

Conexiuni#

Conexiunile sunt modalitatea prin care agenții ajung în lumea exterioară. Patru tipuri, un singur grup în bara laterală:

• Aplicații (/dashboard/app-connections) — conexiuni OAuth la Slack, HubSpot, Salesforce, Google Calendar, Google Sheets și Cal.com. Conectați o singură dată, apoi activați instrumentele pentru fiecare operațiune (postați un mesaj Slack, actualizați sau creați un contact HubSpot, rezervați un interval Cal.com…) pentru orice agent. Consultați Conectați aplicații.
• API-uri (/dashboard/api-connections) — transformați orice API HTTP într-o acțiune a agentului. Lipiți o comandă cURL, iar asistentul AI redactează definiția instrumentului, sau construiți-o manual; un buton Cerere de test inițiază un apel sandbox înainte de lansare. Consultați Conexiuni API — interfața din tabloul de bord pentru /v1/integrations.
• MCP (/dashboard/mcp-connections) — adăugați un server Model Context Protocol după URL și permiteți agentului să utilizeze instrumentele pe care le expune. Consultați Adăugați un server MCP.
• VoIP (/dashboard/voip-connections) — acreditări de furnizor pentru utilizarea propriilor numere de telefon. Consultați Conectați un furnizor VoIP.

ThunderPhone expune și propriul endpoint MCP, astfel încât un client MCP extern să poată lista agenți, inspecta apeluri și transcrieri și efectua apeluri. Consultați Utilizați ThunderPhone ca server MCP.

În API: /v1/integrations, /v1/mcp-servers și /v1/voip-connections; consultați și Construiți o integrare de instrument.

Campanii#

O campanie efectuează apeluri outbound la scară largă: încărcați un CSV cu contacte, alegeți agentul și numărul de apelare și setați fereastra de apelare (zile și ore, în funcție de fusul orar), concurența și politica de reîncercare (numărul maxim de încercări și rezultatele — fără răspuns, mesagerie vocală, eșuat — care sunt reîncercate). Campania parcurge lista și înregistrează fiecare apel în Istoricul apelurilor.

În tabloul de bord: Campanii (/dashboard/campaigns). Consultați Derulați o campanie de apeluri outbound.

Pentru apeluri programatice unice: API-ul pentru apeluri outbound.

Monitorizare live#

Live afișează fiecare apel în desfășurare din organizație și vă permite să deschideți oricare dintre ele pentru a asculta și a interveni în șoaptă în timp real. Este suprafața de supraveghere: urmăriți cum un prompt nou primește primul trafic real sau monitorizați o campanie în desfășurare.

În tabloul de bord: Live (/dashboard/live). Consultați Urmăriți și supravegheați apelurile live.

Simulări#

O simulare este un apelant AI care poartă o conversație reală cu agentul dumneavoastră — aceeași rută de telefonie, transcriere reală, evaluare reală — astfel încât să puteți testa înainte (și după) lansare. Direcționați-o către un agent sau un număr de telefon, scrieți chiar dumneavoastră scenariul apelantului sau generați scenarii cu AI din promptul agentului (inclusiv cazuri-limită, dacă solicitați acest lucru) și urmăriți apelul live.

Scenariile sunt grupate în suite care stabilesc o rată minimă de reușită și pot bloca lansările în CI; regresiile față de baza de referință acceptată sunt raportate pentru fiecare scenariu.

În tabloul de bord: Simulări (/dashboard/simulations), plus butonul Simulare din constructorul de agenți. Consultați Simulați un apel.

În API: /v1/test-calls și executorul de suite — consultați Testați un agent cap-coadă.

Seturi de validare#

Un set de validare transformă momentele din apeluri reale în verificări de regresie repetabile, cu un singur tur. Fiecare exemplu fixează contextul conversației, înregistrarea audio relevantă a apelantului, răspunsul original și comportamentul așteptat. Reluările sunt executate pe versiunea curentă a agentului fără a plasa un alt apel, iar dialogul de implementare poate afișa dacă cea mai recentă execuție corespunde în continuare acelei versiuni.

În tabloul de bord: Seturi de validare (/dashboard/validation) pentru setul de date al organizației și fila Validare din constructorul de agenți pentru execuții. Consultați Seturi de validare.

În API: /v1/validation-sets și punctele finale de reluare pentru agent/exemplu de pe aceeași pagină de referință.

Experimente#

Un experiment testează A/B configurațiile agentului pe trafic live: definiți variante (prompturi, motoare sau setări diferite), distribuiți traficul între ele și comparați rezultatele pentru fiecare variantă. Folosiți-l în loc să implementați manual logica de segmentare într-un webhook.

În tabloul de bord: Experimente (/dashboard/experiments) și fila A/B din constructorul de agenți. Consultați Experimente (testare A/B).

Probleme#

O problemă este o situație semnalată într-un anumit apel — raportată de un evaluator uman sau detectată de evaluarea AI. Problemele includ severitatea, sursa și starea, iar pagina Probleme este coada de triaj: filtrați, inspectați apelul problematic și urmăriți remedierea.

În tabloul de bord: Probleme (/dashboard/issues), plus semnalarea pentru fiecare apel în Istoricul apelurilor. Consultați Triajul problemelor.

În API: /v1/issue-reports.

Rapoarte#

Un raport răspunde la o întrebare în limbaj natural despre datele apelurilor dumneavoastră („Care au fost primele trei motive pentru care apelanții au solicitat un om săptămâna trecută?”) cu o analiză redactată de AI, limitată la agenții și intervalul de date pe care le alegeți.

În tabloul de bord: Rapoarte (/dashboard/reports). Consultați Rapoarte.

Observabilitate#

Observabilitatea este suprafața de metrici: volumul apelurilor, rezultatele și calitatea în timp, filtrabile după agent și interval de timp, cu export pentru analiză ulterioară.

În tabloul de bord: Observabilitate (/dashboard/observability). Consultați Observabilitate.

Alerte#

O regulă de alertă monitorizează o metrică (rata de reușită, rata de eșec, scorul mediu, volumul apelurilor, regresiile suitei) într-un interval de timp și se declanșează atunci când aceasta depășește pragul dumneavoastră. Notificările sunt trimise prin e-mail și Slack și declanșează un eveniment alert.triggered către punctele finale webhook.

În tabloul de bord: Organizație → Alerte. Consultați Alerte.

Webhookuri#

ThunderPhone trimite webhookuri HTTP POST către serverul dumneavoastră atunci când se întâmplă lucruri în timpul și după un apel. Două modele de livrare:

• Endpointuri webhook (recomandat): gestionați mai multe URL-uri la /v1/developer/webhook-endpoints, cu secrete pentru fiecare endpoint și abonamente la evenimente pentru fiecare endpoint.
• Webhook moștenit cu un singur URL: un URL per organizație. Gestionat la /v1/webhook sau în Organizație → General. Păstrat pentru compatibilitate retroactivă.

Evenimentele sunt împărțite în două clase:

• Evenimentele blocante se așteaptă ca serverul dumneavoastră să răspundă cu o configurație care modelează apelul în desfășurare — evenimentele de apel primit (telephony.incoming / web.incoming). Aveți la dispoziție până la 10 secunde pentru a răspunde; la expirarea timpului, agentul atribuit static gestionează apelul.
• Evenimentele neblocante sunt notificări trimise fără a aștepta răspuns, reîncercate cu backoff exponențial — consultați semantica livrării.

Fiecare solicitare include o semnătură HMAC-SHA256 în X-ThunderPhone-Signature. Consultați Verificarea semnăturii.

Instrumente de funcții#

Un instrument de funcții este un endpoint HTTP pe care agentul dumneavoastră îl poate apela în timpul conversației. Furnizați ThunderPhone o schemă de funcție în stil OpenAI și un URL de endpoint; agentul decide când să îl apeleze, iar ThunderPhone efectuează solicitarea HTTP semnată de pe serverele sale și transmite rezultatul înapoi agentului.

Agenții includ și capabilități integrate pentru apeluri — transferarea apelului, trimiterea de date de la tastatură (DTMF), încheierea apelului, așteptarea în așteptare — pe care le activați cu linii simple în prompt, în loc de definiții de instrumente.

În tabloul de bord: secțiunea Conexiuni API din constructor (consultați Conexiuni).

În API: /v1/integrations și specificația Instrumente de funcții.

Echipă și roluri#

Fiecare organizație are o listă de membri cu două roluri: Membrii creează și operează agenți; Administratorii gestionează și echipa, și facturarea. Invitați prin e-mail — invitațiile expiră după 7 zile și pot fi revocate; meniul ⋯ din rândul unui membru modifică rolurile sau elimină o persoană. Autentificarea unică poate fi configurată la nivelul întregii organizații — consultați SSO.

În tabloul de bord: Organizație → General. Consultați Invitați-vă echipa.

În API: /v1/members, /v1/invites.

Facturare#

ThunderPhone este preplătit. Fiecare organizație are un sold în USD; apelurile îl debitează la tariful pe minut al agentului (nivelul motorului plus suprataxe — constructorul afișează în timp real tariful total pe măsură ce modificați setările, iar anumite limbi suplimentare adaugă 3¢/min). Când soldul ajunge la zero, apelurile primite sunt respinse, iar apelurile efectuate returnează 402 Payment Required.

Adăugați fonduri manual sau activați reîncărcarea automată cu un prag de sold, o sumă de reîncărcare și o limită opțională de cheltuieli lunare — astfel încât un apel să nu se întrerupă niciodată la mijlocul unei propoziții.

În tabloul de bord: Organizație → Setări de facturare și Istoric de facturare. Consultați Adăugați fonduri și activați reîncărcarea automată, precum și referința completă privind prețurile.

În API: /v1/billing.

Copilotul din aplicație#

Tabloul de bord include un copilot integrat — întrebați-l „cum fac X” și răspunde pe baza acestei documentații, oferă ghiduri pas cu pas care evidențiază controalele reale și poate relua oricare dintre tururile ghidate. Este cea mai rapidă modalitate de a găsi un control menționat pe această pagină. Consultați Întrebați copilotul din aplicație.

Punerea cap la cap#