Ghiduri

Agent propriu

Doriți să conectați la un număr volai propria platformă vocală - ElevenLabs Conversational AI în propriul workspace, Vapi, Retell sau chiar un IVR Asterisk/FreeSWITCH propriu - în locul agentului integrat volai? Această pagină este un ghid pentru ambele sensuri: apeluri primite și efectuate. La apelurile efectuate nu plătiți suprataxa pentru agent de 2,50 kr/min (≈ 0,52 RON) - agentul îl rulați (și îl plătiți) dumneavoastră, la propria platformă.

1Când agent propriu, când cel integrat

Ambele variante rulează pe același număr și cu același credit - diferă doar CINE rulează logica conversației și cât costă în plus:

2Apeluri primite către agentul propriu

Fără mecanisme noi - este suficientă rutarea existentă mode: "sip" (la fel ca pentru un softphone propriu, vezi SIP) către sipUri platformei dumneavoastră. Pentru un număr ElevenLabs de tip SIP trunk înregistrat în PROPRIUL workspace, aceasta este o adresă cu același număr ca linia dumneavoastră volai:

curl -X PATCH "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "sip", "sipUri": "sip:+420601234567@sip.rtc.elevenlabs.io"}}'

Iar în contul dumneavoastră ElevenLabs (Settings → Phone Numbers → Import → SIP trunk) înregistrați acest număr cu inbound_trunk_config:

