Sprievodcovia

Vlastný agent

Chcete na číslo volai napojiť vlastnú hlasovú platformu - ElevenLabs Conversational AI vo svojom vlastnom workspace, Vapi, Retell, alebo aj vlastný Asterisk/FreeSWITCH IVR - namiesto zabudovaného agenta volai? Táto stránka je návod na oba smery: prichádzajúce aj odchádzajúce hovory. Pri odchádzajúcich navyše neplatíte prirážku za agenta 2,50 kr/min (≈ 0,10 EUR) - agenta si prevádzkujete (a platíte) sami u svojej platformy.

1Kedy vlastný agent, kedy zabudovaný

Obe cesty bežia na rovnakom čísle a rovnakom kredite - líšia sa len v tom, KTO prevádzkuje konverzačnú logiku a koľko to stojí navyše:

2Prichádzajúce hovory na vlastného agenta

Žiadna nová mechanika - stačí existujúce mode: "sip" smerovanie (rovnaké ako pre vlastný softfón, pozri SIP) so sipUri vašej platformy. Pre číslo ElevenLabs SIP-trunk zaregistrované vo VAŠOM vlastnom workspace je to adresa s rovnakým číslom, aké má vaša linka volai:

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

A vo svojom účte ElevenLabs (Settings → Phone Numbers → Import → SIP trunk) toto číslo zaregistrujete s inbound_trunk_config:

{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "Môj vlastný agent",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

allowed_addresses vyššie je náš rozsah signalizácie (81.31.45.0/24) - bezpečnejší než univerzálne 0.0.0.0/0, ktoré pustí INVITE odkiaľkoľvek. Oboje hovor prepustí, ale pri importe bez prihlasovacích údajov je allowlist JEDINOU kontrolou - preto zadajte rozsah, nie 0.0.0.0/0.

Používate inú platformu než ElevenLabs? Rovnaký princíp - zistite u nej SIP adresu, na ktorú má chodiť hovor pre vaše číslo, a tú zadajte do sipUri. Pri Vapi ide rovnaký rozsah do BYO trunku ako gateways.

Pri Vapi je adresa smerovania sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> nájdete pri svojom BYO SIP trunku vo Vapi, organizácia v EÚ regióne má namiesto sip.vapi.ai doménu sip.eu.vapi.ai. Holé sip.vapi.ai patrí natívnym číslam Vapi a pre číslo od nás nefunguje. Prihlasovacie meno a heslo nechajte pri BYO trunku prázdne, Vapi naše hovory pozná podľa IP v gateways.

Do gateways zadajte rozsah ako IP 81.31.45.0 a masku (netmask) 24 zvlášť. S predvolenou maskou 32 by Vapi pustilo len jednu adresu a naše hovory by odmietlo.

3Odchádzajúce hovory z vlastného agenta (relay)

Toto je opačný smer - vaša platforma sama vytáča von. Väčšina hlasových AI platforiem (vrátane ElevenLabs) však nevie telefónnu linku trvalo zaregistrovať ako SIP klienta - iba odošle autentifikovaný hovor s prihlasovacími údajmi vašej linky. Telefónna sieť takýto hovor priamo na cieľové číslo nepustí, a preto ho vediete cez krátkodobé relay spojenie:

1. Nastavte svoju platformu na svoju linku

Vyžiadajte si SIP údaje svojej linky:

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

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

Odpoveď vracia server (pre REGISTER softfónu, pozri SIP) a outboundTrunkAddress ZVLÁŠŤ - nie sú zameniteľné.

A nastavte outboundTrunkAddress - NIE server - ako odchádzajúci trunk svojej platformy. V ElevenLabs ide o outbound_trunk_config daného telefónneho čísla (Settings → Phone Numbers → vaše číslo → Outbound calling), presne v tomto tvare:

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

2. Vytvorte relay spojenie

Tesne pred hovorom (spojenie má krátku životnosť, pozri limity nižšie) zavolajte:

curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_VAS_KLUC" \
  -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"
}

