Vodniki

Lasten agent

Želite namesto vgrajenega agenta volai na številko volai priklopiti lastno glasovno platformo - ElevenLabs Conversational AI v svojem delovnem prostoru, Vapi, Retell ali kar lasten IVR na Asterisk/FreeSWITCH? Ta stran je navodilo za obe smeri: dohodne in odhodne klice. Pri odhodnih klicih poleg tega ne plačujete doplačila za agenta 2,50 kr/min (≈ 0,10 EUR) - agenta upravljate (in plačujete) sami pri svoji platformi.

1Kdaj lasten agent, kdaj vgrajeni

Obe poti tečeta na isti številki in z istim dobroimetjem - razlikujeta se le v tem, KDO vodi pogovorno logiko in koliko to stane dodatno:

2Dohodni klici na lastnega agenta

Nobene nove mehanike - zadošča obstoječe usmerjanje mode: "sip" (enako kot za lasten softphone, glej SIP) na sipUri vaše platforme. Za številko SIP trunka ElevenLabs, registrirano v VAŠEM lastnem delovnem prostoru, je to naslov z isto številko, kot jo ima vaša linija 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"}}'

V svojem računu ElevenLabs (Settings → Phone Numbers → Import → SIP trunk) nato to številko registrirate z inbound_trunk_config:

{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "Moj lastni agent",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

allowed_addresses zgoraj je naš obseg signalizacije (81.31.45.0/24) - varnejši od splošnega 0.0.0.0/0, ki spusti INVITE od koderkoli. Obe možnosti klic prepustita, a pri uvozu brez prijavnih podatkov je seznam dovoljenih naslovov EDINI nadzor - zato vnesite obseg, ne 0.0.0.0/0.

Uporabljate drugo platformo kot ElevenLabs? Isto načelo - pri njej poiščite SIP naslov, na katerega naj prihaja klic za vašo številko, in ga vnesite v sipUri. Pri Vapi isti obseg vnesete v BYO trunk kot gateways.

Pri Vapi je naslov usmerjanja sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> najdete pri svojem BYO SIP trunku v Vapi, organizacija v regiji EU ima namesto sip.vapi.ai domeno sip.eu.vapi.ai. Goli sip.vapi.ai pripada izvornim številkam Vapi in za našo številko ne deluje. Uporabniško ime in geslo pri BYO trunku pustite prazna, Vapi naše klice prepozna po IP naslovu v gateways.

V gateways vnesite obseg kot IP 81.31.45.0 in masko (netmask) 24 ločeno. S privzeto masko 32 bi Vapi spustil le en naslov in naše klice zavrnil.

3Odhodni klici z lastnega agenta (relej)

To je nasprotna smer - vaša platforma sama kliče navzven. Večina glasovnih AI platform (tudi ElevenLabs) pa telefonske linije ne zna trajno registrirati kot SIP odjemalca - pošlje le overjen klic s prijavnimi podatki vaše linije. Telefonsko omrežje takega klica neposredno na ciljno številko ne spusti, zato ga speljete prek kratkotrajne relejne povezave:

1. Nastavite svojo platformo na svojo linijo

Prevzemite SIP podatke svoje linije:

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

Odgovor vrne server (za REGISTER softphona, glej SIP) in outboundTrunkAddress LOČENO - nista zamenljiva.

Nato kot odhodni trunk svoje platforme nastavite outboundTrunkAddress - NE server - Pri ElevenLabs gre za outbound_trunk_config dane telefonske številke (Settings → Phone Numbers → vaša številka → Outbound calling), natanko v tej obliki:

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

2. Ustvarite relejno povezavo

Tik pred klicem (povezava je kratkotrajna, glej omejitve spodaj) pokličite:

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

Številko klicanega vnesete NAM v to - platforma je nikoli ne vidi, dobi le golo sipName iz odgovora.

3. Platformi naročite, naj pokliče sipName

Pri ElevenLabs to pomeni klic prek /v1/convai/sip-trunk/outbound-call z to_number neposredno sipName:

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

agent_id najdete pri svojem agentu v ElevenLabs, agent_phone_number_id je phone_number_id uvožene številke - vrne ga odgovor uvoza ali ga preberete s seznama Phone numbers.

Lasten SIP odjemalec ali PBX namesto ElevenLabs? Neposredno pokličite celoten sipUri kot običajen SIP klic - ta omejitev velja le za platforme, ki hočejo golo ime brez predpone sip: .

4. Kaj se zgodi potem

Telefonsko omrežje klic sprejme na imenu volai_relay_2, ga preusmeri na vaš to in kot vidno številko klicatelja nastavi vašo from - klicani na zaslonu vidi vašo linijo volai, ne internega imena relejnega mesta (če ima številka lastna relejna imena - glej Zaračunavanje spodaj, sicer klicani vidi demo številko volai). Po koncu klica se lease sprosti in minute se zaračunajo enako kot pri običajnem odhodnem klicu - 0,92 kr/min (≈ 0,04 EUR), brez doplačila za agenta.

Odgovor o vzpostavitvi klica prispe šele po celotnem zvonjenju (tudi več deset sekund) - to ni napaka, tudi kratek timeout na vaši strani bi bil takrat videti kot neuspeh, čeprav klic teče.

4Odpravljanje težav

Najpogostejša sporočila pri lastnem agentu in kaj z njimi:

5Zaračunavanje

Odhodni klic prek releja se zaračuna po isti ceni kot običajen odhodni klic - 0,92 kr/min (≈ 0,04 EUR) - brez kakršnega koli doplačila za agenta. Cene so brez DDV, kot ves cenik.

Sočasnost je omejena (glej omejitve spodaj): največ 1 aktivni klic na eno vašo številko in največ 2 na ves račun hkrati.

Klicani vidi vašo linijo volai SAMO, če ima številka lastna relejna imena (relayNames) - številka jih dobi takoj po nakupu. Dokler jih nima, lease pade na skupni nabor in klicani vidi demo številko volai. Če to traja dlje kot eno uro, pišite podpori.

6Omejitve, kvote in varnost

Zgornja meja je 1 aktivni lease na eno vašo številko in največ 2 na ves račun - namerna zaščita, da ena sama stranka ne zasede celotnega skupnega nabora relejnih mest:

• from mora biti vaša lastna številka volai - sicer from_number_not_owned. Brez tega preverjanja bi se bilo mogoče izdajati za tujo linijo (ponarejanje caller ID).
• Ista vrata kot pri običajnem klicu - seznam »ne kličite« (velja le za klice, ne za SMS), samodejna 30-dnevna blokada po 3 neuspelih poskusih na isto številko v 24 urah, premijske linije, zaščita pred zanko med številkami volai, zaklep klicane številke in splošna omejitev števila klicev. Nič od tega ni mogoče zaobiti z relejem.
• Poln nabor -> 503 capacity_busy - relejna mesta so skupna zgornja meja sočasnosti CELOTNE platforme, ne le vašega računa. Pri capacity_busy se nič ne zaračuna, poskusite znova čez trenutek.
• Celotno referenco REST (kode napak, GET/DELETE nad leasi) najdete na REST API.

Vsaka napaka API-ja nosi cause (kdo jo odpravi) in action (kaj storiti) - glej Format napak v referenci REST API.