Anleitungen

Eigener Agent

Möchten Sie statt des integrierten Agenten Ihre eigene Sprachplattform - ElevenLabs Conversational AI im eigenen Workspace, Vapi, Retell oder auch ein eigenes Asterisk/FreeSWITCH-IVR - an eine volai-Nummer anbinden? Diese Seite beschreibt beide Richtungen: eingehende und ausgehende Anrufe. Bei ausgehenden Anrufen zahlen Sie zudem keinen Agentenaufschlag von 2,50 kr/min (≈ 0,10 EUR) - den Agenten betreiben (und bezahlen) Sie selbst bei Ihrer Plattform.

1Eigener Agent oder integrierter Agent

Beide Wege laufen über dieselbe Nummer und dasselbe Guthaben - sie unterscheiden sich nur darin, WER die Gesprächslogik betreibt und was das zusätzlich kostet:

2Eingehende Anrufe zu Ihrem eigenen Agenten

Keine neue Mechanik - es genügt die vorhandene mode: "sip" -Weiterleitung (wie bei Ihrem eigenen Softphone, siehe SIP) ) auf die sipUri -Adresse Ihrer Plattform. Für eine ElevenLabs-SIP-Trunk-Nummer, die in IHREM eigenen Workspace registriert ist, ist das eine Adresse mit derselben Nummer wie Ihre volai-Leitung:

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

Und in Ihrem ElevenLabs-Konto (Settings → Phone Numbers → Import → SIP trunk) registrieren Sie diese Nummer mit inbound_trunk_config:

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

allowed_addresses oben ist unser Signalisierungsbereich (81.31.45.0/24) - sicherer als das universelle 0.0.0.0/0, das ein INVITE von überall durchlässt. Beides lässt den Anruf durch, aber bei einem Import ohne Zugangsdaten ist die Allowlist die EINZIGE Prüfung - verwenden Sie daher den Bereich, nicht 0.0.0.0/0.

Sie nutzen eine andere Plattform als ElevenLabs? Das Prinzip ist dasselbe - ermitteln Sie dort die SIP-Adresse, an die Anrufe für Ihre Nummer gehen sollen, und tragen Sie diese ein in sipUri. Bei Vapi kommt derselbe Bereich in den BYO-Trunk als gateways.

Bei Vapi lautet die Weiterleitungsadresse sip:<E164>@<credentialId>.sip.vapi.ai - <credentialId> finden Sie bei Ihrem BYO-SIP-Trunk in Vapi; eine Organisation in der EU-Region verwendet statt sip.vapi.ai die Domain sip.eu.vapi.ai. Das nackte sip.vapi.ai gehört zu nativen Vapi-Nummern und funktioniert für eine Nummer von uns nicht. Lassen Sie Benutzername und Passwort beim BYO-Trunk leer, Vapi erkennt unsere Anrufe an der IP in den gateways.

Tragen Sie in die gateways den Bereich getrennt als IP 81.31.45.0 und Maske (netmask) 24 ein. Mit der Standardmaske 32 würde Vapi nur eine einzige Adresse zulassen und unsere Anrufe ablehnen.

3Ausgehende Anrufe von Ihrem eigenen Agenten (Relay)

Das ist die Gegenrichtung - Ihre Plattform wählt selbst nach außen. Die meisten Sprach-KI-Plattformen (auch ElevenLabs) können eine Telefonleitung aber nicht dauerhaft als SIP-Client registrieren - sie senden nur einen authentifizierten Anruf mit den Zugangsdaten Ihrer Leitung. Das Telefonnetz lässt einen solchen Anruf nicht direkt zur Zielnummer durch, deshalb führen Sie ihn über eine kurzlebige Relay-Verbindung:

1. Richten Sie Ihre Plattform auf Ihre Leitung aus

Rufen Sie die SIP-Zugangsdaten Ihrer Leitung ab:

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

Die Antwort liefert server (für das REGISTER eines Softphones, siehe SIP) und outboundTrunkAddress GETRENNT - sie sind nicht austauschbar.

Und tragen Sie outboundTrunkAddress - NICHT server - als ausgehenden Trunk Ihrer Plattform ein. Bei ElevenLabs ist das die outbound_trunk_config der betreffenden Telefonnummer (Settings → Phone Numbers → Ihre Nummer → Outbound calling), genau in dieser Form:

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

2. Relay-Verbindung erstellen

Rufen Sie kurz vor dem Anruf auf (die Verbindung hat eine kurze Lebensdauer, siehe die Limits unten):

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