{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "Agentul meu propriu",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

allowed_addresses de mai sus este intervalul nostru de semnalizare (81.31.45.0/24) - mai sigur decât universalul 0.0.0.0/0, care lasă să treacă un INVITE de oriunde. Ambele permit apelul, dar la un import fără date de autentificare allowlist-ul este SINGURA verificare - de aceea folosiți intervalul, nu 0.0.0.0/0.

Folosiți altă platformă decât ElevenLabs? Același principiu - aflați de la ea adresa SIP la care trebuie să ajungă apelul pentru numărul dumneavoastră și introduceți-o în sipUri. La Vapi, același interval se introduce în trunchiul BYO ca gateways.

La Vapi, adresa de rutare este sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> îl găsiți la trunchiul dumneavoastră BYO SIP din Vapi; o organizație din regiunea UE folosește în loc de sip.vapi.ai domeniul sip.eu.vapi.ai. Simplul sip.vapi.ai aparține numerelor Vapi native și nu funcționează pentru un număr de la noi. Lăsați numele de utilizator și parola goale la trunchiul BYO - Vapi recunoaște apelurile noastre după IP-ul din gateways.

În gateways introduceți intervalul separat, ca IP 81.31.45.0 și mască (netmask) 24. Cu masca implicită 32, Vapi ar permite o singură adresă și ar respinge apelurile noastre.

3Apeluri efectuate de agentul propriu (relay)

Acesta este sensul opus - platforma dumneavoastră formează singură numărul. Majoritatea platformelor vocale AI (inclusiv ElevenLabs) nu pot înregistra permanent o linie telefonică drept client SIP - trimit doar un apel autentificat cu datele de acces ale liniei dumneavoastră. Rețeaua telefonică nu lasă un astfel de apel să ajungă direct la numărul destinatar, de aceea îl treceți printr-o conexiune relay de scurtă durată:

1. Setați platforma pe linia dumneavoastră

Preluați datele SIP ale liniei dumneavoastră:

curl "https://volai.cz/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

Răspunsul returnează server (pentru REGISTER la un softphone, vezi SIP) și outboundTrunkAddress SEPARAT - nu se pot înlocui între ele.

Și setați outboundTrunkAddress - NU server - drept trunchi de ieșire al platformei dumneavoastră. La ElevenLabs este vorba despre outbound_trunk_config numărului de telefon respectiv (Settings → Phone Numbers → numărul dumneavoastră → Outbound calling), exact în această formă:

{
  "outbound_trunk_config": {
    "address": "sip.volai.cz",
    "transport": "tcp",
    "media_encryption": "allowed",
    "credentials": {
      "username": "123456",
      "password": "a1b2c3d4e5f6"
    }
  }
}

2. Creați o conexiune relay

Chiar înainte de apel (conexiunea are o durată de viață scurtă, vezi limitele de mai jos) apelați:

curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

{
  "id": "rl_4f2a91cd",
  "sipName": "volai_relay_2",
  "sipUri": "sip:volai_relay_2@sip.volai.cz",
  "expiresAt": 1756111760000,
  "callId": "c_9d4e2b7f"
}

Numărul apelat ni-l transmiteți NOUĂ în to - platforma nu îl vede niciodată, primește doar sipName simplu din răspuns.

3. Spuneți platformei să apeleze sipName

La ElevenLabs aceasta înseamnă apelarea /v1/convai/sip-trunk/outbound-call cu to_number setat direct la sipName:

{
  "agent_id": "agent_...",
  "agent_phone_number_id": "phnum_...",
  "to_number": "volai_relay_2"
}

agent_id îl găsiți la agentul dumneavoastră din ElevenLabs, agent_phone_number_id este phone_number_id al numărului importat - îl returnează răspunsul importului sau îl puteți citi din lista Phone numbers.

Folosiți un client SIP propriu sau o centrală PBX în loc de ElevenLabs? Formați direct sipUri complet, ca pe un apel SIP obișnuit - restricția se aplică doar platformelor care vor un nume simplu, fără sip: prefix.

4. Ce se întâmplă mai departe

Rețeaua telefonică primește apelul la numele volai_relay_2, îl transferă către to dumneavoastră și setează numărul vizibil al apelantului la from dumneavoastră - destinatarul vede pe ecran linia dumneavoastră volai, nu numele intern al slotului relay (dacă numărul are nume relay proprii - vezi Facturarea mai jos, altfel destinatarul vede numărul demo volai). După terminarea apelului lease-ul se eliberează, iar minutele se facturează exact ca un apel efectuat obișnuit - 0,92 kr/min (≈ 0,19 RON), fără suprataxă pentru agent.

Răspunsul despre formarea apelului sosește abia după toată durata de apel (uneori zeci de secunde) - nu este o eroare, dar un timeout scurt din partea dumneavoastră ar arăta în acel moment ca un eșec, deși apelul este în curs.

4Rezolvarea problemelor

Cele mai frecvente mesaje la un agent propriu și ce puteți face:

5Facturare

Apelul efectuat prin relay se facturează cu același tarif ca un apel efectuat obișnuit - 0,92 kr/min (≈ 0,19 RON) - fără nicio suprataxă pentru agent. Tarifele sunt fără TVA, ca întreaga listă de prețuri.

Simultaneitatea este limitată (vezi limitele de mai jos): cel mult 1 apel activ pe un număr al dumneavoastră și cel mult 2 în întregul cont, simultan.

Destinatarul vede linia dumneavoastră volai DOAR dacă numărul are nume relay (relayNames) proprii - numărul le primește imediat după cumpărare. Cât timp nu le are, lease-ul cade pe pool-ul comun, iar destinatarul vede numărul demo volai. Dacă situația durează mai mult de o oră, scrieți-ne la suport.

6Limite, cote și securitate

Plafonul este 1 lease activ pe un număr al dumneavoastră și cel mult 2 în întregul cont - o protecție intenționată împotriva ocupării de către un singur client a întregului pool comun de sloturi relay:

• from trebuie să fie propriul dumneavoastră număr volai - altfel from_number_not_owned. Fără această verificare s-ar putea uzurpa linia altcuiva (caller ID spoofing).
• Aceleași bariere ca la un apel obișnuit - lista „nu sunați” (se aplică doar apelurilor, nu SMS-urilor), blocarea automată de 30 de zile după 3 încercări nereușite către același număr în 24 de ore, liniile premium, protecția împotriva buclei între numerele volai, blocarea numărului apelat și limita generală de apeluri. Nimic din toate acestea nu poate fi ocolit prin relay.
• Pool plin -> 503 capacity_busy - sloturile relay sunt un plafon comun de simultaneitate pentru ÎNTREAGA platformă, nu doar pentru contul dumneavoastră. La capacity_busy nu se facturează nimic, încercați din nou peste puțin timp.
• Referința REST completă (coduri de eroare, GET/DELETE pentru lease-uri) o găsiți la REST API.

Fiecare eroare API conține cause (cine o remediază) și action (ce trebuie făcut) - vezi Formatul erorilor în referința REST API.