Przewodniki

Własny agent

Chcą Państwo podłączyć do numeru volai własną platformę głosową - ElevenLabs Conversational AI we własnym workspace, Vapi, Retell, a nawet własny IVR na Asterisk/FreeSWITCH - zamiast wbudowanego agenta volai? Ta strona to instrukcja dla obu kierunków: połączeń przychodzących i wychodzących. Przy wychodzących nie płacą Państwo dodatkowo dopłaty za agenta (2.50 CZK/min (~EUR 0.10)) - agenta prowadzą Państwo (i opłacają) sami na własnej platformie.

1Kiedy własny agent, a kiedy wbudowany

Obie drogi działają na tym samym numerze i tym samym saldzie - różnią się tylko tym, KTO prowadzi logikę rozmowy i ile to kosztuje dodatkowo:

2Połączenia przychodzące do własnego agenta

Bez nowej mechaniki - wystarczy istniejące ustawienie routingu mode: "sip" (takie samo jak dla własnego softfona, patrz SIP) z adresem sipUri Państwa platformy. Dla numeru SIP trunk w ElevenLabs zarejestrowanego we WŁASNYM workspace jest to adres z tym samym numerem, jaki ma Państwa linia 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"}}'

Na koncie ElevenLabs (Settings → Phone Numbers → Import → SIP trunk) proszę zarejestrować ten numer z konfiguracją inbound_trunk_config:

{
  "provider": "sip_trunk",
  "phone_number": "+420601234567",
  "label": "Mój własny agent",
  "inbound_trunk_config": {
    "allowed_addresses": ["81.31.45.0/24"],
    "media_encryption": "allowed"
  }
}

allowed_addresses powyżej to nasz zakres sygnalizacji (81.31.45.0/24) - bezpieczniejszy niż uniwersalny 0.0.0.0/0, który przepuszcza INVITE z dowolnego miejsca. Oba warianty przepuszczą połączenie, ale przy imporcie bez danych logowania allowlista jest JEDYNĄ kontrolą - dlatego proszę podać zakres, a nie 0.0.0.0/0.

Używają Państwo innej platformy niż ElevenLabs? Zasada jest ta sama - proszę sprawdzić u niej adres SIP, na który mają trafiać połączenia dla Państwa numeru, i wpisać go w pole sipUri. W Vapi ten sam zakres trafia do trunku BYO jako gateways.

W Vapi adres routingu ma postać sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> znajdą Państwo przy swoim trunku BYO SIP w Vapi, a organizacja w regionie UE ma zamiast sip.vapi.ai domenę sip.eu.vapi.ai. Sam sip.vapi.ai należy do natywnych numerów Vapi i dla numeru od nas nie działa. Nazwę użytkownika i hasło proszę zostawić w trunku BYO puste - Vapi rozpoznaje nasze połączenia po adresie IP w gateways.

W gateways proszę podać zakres jako IP 81.31.45.0 oraz maskę (netmask) 24 osobno. Przy domyślnej masce 32 Vapi przepuściłoby tylko jeden adres i odrzucałoby nasze połączenia.

3Połączenia wychodzące z własnego agenta (relay)

To kierunek przeciwny - Państwa platforma sama wykonuje połączenia. Większość platform głosowych AI (w tym ElevenLabs) nie potrafi jednak na stałe zarejestrować linii telefonicznej jako klienta SIP - wysyła jedynie uwierzytelnione połączenie z danymi logowania Państwa linii. Sieć telefoniczna nie przepuści takiego połączenia bezpośrednio na numer docelowy, dlatego prowadzą je Państwo przez krótkotrwałe połączenie relay:

1. Proszę skonfigurować platformę na swoją linię

Proszę pobrać dane SIP swojej linii:

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

Odpowiedź zwraca server (do REGISTER softfona, patrz SIP) oraz outboundTrunkAddress OSOBNO - nie są wymienne.

Proszę ustawić outboundTrunkAddress - a NIE server - jako wychodzący trunk swojej platformy. W ElevenLabs jest to outbound_trunk_config danego numeru telefonu (Settings → Phone Numbers → Państwa numer → Outbound calling), dokładnie w tej postaci:

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

2. Proszę utworzyć połączenie relay

Tuż przed połączeniem (połączenie ma krótki czas życia, patrz limity poniżej) proszę wywołać:

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

