Průvodci

Vlastní agent

Chceš na číslo volai napojit vlastní hlasovou platformu - ElevenLabs Conversational AI ve svém vlastním workspace, Vapi, Retell, nebo klidně vlastní Asterisk/FreeSWITCH IVR - místo zabudovaného agenta volai? Tahle stránka je návod na oba směry: příchozí i odchozí hovory. U odchozích navíc neplatíš agentní přirážku 2,50 Kč/min - agenta si provozuješ (a platíš) sám u své platformy.

1Kdy vlastní agent, kdy zabudovaný

Obě cesty běží na stejném čísle a stejném kreditu - liší se jen v tom, KDO provozuje konverzační logiku a kolik to stojí navíc:

2Příchozí hovory na vlastního agenta

Žádná nová mechanika - stačí existující směrování mode: "sip" (stejné jako pro vlastní softphone, viz SIP) se sipUri tvé platformy. Pro ElevenLabs SIP-trunk číslo zaregistrované na TVÉM vlastním workspace je to adresa se stejným číslem, jaké má tvoje volai linka:

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

A na svém ElevenLabs účtu (Settings → Phone Numbers → Import → SIP trunk) tohle číslo zaregistruješ s inbound_trunk_config:

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

allowed_addresses výš je náš rozsah signalizace (81.31.45.0/24) - bezpečnější než univerzální 0.0.0.0/0, které pustí INVITE odkudkoli. Obojí hovor propustí, ale u importu bez přihlašovacích údajů je allowlist JEDINÁ kontrola - proto dej rozsah, ne 0.0.0.0/0.

Používáš jinou platformu než ElevenLabs? Stejný princip - zjisti u ní SIP adresu, na kterou má chodit hovor pro tvoje číslo, a tu dej do sipUri. U Vapi jde stejný rozsah do BYO trunku jako gateways.

U Vapi je adresa směrování sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> najdeš u svého BYO SIP trunku ve Vapi; holý sip.vapi.ai patří nativním Vapi číslům a pro číslo od nás nefunguje.

3Odchozí hovory z vlastního agenta (relay)

Tohle je opačný směr - tvoje platforma sama vytáčí ven. Většina hlasových AI platforem (ElevenLabs včetně) ale neumí telefonní linku trvale zaregistrovat jako SIP klienta - jen odešle autentizovaný hovor s přihlašovacími údaji tvé linky. Telefonní síť takový hovor napřímo na cílové číslo nepustí, a proto ho vedeš přes krátce trvající relay spojení:

1. Nastav svou platformu na svou linku

Vyzvedni si SIP údaje své linky:

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

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

Odpověď vrací server (pro REGISTER softphonu, viz SIP) a outboundTrunkAddress ZVLÁŠŤ - nejsou zaměnitelné.

A nastav outboundTrunkAddress - NE server - jako odchozí trunk své platformy. U ElevenLabs jde o outbound_trunk_config daného telefonního čísla (Settings → Phone Numbers → tvoje číslo → Outbound calling), přesně tenhle tvar:

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

2. Vytvoř relay spojení

Těsně před hovorem (spojení má krátkou životnost, viz limity níž) zavolej:

curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -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áváš NÁM do to - platforma ho nikdy nevidí, dostane jen holé sipName z odpovědi.

3. Řekni platformě, ať zavolá na sipName

U ElevenLabs to znamená zavolat přes /v1/convai/sip-trunk/outbound-call s to_number rovnou sipName:

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

agent_id najdeš u svého agenta v ElevenLabs, agent_phone_number_id je phone_number_id importovaného čísla - vrátí ho odpověď importu, nebo ho vyčteš ze seznamu Phone numbers.

Vlastní SIP klient nebo PBX místo ElevenLabs? Vytoč rovnou celé sipUri jako běžné SIP volání - to omezení platí jen pro platformy, které chtějí holé jméno bez sip: prefixu.

4. Co se stane dál

Telefonní síť hovor přijme na jméně volai_relay_2, přepojí ho na tvoje to a nastaví viditelné číslo volajícího na tvoje from - volaný na displeji uvidí tvoji volai linku, ne interní jméno relay slotu (pokud má číslo vlastní relay jména - viz Účtování níž, jinak volaný uvidí demo číslo volai). Po skončení hovoru se lease uvolní a minuty se naúčtují stejně jako běžný odchozí hovor - 0,92 Kč/min, žádná agentní přirážka.

Odpověď o vytočení hovoru dorazí až po celém vyzvánění (klidně desítky sekund) - to není chyba, i krátký timeout na tvé straně by v tu chvíli vypadal jako selhání, přestože hovor běží.

4Řešení potíží

Nejčastější hlášky u vlastního agenta a co s nimi:

5Účtování

Odchozí hovor přes relay se účtuje stejnou sazbou jako běžný odchozí hovor - 0,92 Kč/min - bez jakékoli agentní přirážky. Sazby jsou bez DPH, jako celý ceník.

Souběžnost je omezená (viz limity níž): nejvýš 1 aktivní hovor na jedno tvoje číslo a nejvýš 2 na celý účet najednou.

Volaný uvidí tvoji volai linku JEN pokud má číslo vlastní relay jména (relayNames) - bez nich lease spadne na sdílený pool a volaný uvidí demo číslo volai. Chybí-li ti relay jména, napiš na podporu.

6Limity, kvóty a zabezpečení

Strop je 1 aktivní lease na jedno tvoje číslo a nejvýš 2 na celý účet - záměrná pojistka proti tomu, aby jeden zákazník obsadil celý sdílený pool relay slotů:

• from musí být tvoje vlastní volai číslo - jinak from_number_not_owned. Bez týhle kontroly by šlo vydávat se za cizí linku (caller ID spoofing).
• Stejné brány jako běžný hovor - seznam nevolat (platí jen pro hovory, ne SMS), automatická 30denní blokace po 3 neúspěšných pokusech na stejné číslo za 24 hodin, prémiové linky, ochrana proti smyčce mezi volai čísly, zámek volaného čísla i obecný rate limit hovorů. Nic z tohohle nejde relayem obejít.
• Plný pool -> 503 capacity_busy - relay sloty jsou sdílený strop souběžnosti CELÉ platformy, ne jen tvého účtu. Při capacity_busy se nic neúčtuje, zkus to znovu za chvíli.
• Kompletní REST referenci (chybové kódy, GET/DELETE nad leasy) najdeš na REST API.

Každá chyba API nese cause (kdo ji opraví) a action (co udělat) - viz Formát chyb v referenci REST API.