Die Nummer des Angerufenen übergeben Sie UNS in to - die Plattform sieht sie nie, sie erhält nur den nackten sipName aus der Antwort.

3. Weisen Sie die Plattform an, den sipName anzurufen

Bei ElevenLabs bedeutet das, über /v1/convai/sip-trunk/outbound-call anzurufen, mit to_number direkt auf den sipNamegesetzt:

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

agent_id finden Sie bei Ihrem Agenten in ElevenLabs, agent_phone_number_id ist die phone_number_id der importierten Nummer - die Antwort des Imports liefert sie, oder Sie lesen sie aus der Liste Phone numbers ab.

Sie nutzen statt ElevenLabs einen eigenen SIP-Client oder eine Telefonanlage? Wählen Sie direkt die vollständige sipUri wie bei einem gewöhnlichen SIP-Anruf - die Einschränkung gilt nur für Plattformen, die einen nackten Namen ohne das Präfix sip: verlangen.

4. Was danach passiert

Das Telefonnetz nimmt den Anruf unter dem Namen volai_relay_2 an, verbindet ihn mit Ihrer to und setzt die angezeigte Rufnummer des Anrufers auf Ihre from - der Angerufene sieht auf dem Display Ihre volai-Leitung, nicht den internen Namen des Relay-Slots (sofern die Nummer eigene Relay-Namen hat - siehe Abrechnung unten, sonst sieht der Angerufene die Demo-Nummer von volai). Nach dem Ende des Anrufs wird der Lease freigegeben und die Minuten werden wie bei einem normalen ausgehenden Anruf abgerechnet - 0,92 kr/min (≈ 0,04 EUR), ohne Agentenaufschlag.

Die Antwort auf die Anrufwahl trifft erst nach dem gesamten Klingeln ein (durchaus Dutzende Sekunden) - das ist kein Fehler, aber ein kurzer Timeout auf Ihrer Seite würde in diesem Moment wie ein Fehlschlag wirken, obwohl der Anruf läuft.

4Fehlerbehebung

Die häufigsten Meldungen beim eigenen Agenten und was dagegen hilft:

5Abrechnung

Ein ausgehender Anruf über das Relay wird zum selben Tarif abgerechnet wie ein normaler ausgehender Anruf - 0,92 kr/min (≈ 0,04 EUR) - ganz ohne Agentenaufschlag. Die Preise verstehen sich ohne MwSt., wie die gesamte Preisliste.

Die Parallelität ist begrenzt (siehe die Limits unten): höchstens 1 aktiver Anruf pro Nummer und höchstens 2 pro Konto gleichzeitig.

Der Angerufene sieht Ihre volai-Leitung NUR, wenn die Nummer eigene Relay-Namen (relayNames) hat - die Nummer erhält sie direkt nach dem Kauf. Solange sie fehlen, fällt der Lease auf den gemeinsamen Pool zurück und der Angerufene sieht die Demo-Nummer von volai. Wenn das länger als eine Stunde dauert, schreiben Sie an den Support.

6Limits, Kontingente und Sicherheit

Die Obergrenze liegt bei 1 aktivem Lease pro Nummer und höchstens 2 pro Konto - eine bewusste Sicherung dagegen, dass ein einzelner Kunde den gesamten gemeinsamen Pool an Relay-Slots belegt:

• from muss Ihre eigene volai-Nummer sein - sonst from_number_not_owned. Ohne diese Prüfung könnte man sich als fremde Leitung ausgeben (Caller-ID-Spoofing).
• Dieselben Schranken wie bei einem normalen Anruf - Do-not-call-Liste (gilt nur für Anrufe, nicht für SMS), automatische 30-Tage-Sperre nach 3 erfolglosen Versuchen zur selben Nummer innerhalb von 24 Stunden, Premium-Rufnummern, Schutz vor Schleifen zwischen volai-Nummern, Sperre der angerufenen Nummer und das allgemeine Ratelimit für Anrufe. Nichts davon lässt sich über das Relay umgehen.
• Pool voll -> 503 capacity_busy - Relay-Slots sind eine gemeinsame Obergrenze der Parallelität für die GESAMTE Plattform, nicht nur für Ihr Konto. Bei capacity_busy wird nichts abgerechnet, versuchen Sie es in Kürze erneut.
• Die vollständige REST-Referenz (Fehlercodes, GET/DELETE zu Leases) finden Sie in der REST-API-Referenz.

Jeder API-Fehler enthält cause (wer ihn behebt) und action (was zu tun ist) - siehe Fehlerformat in der REST-API-Referenz.