Numer docelowy podają Państwo NAM w polu to - platforma nigdy go nie widzi, dostaje tylko samą nazwę sipName z odpowiedzi.

3. Proszę polecić platformie połączenie z sipName

W ElevenLabs oznacza to wywołanie /v1/convai/sip-trunk/outbound-call z polem to_number ustawionym bezpośrednio na sipName:

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

agent_id znajdą Państwo przy swoim agencie w ElevenLabs, agent_phone_number_id to phone_number_id zaimportowanego numeru - zwraca go odpowiedź importu albo można go odczytać z listy Phone numbers.

Własny klient SIP lub centrala PBX zamiast ElevenLabs? Proszę wybrać wprost pełny sipUri jak przy zwykłym połączeniu SIP - to ograniczenie dotyczy tylko platform, które chcą samej nazwy z pominięciem prefiksu sip: .

4. Co dzieje się dalej

Sieć telefoniczna przyjmuje połączenie na nazwie volai_relay_2, przekazuje je na Państwa to i ustawia widoczny numer dzwoniącego na Państwa from - osoba wywoływana zobaczy na wyświetlaczu Państwa linię volai, a nie wewnętrzną nazwę slotu relay (jeśli numer ma własne nazwy relay - patrz Rozliczanie poniżej; w przeciwnym razie zobaczy numer demonstracyjny volai). Po zakończeniu rozmowy lease jest zwalniany, a minuty są naliczane tak samo jak przy zwykłym połączeniu wychodzącym - 0.92 CZK/min (~EUR 0.04), bez dopłaty za agenta.

Odpowiedź o wykonaniu połączenia przychodzi dopiero po całym dzwonieniu (nawet kilkadziesiąt sekund) - to nie jest błąd, choć krótki timeout po Państwa stronie wyglądałby w tej chwili jak awaria, mimo że połączenie trwa.

4Rozwiązywanie problemów

Najczęstsze komunikaty przy własnym agencie i co z nimi zrobić:

5Rozliczanie

Połączenie wychodzące przez relay jest rozliczane według tej samej stawki co zwykłe połączenie wychodzące - 0.92 CZK/min (~EUR 0.04) - bez jakiejkolwiek dopłaty za agenta. Stawki podajemy bez VAT, tak jak cały cennik.

Liczba równoczesnych połączeń jest ograniczona (patrz limity poniżej): najwyżej 1 aktywne połączenie na jeden Państwa numer i najwyżej 2 na całe konto jednocześnie.

Osoba wywoływana zobaczy Państwa linię volai TYLKO wtedy, gdy numer ma własne nazwy relay (relayNames) - numer dostaje je zaraz po zakupie. Dopóki ich nie ma, lease przechodzi na wspólną pulę, a osoba wywoływana widzi numer demonstracyjny volai. Jeśli trwa to dłużej niż godzinę, proszę napisać do wsparcia.

6Limity, kwoty i zabezpieczenia

Limit aktywnych leasów to najwyżej 1 na numer oraz najwyżej 2 na konto - celowe zabezpieczenie przed zajęciem całej wspólnej puli slotów relay przez jednego klienta:

• from musi być Państwa własnym numerem volai - w przeciwnym razie from_number_not_owned. Bez tej kontroli można by podszywać się pod cudzą linię (spoofing identyfikatora dzwoniącego).
• Te same bramki co przy zwykłym połączeniu - lista numerów, na które nie wolno dzwonić (dotyczy tylko połączeń, nie SMS), automatyczna 30-dniowa blokada po 3 nieudanych próbach na ten sam numer w ciągu 24 godzin, linie o podwyższonej opłacie, ochrona przed pętlą między numerami volai, blokada numeru wywoływanego oraz ogólny limit częstotliwości połączeń. Żadnej z tych kontroli nie da się obejść przez relay.
• Pełna pula -> 503 capacity_busy - sloty relay to wspólny limit równoczesności CAŁEJ platformy, nie tylko Państwa konta. Przy capacity_busy nic nie jest naliczane, proszę spróbować ponownie za chwilę.
• Pełną dokumentację REST (kody błędów, GET/DELETE na leasach) znajdą Państwo w dokumentacji REST API.

Każdy błąd API zawiera cause (kto go naprawia) oraz action (co zrobić) - patrz Format błędów w dokumentacji REST API.