Číslo volaného zadávate NÁM do to - platforma ho nikdy nevidí, dostane len holé sipName z odpovede.

3. Povedzte platforme, nech zavolá na sipName

V ElevenLabs to znamená zavolať cez /v1/convai/sip-trunk/outbound-call s to_number nastaveným priamo na sipName:

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

agent_id nájdete pri svojom agentovi v ElevenLabs, agent_phone_number_id je phone_number_id importovaného čísla - vráti ho odpoveď importu, alebo ho vyčítate zo zoznamu Phone numbers.

Vlastný SIP klient alebo PBX namiesto ElevenLabs? Vytočte rovno celé sipUri ako bežné SIP volanie - toto obmedzenie platí len pre platformy, ktoré chcú holé meno bez sip: prefixu.

4. Čo sa stane potom

Telefónna sieť hovor prijme na mene volai_relay_2, prepojí ho na vaše to a nastaví viditeľné číslo volajúceho na vaše from - volaný na displeji uvidí vašu linku volai, nie interné meno relay slotu (ak má číslo vlastné relay mená - pozri Účtovanie nižšie, inak volaný uvidí demo číslo volai). Po skončení hovoru sa lease uvoľní a minúty sa zaúčtujú rovnako ako bežný odchádzajúci hovor - 0,92 kr/min (≈ 0,04 EUR), žiadna prirážka za agenta.

Odpoveď o vytočení hovoru príde až po celom zvonení (pokojne desiatky sekúnd) - to nie je chyba, aj krátky timeout na vašej strane by v tej chvíli vyzeral ako zlyhanie, hoci hovor beží.

4Riešenie problémov

Najčastejšie hlášky pri vlastnom agentovi a čo s nimi:

5Účtovanie

Odchádzajúci hovor cez relay sa účtuje rovnakou sadzbou ako bežný odchádzajúci hovor - 0,92 kr/min (≈ 0,04 EUR) - bez akejkoľvek prirážky za agenta. Sadzby sú bez DPH, ako celý cenník.

Súbežnosť je obmedzená (pozri limity nižšie): najviac 1 aktívny hovor na jedno vaše číslo a najviac 2 na celý účet naraz.

Volaný uvidí vašu linku volai LEN vtedy, ak má číslo vlastné relay mená (relayNames) - číslo ich dostane hneď po kúpe. Kým ich nemá, lease spadne na zdieľaný pool a volaný uvidí demo číslo volai. Ak to trvá dlhšie než hodinu, napíšte na podporu.

6Limity, kvóty a zabezpečenie

Strop je 1 aktívny lease na jedno vaše číslo a najviac 2 na celý účet - zámerná poistka proti tomu, aby jeden zákazník obsadil celý zdieľaný pool relay slotov:

• from musí byť vaše vlastné číslo volai - inak from_number_not_owned. Bez tejto kontroly by sa dalo vydávať za cudziu linku (spoofing identifikácie volajúceho).
• Rovnaké brány ako bežný hovor - zoznam nevolať (platí len pre hovory, nie SMS), automatická 30-dňová blokácia po 3 neúspešných pokusoch na to isté číslo za 24 hodín, prémiové linky, ochrana proti slučke medzi číslami volai, zámok volaného čísla aj všeobecný rate limit hovorov. Nič z toho sa cez relay nedá obísť.
• Plný pool -> 503 capacity_busy - relay sloty sú zdieľaný strop súbežnosti CELEJ platformy, nie len vášho účtu. Pri capacity_busy sa nič neúčtuje, skúste to o chvíľu znova.
• Kompletnú REST referenciu (chybové kódy, GET/DELETE nad leasmi) nájdete v REST API.

Každá chyba API obsahuje cause (kto ju opraví) a action (čo urobiť) - pozri Formát chýb v referencii REST API.