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": ["0.0.0.0/0"],
    "media_encryption": "allowed"
  }
}

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.

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

A nastav je 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": "udp",
    "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"
}

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

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. 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.

4Limity, kvóty a zabezpečení

• 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.