Schnellstart
In vier Schritten von null zur ersten deutschen Rufnummer für deinen KI-Agenten.
Kapitel einzeln öffnenTrunkBeam gibt dir deutsche Rufnummern für Voice Agents. Du verwaltest sie im Dashboard, im Terminal, über einen MCP-Server oder per REST-API. Diese Seite führt einmal durch den ganzen Ablauf.
Voraussetzungen
- Eine Firma oder ein Gewerbe mit Sitz in Deutschland. Für eine Ortsnetznummer brauchst du einen Standort im jeweiligen Ortsnetz, für Berlin (030) also eine Berliner Adresse.
- Ein Voice-Stack, der SIP spricht, zum Beispiel ElevenLabs, OpenAI Realtime, Vapi, Retell AI, LiveKit oder Asterisk.
- Nur für CLI und MCP-Server: Node.js 22 oder neuer.
1. Zugang anfragen
TrunkBeam ist im Early Access. Frag deinen Zugang an, wir besprechen die Anbindung mit dir und schalten dein Konto unter https://app.trunkbeam.com frei. Zum Schutz richtest du beim ersten Anmelden die Zwei-Faktor-Anmeldung ein. Mehr dazu unter Konto und Prüfung.
2. Unternehmen prüfen lassen
Vor der ersten Rufnummer prüfen wir einmalig deine Firma und deinen Standort. Das erledigst du im Dashboard: Firmendaten, Standorte und je Standort ein Nachweis, zum Beispiel eine aktuelle Strom- oder Internetrechnung für genau diese Adresse. In der Regel sind wir innerhalb eines Werktags fertig. Danach kaufst du beliebig viele Nummern ohne neue Prüfung.
3. Nummer bestellen und verbinden
Im Dashboard unter Rufnummern wählst du deinen Standort, bestellst die Nummer und verbindest sie danach auf ihrer Detailseite mit deinem Agenten.
4. Beim Agenten eintragen
Damit Anrufe ankommen, trägst du die Nummer und die SIP-Daten bei deiner Voice-Plattform ein. Was genau wohin gehört, steht in den Plattform-Anleitungen für ElevenLabs, LiveKit, Vapi, Retell, Ultravox und OpenAI. Ab dann gehen Anrufe auf die Nummer an deinen Agenten.
Automatisiert per MCP-Server oder CLI
Alles aus Schritt 3 und 4 geht auch ohne Dashboard. Lege dafür im Dashboard unter API, CLI & MCP einen API-Schlüssel an. Mit dem MCP-Server erledigt dein KI-Assistent, zum Beispiel Claude Code, Codex oder Cursor, die Einrichtung auf Zuruf. Mit der CLI geht es so:
npx @trunkbeam/cli login # fragt den Schlüssel verdeckt ab
trunkbeam sites # Standort-ID nachsehen
trunkbeam numbers order --site 3 # zeigt den Preis und fragt nach
trunkbeam numbers connect 12 --elevenlabs # Nummer mit dem Agenten verbinden
trunkbeam guide elevenlabs --number 12 # was du bei ElevenLabs einträgst
Wie geht es weiter
- Durchstellen und Wartemusik, wenn ein Mensch übernehmen soll
- SIP-Anbindung, auch für ausgehende Anrufe
- MCP-Server einrichten für Claude Code, Codex und Cursor
Konto und Prüfung
Zugang, Prüfung von Unternehmen und Standorten, API-Schlüssel.
Kapitel einzeln öffnenRufnummern dürfen in Deutschland nur an echte Firmen mit passendem Standort vergeben werden. Das schreibt die Bundesnetzagentur vor. Geprüft wird deshalb einmalig vor der ersten Rufnummer.
Zugang
TrunkBeam ist im Early Access. Frag deinen Zugang an, dann besprechen wir die Anbindung und schalten dein Konto unter https://app.trunkbeam.com frei. Beim ersten Anmelden bestätigst du deine E-Mail-Adresse und richtest die Zwei-Faktor-Anmeldung mit einer Authenticator-App ein. Ohne sie geht es nicht ins Dashboard.
Unternehmen prüfen lassen
Die Prüfung startest du im Dashboard. Sie hat vier Schritte:
- Unternehmen: Firmendaten laut Handelsregister oder Gewerbeanmeldung.
- Standorte: Hauptsitz und gegebenenfalls weitere Niederlassungen, an denen du Ortsnetznummern willst.
- Nachweise: je Standort ein Standortnachweis (siehe unten). Ohne Handelsregistereintrag zusätzlich die Gewerbeanmeldung mit aktueller Anschrift, höchstens 3 Monate alt. Den Registerauszug rufen wir selbst ab.
- Einreichen: Angaben kontrollieren und bestätigen.
Ein Mensch prüft die Angaben, in der Regel innerhalb eines Werktags. Den Stand siehst du jederzeit im Dashboard. Danach bestellst du Nummern ohne neue Prüfung.
Standortnachweis
Eine Rechnung oder ein Bescheid auf deine Firma, für eine Leistung an genau dieser Adresse:
| Nachweis | höchstens |
|---|---|
| Internet- oder Festnetzrechnung mit Anschlussadresse | 3 Monate alt |
| Rechnung für Strom, Gas oder Wasser mit Lieferstelle | 3 Monate alt |
| Jahresabrechnung für Strom, Gas oder Wasser | 12 Monate alt |
| Müllgebühren- oder Grundbesitzabgabenbescheid der Gemeinde | 12 Monate alt |
| Nebenkostenabrechnung des Vermieters für diese Räume | 12 Monate alt |
| Gewerbesteuerbescheid mit Betriebsstätte | 12 Monate alt |
Handy-, Shop- oder Lieferantenrechnungen reichen nicht. Sie zeigen nur eine Postanschrift, die auch ein virtuelles Büro hätte.
Wenn wir ablehnen
Im Dashboard steht der Grund, zum Beispiel „Nachweis älter als 3 Monate“. Reiche den fehlenden Nachweis nach, dann prüfen wir erneut.
Welche Nummern es gibt
- Ortsnetznummer mit der Vorwahl eines geprüften Standorts, zum Beispiel 07422 für Schramberg. Für jedes weitere Ortsnetz brauchst du dort einen geprüften Standort.
- 032-Nummer ohne Ortsbezug. Dafür reicht ein Sitz in Deutschland.
Eine bestimmte Wunschnummer kannst du nicht aussuchen. Du bestellst eine Nummer für einen Standort und bekommst sie zugeteilt. Je Konto sind bis zu 25 Nummern möglich, mehr beantragst du im Dashboard unter Rufnummern.
API-Schlüssel
Für CLI, MCP-Server und REST-API legst du im Dashboard unter API, CLI & MCP einen Schlüssel an. Er beginnt mit tb_live_ und wird nur einmal angezeigt. Jeder Schlüssel hat Rechte:
| Recht | erlaubt |
|---|---|
Lesen (read) | Nummern, Agenten, Anrufe, Nutzung und Preise abrufen. Immer enthalten. |
Verwalten (manage) | Agenten, Zuordnung der Nummern und Weiterleitung ändern |
Bestellen (order) | Rufnummern bestellen und kündigen, verursacht Kosten |
Dazu wählst du eine Gültigkeit von 30, 90 oder 365 Tagen oder unbegrenzt. Ein Schlüssel lässt sich jederzeit widerrufen. Gib KI-Agenten einen eigenen Schlüssel und das Recht „Bestellen“ nur, wenn sie wirklich Nummern kaufen sollen.
Nur im Dashboard gehen: Prüfung und Nachweise, SIP-Zugang für ausgehende Anrufe, Tarifwechsel und das Anlegen von Schlüsseln.
Plattform-Anleitungen
Was du bei ElevenLabs, LiveKit, Vapi, Retell, Ultravox, OpenAI und anderen SIP-Zielen einträgst, damit deine Nummer beim Agenten ankommt.
Kapitel einzeln öffnenIn TrunkBeam trägst du an jeder Rufnummer nur ein, wohin Anrufe gehen sollen: die Adresse bei deinem Anbieter (SIP-URI). Alles Weitere stellst du beim Anbieter ein. Diese Seite zeigt für die gängigen Plattformen, wo du was findest.
Die Anleitung für ElevenLabs ist im Betrieb getestet. Die übrigen folgen den Dokumentationen der Anbieter (Stand September 2026). Die Felder dort können sich ändern.
Das Prinzip
| Richtung | Was passiert | Wo du es einstellst |
|---|---|---|
| Eingehend | TrunkBeam stellt Anrufe auf deine Nummer an die SIP-URI des Anbieters durch. | Dashboard → Rufnummern → Nummer → Verbindung |
| Ausgehend und Weiterleitung | Dein Agent ruft über TrunkBeam nach draußen an oder leitet weiter. Dafür meldet sich der Anbieter mit dem SIP-Zugang an. | Dashboard → Konto → SIP-Zugang |
Für ausgehende Anrufe gelten bei allen Anbietern dieselben Werte:
| Feld | Wert |
|---|---|
| Server / Address | sip.trunkbeam.com |
| Port | 5061 |
| Transport | TLS |
| Benutzername / Passwort | aus Konto → SIP-Zugang (das Passwort ist nur beim Erzeugen sichtbar) |
Das SIP-Ziel an der Nummer
- Adresse beim Anbieter: Nummer oder Kennung, Server und Übertragung (TLS, TCP oder UDP). Einen Port musst du nicht eintragen: Es gilt 5061 bei TLS, sonst 5060. Nur bei einem abweichenden Port hängst du ihn an den Server an, zum Beispiel
pbx.example.de:5080. Hast du eine fertige SIP-URI wiesip:+4930123456@sip.anbieter.example;transport=tls, füge sie in eines der oberen Felder ein; das Dashboard verteilt sie auf die Felder. So sind auch die SIP-URIs weiter unten gemeint. - Sprache verschlüsseln (SRTP): Standard. Beim Anbieter muss verschlüsselte Sprache erlaubt sein, sonst kommen Anrufe nicht durch. Im Anrufprotokoll steht dann „Verschlüsselung passt nicht (SIP 488)“.
- Benutzername und Passwort: nur einschalten, wenn der Anbieter sie für eingehende Anrufe verlangt. Die meisten erkennen TrunkBeam an der IP-Adresse. Die IP steht im Dashboard beim SIP-Ziel.
Nach dem Speichern die Nummer anrufen. Hebt der Agent nicht ab, steht der Grund im Dashboard unter Anrufe.
Angaben, die TrunkBeam mitschickt
| SIP-Header | Inhalt |
|---|---|
X-TrunkBeam-Called | die angerufene TrunkBeam-Nummer |
X-TrunkBeam-Transfer | nur bei Rückkehr nach einer Weiterleitung: der Grund (no-answer, busy, unavailable, not-allowed, limit) |
X-TrunkBeam-Transfer-Target | nur bei Rückkehr: die Nummer, die nicht abgenommen hat |
Weiterleiten kann der Agent per SIP REFER an tel:+49… oder sip:+49…@sip.trunkbeam.com. Mehr dazu unter Durchstellen und Wartemusik.
ElevenLabs Agents
SIP-URI in TrunkBeam: sip:+49…@sip.rtc.elevenlabs.io;transport=tls mit deiner TrunkBeam-Nummer. Sprache verschlüsseln an, Benutzername und Passwort wie in ElevenLabs.
- Nummer importieren: ElevenLabs → Agents → Phone Numbers → Import number → From SIP trunk.
- Label:
TrunkBeam - Phone Number: deine TrunkBeam-Nummer mit +, genau wie in der SIP-URI
- Label:
- Inbound Configuration
- Media Encryption: Allowed oder Required. Mit „Disabled“ kommen Anrufe nicht durch.
- Authentication: an. Benutzername und Passwort frei wählen und dieselben Werte in TrunkBeam beim SIP-Ziel eintragen. Ohne Authentication nimmt ElevenLabs Anrufe von jedem an.
- Alle anderen Schalter bleiben aus. Eine IP-Freigabe (Allowed Addresses) und Remote Domains sind nicht nötig. Wer Remote Domains trotzdem setzen will:
sip.trunkbeam.com.
- Outbound Configuration für Anrufe nach draußen und Weiterleitungen
- Address:
sip.trunkbeam.com - Transport Type: TLS
- Media Encryption: Required
- Username / Password: aus Konto → SIP-Zugang
- Address:
- Agent zuweisen: der importierten Nummer den Agenten zuweisen und die Nummer anrufen.
Weiterleiten: System-Tool „Transfer to number“ mit Transfer-Typ SIP REFER. Ohne REFER („Conference“) baut ElevenLabs einen zweiten Anruf über TrunkBeam auf.
- Die angerufene Nummer steht dem Agenten als
{{sip_trunkbeam_called}}zur Verfügung. - Ruft TrunkBeam den Agenten nach einer erfolglosen Weiterleitung zurück, stehen Grund und Nummer in
{{sip_trunkbeam_transfer}}und{{sip_trunkbeam_transfer_target}}. Im Prompt darauf eingehen, zum Beispiel eine Nachricht aufnehmen, statt neu zu begrüßen. - ElevenLabs wartet nur etwa 10 bis 15 Sekunden auf das Ergebnis einer Weiterleitung. Mit Erreichbarkeitsprüfung klingelt es deshalb höchstens 12 Sekunden.
Dokumentation von ElevenLabs: SIP-Trunking, Transfer to number
LiveKit Cloud
SIP-URI in TrunkBeam: sip:+49…@<subdomain>.eu.sip.livekit.cloud;transport=tls. Die Adresse steht unter Settings → Project. Benutzername und Passwort einschalten, mit denselben Werten wie im Inbound-Trunk.
-
Inbound-Trunk: LiveKit Cloud → Telephony → SIP trunks → Create inbound trunk, oder per CLI:
lk sip inbound create --name trunkbeam --numbers "+49…" \ --auth-user "<Benutzername>" --auth-pass "<Passwort>"Für die Header von TrunkBeam
include_headers: SIP_X_HEADERSsetzen. Sie erscheinen dann als Attributesip.h.x-trunkbeam-calledundsip.h.x-trunkbeam-transfer. -
Dispatch-Regel: Telephony → Dispatch rules, Anrufe dieses Trunks an den Agenten.
-
Outbound-Trunk für Anrufe nach draußen und Weiterleitungen:
lk sip outbound create --name trunkbeam --address sip.trunkbeam.com --transport tls \ --numbers "+49…" --auth-user "<SIP-Zugang Benutzername>" --auth-pass "<SIP-Zugang Passwort>"
Weiterleiten: TransferSIPParticipant sendet ein SIP REFER, transfer_to als tel:+49… oder sip:….
Eine IP-Freigabe gibt es in LiveKit Cloud nur über den Support. Benutzername und Passwort reichen.
Dokumentation von LiveKit: SIP-Trunk einrichten, SIP-API, Transfer
LiveKit selbst betrieben
Wie LiveKit Cloud, mit dem SIP-Dienst livekit/sip auf deinem Server.
- SIP-URI in TrunkBeam:
sip:+49…@sip.deine-domain.example;transport=tls. Das Zertifikat muss zum Hostnamen passen. - Im SIP-Dienst öffentliche IP und TLS einrichten. In der Firewall SIP (5060/5061) und die RTP-Ports (Standard 10000–20000) für die IP von TrunkBeam öffnen.
- Inbound-Trunk mit Benutzername und Passwort oder mit IP-Freigabe (
--allowed-addresses <IP>/32). Bei IP-Freigabe in TrunkBeam keine Zugangsdaten eintragen. - Outbound-Trunk wie bei LiveKit Cloud.
Vapi
SIP-URI in TrunkBeam: sip:+49…@<credentialId>.sip.eu.vapi.ai für EU-Konten, sonst <credentialId>.sip.vapi.ai. Keine Zugangsdaten, Vapi erkennt TrunkBeam an der IP.
-
Credential anlegen per API, EU-Konten über
api.eu.vapi.ai:POST /credential { "provider": "byo-sip-trunk", "name": "TrunkBeam", "gateways": [{ "ip": "<IP von TrunkBeam>", "port": 5061, "inboundEnabled": true, "outboundEnabled": true, "outboundProtocol": "tls" }], "outboundAuthenticationPlan": { "authUsername": "<SIP-Zugang Benutzername>", "authPassword": "<SIP-Zugang Passwort>" } } -
Telefonnummer anlegen:
POST /phone-number { "provider": "byo-phone-number", "number": "+49…", "credentialId": "<credentialId>", "numberE164CheckEnabled": true }
Weiterleiten: Tool transferCall mit destination { "type": "sip", "sipUri": "sip:+49…@sip.trunkbeam.com" }. Vapi nutzt dafür standardmäßig REFER.
Dokumentation von Vapi: SIP-Trunk, Netzwerk
Retell AI
SIP-URI in TrunkBeam: sip:+49…@sip.retellai.com;transport=tcp. Keine Zugangsdaten.
Bei Retell unter Phone Numbers → Connect via SIP trunking:
| Feld | Wert |
|---|---|
| Phone Number | deine TrunkBeam-Nummer im Format E.164 |
| Termination URI | sip.trunkbeam.com |
| Transport | TLS |
| SIP Trunk User Name / Password | aus Konto → SIP-Zugang |
| Inbound Agent | der gewünschte Agent |
Um diese Werte später zu ändern, die Nummer bei Retell löschen und neu importieren.
Weiterleiten: Retell leitet standardmäßig per neuem Anruf weiter und bleibt dabei im Gespräch. Mit der Option „SIP REFER“ gibt Retell den Anruf an TrunkBeam ab.
Dokumentation von Retell: Custom Telephony, Transfer
Ultravox
SIP-URI in TrunkBeam: sip:agent_<agentId>@<SIP-Domain deines Kontos>. Die Domain liefert GET /api/sip. Keine Zugangsdaten.
-
TrunkBeam freigeben:
PATCH /api/sipmit{ "allowedCidrRanges": ["<IP von TrunkBeam>/32"] }. -
Ausgehend: Anruf mit
mediumsip.outgoing:{ "sip": { "outgoing": { "to": "sip:+49…@sip.trunkbeam.com;transport=tls", "from": "+49…", "username": "<SIP-Zugang Benutzername>", "password": "<SIP-Zugang Passwort>" } } }
Weiterleiten: Das eingebaute coldTransfer sendet ein SIP REFER an sip:+49…@sip.trunkbeam.com.
Dokumentation von Ultravox: SIP, Transfers
OpenAI Realtime
Nur eingehend. SIP-URI in TrunkBeam: sip:proj_…@sip.api.openai.com;transport=tls, in der EU sip-eu.api.openai.com. Sprache verschlüsseln an, das verlangt OpenAI. Keine Zugangsdaten.
- OpenAI → Projekt → Webhooks: Event
realtime.call.incomingan dein Backend. - Dein Backend nimmt jeden Anruf per
POST /v1/realtime/calls/{call_id}/acceptan, mit Modell, Anweisungen und Stimme. Die SIP-Header von TrunkBeam stehen im Webhook unterdata.sip_headers.
Weiterleiten: POST /v1/realtime/calls/{call_id}/refer mit target_uri tel:+49….
Dokumentation von OpenAI: Realtime SIP
Deepgram Voice Agent
Deepgram hat keine SIP-Schnittstelle. Baue den Agenten mit LiveKit Agents und den Deepgram-Plugins und binde ihn wie LiveKit an. Alternativ Pipecat mit Daily- oder LiveKit-Transport.
Dokumentation von Deepgram: Deepgram mit LiveKit
Andere SIP-Ziele
Für eine eigene Telefonanlage, Asterisk, FreeSWITCH, Synthflow oder jeden anderen SIP-Server:
- SIP-URI mit Host, Port und Transport des Ziels, zum Beispiel
sip:empfang@pbx.example.de:5061;transport=tls. - Anrufe von TrunkBeam zulassen: Benutzername und Passwort (Digest) oder die IP von TrunkBeam freigeben.
- Codecs: G.722 und G.711 (PCMA/PCMU).
- Ausgehend: Server
sip.trunkbeam.com, Port 5061, TLS, mit dem SIP-Zugang.
Pipecat hat keinen eigenen SIP-Eingang. Die Einwahl über Daily setzt voraus, dass der Anbieter den laufenden Anruf per API an eine Adresse weiterreicht, die Daily für jeden Anruf neu vergibt; TrunkBeam stellt an eine feste Adresse je Nummer zu. Zwei Wege funktionieren: Pipecat mit dem LiveKit-Transport betreiben und die Nummer wie oben bei LiveKit verbinden, oder einen eigenen Asterisk oder FreeSWITCH als SIP-Ziel eintragen, der den Ton an Pipecat weitergibt.
Noch nicht möglich sind Ziele, die ausgehend nur eine IP-Freigabe statt Passwort können, zum Beispiel Daily Dial-out, und Ziele, die zwingend Opus verlangen.
SIP-Anbindung
Eingehende Anrufe per SIP an deinen Agenten leiten und ausgehend über deine Nummer telefonieren.
Kapitel einzeln öffnenEingehende Anrufe
Jede Nummer zeigt auf ein SIP-Ziel, die Agent-Anbindung. Dorthin schicken wir jeden eingehenden Anruf. Du setzt das Ziel im Dashboard unter Rufnummern oder per CLI:
trunkbeam numbers connect 12 --sip-uri "sip:agent@voice.example;transport=tls"
trunkbeam numbers connect 12 --elevenlabs # ElevenLabs in einem Schritt
Antwortet dein Agent nicht, zum Beispiel bei einer Störung beim Anbieter, kann stattdessen eine normale deutsche Rufnummer klingeln, etwa dein Büro. Wie lange der Agent zum Abheben hat, stellst du mit --after ein (5 bis 30 Sekunden, Standard 8):
trunkbeam numbers fallback 12 "07422 123456" --after 10
Im SIP-INVITE bekommst du die Nummer des Anrufers im From-Header und deine gewählte Nummer im To-Header, zusätzlich im Header X-TrunkBeam-Called. So kann dein Agent pro Nummer anders reagieren.
Ausgehende Anrufe
Für Anrufe deines Agenten nach draußen und für Weiterleitungen legst du im Dashboard unter SIP-Zugang einen Zugang an. Du bekommst Benutzername und Passwort, die du zusammen mit diesen Werten bei deiner Voice-Plattform einträgst:
Host: sip.trunkbeam.com
Port: 5061
Transport: TLS
Benutzer: (aus dem Dashboard)
Passwort: (wird einmal angezeigt)
Als Absender sind nur Nummern aus deinem Konto erlaubt. Andere Absender lehnen wir ab, damit niemand mit fremden Nummern telefoniert.
Einrichtung bei deiner Plattform
Die Voice-Plattformen nennen das meist „Bring your own SIP trunk“, „Custom telephony“ oder „SIP trunk“. Der Ablauf ist überall ähnlich:
- Bei der Plattform einen SIP-Trunk mit Host
sip.trunkbeam.comund den Zugangsdaten von oben anlegen. - Deine Nummer bei der Plattform eintragen und dem Agenten zuweisen.
- Die SIP-Adresse, die die Plattform für eingehende Anrufe nennt, bei uns als Ziel setzen.
trunkbeam guide <anbieter> --number <id> zeigt dir diese Schritte mit deinen echten Werten.
Was du bei ElevenLabs, LiveKit, Vapi, Retell, Ultravox und OpenAI genau einträgst, steht in den Plattform-Anleitungen.
HD-Telefonie mit G.722
TrunkBeam unterstützt HD-Telefonie mit dem Breitband-Codec G.722. Der Codec überträgt einen größeren Sprachfrequenzbereich als klassische Schmalband-Telefonie.
HD-Qualität setzt voraus, dass Endgerät, Voice-Plattform und der gesamte Verbindungsweg Breitbandaudio unterstützen. Auf der SIP-Verbindung müssen die beteiligten Systeme einen passenden Codec aushandeln. Ein HD-fähiges Telefon allein reicht nicht aus, wenn eine andere Teilstrecke nur Schmalband-Audio überträgt, etwa mit G.711. Eine spätere Umwandlung in G.722 stellt die dabei verlorenen Frequenzen nicht wieder her.
Das gilt auch beim Durchstellen: Ob die Verbindung zum neuen Ziel HD-Qualität bietet, hängt von dessen Endgerät und dem Verbindungsweg ab.
Technischer Hintergrund: ITU-T G.722 und Codec-Aushandlung mit SDP nach RFC 3264.
Technische Eckdaten
| Signalisierung | SIP über TLS (Port 5061) |
| Medien | SRTP und RTP |
| Codecs | G.722, G.711 A-law (PCMA), G.711 µ-law (PCMU) |
| DTMF | RFC 2833 (telephone-event) |
| Rufnummernformat | E.164, zum Beispiel +493023125417 |
Die IP-Bereiche für Firewall-Freigaben veröffentlichen wir zum Start.
Durchstellen und Wartemusik
Anrufe vom Voice Agent an Menschen übergeben. Direkt per Blind Transfer oder mit Erreichbarkeitsprüfung, Rückkehr zum Agenten und konfigurierbarer Wartemusik.
Kapitel einzeln öffnenTrunkBeam unterstützt zwei Arten, einen Anruf vom Voice Agent an einen Menschen weiterzugeben. Beide Transfer-Arten und die konfigurierbare Wartemusik sind bereits nutzbar. Den Zugang zur Plattform stimmen wir im Early Access mit dir ab.
Blind Transfer: direkt weiterleiten
Beim Blind Transfer gibt der Agent den Anruf direkt an das hinterlegte Ziel ab. Er wartet nicht darauf, dass die Person annimmt, und verlässt das Gespräch. Eine Rückkehr zum Agenten ist bei diesem Ablauf nicht vorgesehen.
Das eignet sich, wenn das Ziel die weitere Behandlung des Anrufs selbst übernimmt, zum Beispiel eine Telefonanlage mit einer eigenen Warteschlange. Eine erfolgreiche Übergabe bedeutet noch nicht, dass ein Mensch den Anruf angenommen hat.
Weiterleitung mit Erreichbarkeitsprüfung
Wenn du den Anrufer bei Nichterreichbarkeit wieder beim Agenten haben möchtest, nutze die Weiterleitung mit Erreichbarkeitsprüfung:
- Der Agent kündigt die Weiterleitung an.
- Das Ziel wird angerufen. Der Anrufer hört währenddessen die konfigurierte Wartemusik.
- Nimmt das Ziel an, wird der Anrufer verbunden und der Agent verlässt das Gespräch.
- Ist das Ziel besetzt oder nimmt niemand ab, wird das Gespräch mit dem Agenten fortgesetzt.
Der Agent kann dann beispielsweise sagen: „Am Empfang ist gerade niemand erreichbar. Wie kann ich dir sonst weiterhelfen?“ Ob er einen Rückruf aufnimmt oder selbst weiterhilft, bestimmst du in deiner Gesprächslogik.
Die Erreichbarkeitsprüfung ist keine Zusage eines zusätzlichen Vorgesprächs zwischen Agent und Mitarbeiter. Ein solcher konsultativer Ablauf wird häufig als „Warm Transfer“ oder „Attended Transfer“ bezeichnet. Hier beschreiben wir ausdrücklich die Prüfung auf Annahme und die Rückkehr zum Agenten.
Wartemusik selbst konfigurieren
Für die Wartephase stehen verschiedene Wartemusiken zur Verfügung. Du kannst konfigurieren, was Anrufer hören, während es beim Ziel klingelt: den üblichen Klingelton oder eine Wartemusik. Das gilt für beide Arten – beim Blind Transfer auch, während die Rückfallnummern angerufen werden. Nach der Annahme oder der Rückkehr zum Agenten endet die Wartephase.
Die Auswahl betrifft den tatsächlichen Anrufablauf. Das Beispiel auf der Startseite veranschaulicht ihn, ohne einen echten Anruf auszulösen oder Einstellungen zu speichern.
SIP REFER und dein Voice-Stack
SIP REFER ist eine Möglichkeit, eine Weiterleitung im SIP-Netz anzustoßen. Für die Nutzung muss dein Voice-Stack die erforderliche Signalisierung unterstützen. Ob eine Weiterleitung direkt erfolgt oder eine Rückkehr zum Agenten möglich ist, hängt auch von der Integration und dem gewählten Ablauf ab.
Die Weiterleitung stellst du im Dashboard unter Weiterleitung ein, per CLI mit trunkbeam transfer set, über den MCP-Server oder per REST-API. Als Standard für alle Nummern oder je Nummer eigens. Die genaue Einrichtung für deinen Stack klären wir beim Onboarding. Wir behaupten keine pauschale Unterstützung aller Transfer-Arten durch jede aufgeführte Plattform.
Technischer Hintergrund: IETF RFC 5589 zu SIP Call Transfer.
Ziele und Gesprächskosten
Für den Betrieb legst du fest, welche Ziele dein Agent verwenden darf. Stimme Zielnummern, SIP-Adressen und den Umgang mit nicht erreichbaren Anschlüssen vor dem ersten produktiven Anruf ab.
Eine Weiterleitung kann neben der eingehenden Verbindung eine Verbindung zum Ziel verursachen. Konkrete Gesprächskosten und Abrechnungsregeln erhältst du vor dem Start. Siehe Preise und Abrechnung.
Zugang und nächste Schritte
Du möchtest einen bestehenden Voice Agent anbinden? Early Access anfragen oder zunächst die SIP-Anbindung ansehen.
MCP-Server
Nummern direkt aus Claude Code, Codex, Cursor oder jedem anderen MCP-Client verwalten.
Kapitel einzeln öffnenÜber den MCP-Server bestellt dein KI-Assistent Nummern, verbindet sie mit deinem Agenten und stellt Weiterleitung und Wartemusik ein. Du sagst in einem Satz, was du brauchst, der Assistent ruft die passenden Werkzeuge auf.
Der Server läuft lokal über npx @trunkbeam/mcp, Voraussetzung ist Node.js 22 oder neuer. Den API-Schlüssel legst du im Dashboard unter API, CLI & MCP an und gibst ihn als Umgebungsvariable TRUNKBEAM_API_KEY mit.
Werkzeuge
| Werkzeug | Was es macht | Recht |
|---|---|---|
trunkbeam_account | Konto, Prüfstatus, Tarif und Rechte des Schlüssels | Lesen |
trunkbeam_prices | Tarife und Preise | Lesen |
trunkbeam_list_sites | Standorte; nur geprüfte bekommen Ortsnetznummern | Lesen |
trunkbeam_search_area_code | Ortsnetz zu Ort oder Vorwahl suchen | Lesen |
trunkbeam_list_numbers | Deine Nummern mit Ziel | Lesen |
trunkbeam_order_number | Ortsnetz- oder 032-Nummer bestellen, mit Rückfrage | Bestellen |
trunkbeam_list_number_requests | Bestellungen und ihr Stand | Lesen |
trunkbeam_release_number | Nummer kündigen, mit Rückfrage | Bestellen |
trunkbeam_connect_number_elevenlabs | Nummer in einem Schritt mit ElevenLabs verbinden | Verwalten |
trunkbeam_set_number_target | Nummer an eine beliebige SIP-Adresse leiten | Verwalten |
trunkbeam_set_number_agent_fallback | Ersatznummer, wenn der Agent nicht erreichbar ist | Verwalten |
trunkbeam_list_connections | Agent-Anbindungen (SIP-Ziele) | Lesen |
trunkbeam_create_connection | Agent-Anbindung anlegen | Verwalten |
trunkbeam_delete_connection | Agent-Anbindung löschen | Verwalten |
trunkbeam_provider_guide | Einrichtungsanleitung je Anbieter mit deinen echten Werten | Lesen |
trunkbeam_get_transfer_policy | Weiterleitung an Menschen anzeigen | Lesen |
trunkbeam_set_transfer_policy | Weiterleitung ändern, als Standard oder je Nummer | Verwalten |
trunkbeam_reset_number_transfer_policy | Eigene Weiterleitung einer Nummer löschen | Verwalten |
trunkbeam_list_hold_music | Wartemusik mit Beschreibung, damit der Assistent ein passendes Stück wählt | Lesen |
trunkbeam_list_calls | Letzte Anrufe | Lesen |
trunkbeam_usage | Nutzung und Kosten eines Monats | Lesen |
Bestellen und Kündigen laufen immer in zwei Schritten: Zuerst holt der Assistent ein Angebot mit Preis und zeigt es dir. Erst nach deiner Zustimmung bestätigt er. Eine Bestätigung ohne vorheriges Angebot lehnt der Server ab.
Claude Code
claude mcp add trunkbeam \
-e TRUNKBEAM_API_KEY=tb_live_… \
-- npx -y @trunkbeam/mcp
Mit --scope user steht der Server in allen Projekten zur Verfügung. Mit --scope project landet er in der .mcp.json des Repos und damit bei deinem ganzen Team, dann gehört der Schlüssel aber nicht in die Datei. Prüfen mit:
claude mcp list
Codex
codex mcp add trunkbeam \
--env TRUNKBEAM_API_KEY=tb_live_… \
-- npx -y @trunkbeam/mcp
Oder direkt in ~/.codex/config.toml:
[mcp_servers.trunkbeam]
command = "npx"
args = ["-y", "@trunkbeam/mcp"]
[mcp_servers.trunkbeam.env]
TRUNKBEAM_API_KEY = "tb_live_…"
Prüfen mit codex mcp list.
Cursor, Claude Desktop und andere
In .cursor/mcp.json im Projekt, ~/.cursor/mcp.json für alle Projekte oder bei Claude Desktop in claude_desktop_config.json:
{
"mcpServers": {
"trunkbeam": {
"command": "npx",
"args": ["-y", "@trunkbeam/mcp"],
"env": { "TRUNKBEAM_API_KEY": "tb_live_…" }
}
}
}
Windsurf und die meisten anderen Clients lesen denselben mcpServers-Block.
Schlüssel für Assistenten
Gib deinem Assistenten einen eigenen Schlüssel mit begrenzter Gültigkeit. Für reines Nachschauen genügt das Recht „Lesen“. „Verwalten“ braucht er, wenn er Ziele oder die Weiterleitung ändern soll, „Bestellen“ nur, wenn er wirklich Nummern kaufen darf. Einen Schlüssel kannst du im Dashboard jederzeit widerrufen.
Beispiel
Besorg uns eine Nummer für unseren Standort Schramberg und verbinde sie mit unserem ElevenLabs-Agenten.
Der Assistent listet die Standorte, holt das Angebot für eine Ortsnetznummer im Ortsnetz 07422 und fragt dich nach dem Preis. Nach deinem OK bestellt er, verbindet die Nummer mit ElevenLabs und zeigt dir, was du bei ElevenLabs eintragen musst.
CLI
Installation, Anmeldung und alle Befehle der Kommandozeile.
Kapitel einzeln öffnenInstallation
npm install -g @trunkbeam/cli
Alternativ ohne Installation mit npx @trunkbeam/cli <befehl>. Voraussetzung ist Node.js 22 oder neuer.
Anmelden
Lege im Dashboard unter API, CLI & MCP einen API-Schlüssel an. Dann:
trunkbeam login
Die CLI fragt den Schlüssel verdeckt ab, prüft ihn und speichert ihn in ~/.config/trunkbeam/config.json, nur für deinen Benutzer lesbar. trunkbeam logout löscht ihn wieder.
Auf Servern und in CI setzt du stattdessen die Umgebungsvariable:
export TRUNKBEAM_API_KEY=tb_live_…
Reihenfolge: --key vor TRUNKBEAM_API_KEY vor der gespeicherten Datei.
Globale Optionen
| Option | Wirkung |
|---|---|
--json | Rohdaten der API als JSON, für Skripte |
--yes, -y | Kostenpflichtige Aktionen ohne Rückfrage ausführen |
--key <schlüssel> | Anderen API-Schlüssel für diesen Aufruf verwenden |
--help, -h | Hilfe, auch je Befehl: trunkbeam numbers --help |
Befehle
| Befehl | Was er macht |
|---|---|
login, logout | CLI anmelden oder abmelden |
account | Konto, Prüfstatus, Tarif und Rechte des Schlüssels |
sites | Standorte mit ID; nur geprüfte bekommen Ortsnetznummern |
onkz <ort oder vorwahl> | Ortsnetz suchen, zum Beispiel onkz Schramberg |
numbers ls | Deine Nummern mit ID, Status und Ziel |
numbers order --site <id> | Ortsnetznummer am Standort bestellen, zeigt erst den Preis |
numbers order --032 | 032-Nummer ohne Ortsbezug bestellen |
numbers connect <id> --elevenlabs | Nummer in einem Schritt mit ElevenLabs verbinden |
numbers connect <id> --sip-uri <uri> | Nummer an eine beliebige SIP-Adresse leiten |
numbers fallback <id> <nummer> | Ersatznummer, wenn der Agent nicht erreichbar ist |
numbers release <id> | Nummer kündigen, fragt vorher nach |
requests ls, requests rm <id> | Bestellungen ansehen, offene zurückziehen |
connections ls, connections add, connections rm <id> | Agent-Anbindungen (SIP-Ziele) verwalten |
guide <anbieter> --number <id> | Einrichtungsanleitung mit deinen echten Werten |
transfer get, transfer set, transfer reset | Weiterleitung an Menschen, als Standard oder je Nummer |
hold-music | Wartemusik mit Beschreibung |
calls ls | Letzte Anrufe mit Dauer, Status und Kosten |
usage --month <JJJJ-MM> | Nutzung und Kosten eines Monats |
prices | Tarife und Preise |
Anbieter für guide und connections add --provider: elevenlabs, livekit, livekit_self, vapi, retell, ultravox, openai, deepgram, sip.
In Skripten
Mit --json und --yes läuft alles ohne Rückfrage. Beispiel: für einen neuen Kunden eine Nummer am Standort 3 holen und an seinen Agenten leiten.
id=$(trunkbeam numbers order --site 3 --yes --json | jq -r '.assigned.id')
trunkbeam numbers connect "$id" --sip-uri "sip:kunde-42@voice.example" --json
Ist gerade keine Nummer sofort verfügbar, steht in assigned der Wert null und die Bestellung bleibt offen. Den Stand zeigt trunkbeam requests ls.
Rückgabewerte
| Code | Bedeutung |
|---|---|
0 | Erfolgreich |
1 | Fehler oder abgebrochen |
2 | Falscher Aufruf |
REST-API
Alle Funktionen per HTTP, für eigene Oberflächen, Onboarding-Strecken und Automatisierungen.
Kapitel einzeln öffnenGrundlagen
| Basis-URL | https://app.trunkbeam.com/v1 |
| Anmeldung | Authorization: Bearer tb_live_… |
| Format | JSON, Zeitangaben nach ISO 8601 |
| Rufnummern | E.164, zum Beispiel +497422944120 |
| Grenze | 120 Anfragen pro Minute und Schlüssel |
| Beschreibung | OpenAPI 3.1 unter https://app.trunkbeam.com/v1/openapi.json |
curl https://app.trunkbeam.com/v1/numbers \
-H "Authorization: Bearer $TRUNKBEAM_API_KEY"
Den Schlüssel legst du im Dashboard unter API, CLI & MCP an. Jeder Schlüssel hat die Rechte Lesen (read), Verwalten (manage) und Bestellen (order), siehe Konto und Prüfung.
Endpunkte
| Methode | Pfad | Zweck | Recht |
|---|---|---|---|
GET | /account | Konto, Tarif, Prüfstatus, Rechte des Schlüssels | read |
GET | /prices | Tarife und Preise | read |
GET | /verification | Stand der Prüfung und Standorte | read |
GET | /onkz?q=Schramberg | Ortsnetz zu Ort oder Vorwahl suchen | read |
GET | /numbers | Deine Nummern mit Ziel | read |
POST | /number-requests | Nummer bestellen (Ortsnetz am Standort oder 032) | order |
GET | /number-requests | Bestellungen und ihr Stand | read |
DELETE | /number-requests/{id} | Offene Bestellung zurückziehen | order |
POST | /numbers/{id}/connect | Nummer in einem Schritt mit ElevenLabs verbinden | manage |
PUT | /numbers/{id}/target | Nummer an eine SIP-Adresse leiten | manage |
PATCH | /numbers/{id} | Agent, Bezeichnung oder Ersatznummer ändern | manage |
POST | /numbers/{id}/release | Nummer kündigen | order |
GET | /connections | Agent-Anbindungen (SIP-Ziele) | read |
POST | /connections | Agent-Anbindung anlegen | manage |
PATCH | /connections/{id} | Agent-Anbindung ändern | manage |
DELETE | /connections/{id} | Agent-Anbindung löschen | manage |
GET | /agent-problems | Warum Anrufe den Agenten nicht erreicht haben | read |
GET | /credential | SIP-Zugang für ausgehende Anrufe (ohne Passwort) | read |
GET | /transfer-policy | Standard-Weiterleitung | read |
PUT | /transfer-policy | Standard-Weiterleitung setzen | manage |
GET | /transfer-policies | Standard und geltende Regel je Nummer | read |
GET, PUT, DELETE | /numbers/{id}/transfer-policy | Eigene Weiterleitung einer Nummer | read / manage |
GET | /hold-music | Wartemusik mit Beschreibung | read |
GET | /calls | Anrufprotokoll, neueste zuerst | read |
GET | /calls/export | Einzelverbindungen als CSV | read |
GET | /usage?month=2026-10 | Nutzung und Kosten eines Monats | read |
GET | /usage/daily | Anrufe und Minuten je Tag | read |
GET | /usage/export | Tagessummen eines Monats als CSV | read |
GET, PUT | /call-log-settings | Anrufprotokoll einstellen | read / manage |
Nur im Dashboard gehen Prüfung und Nachweise, das Anlegen des SIP-Zugangs, Tarifwechsel und API-Schlüssel.
Nummer bestellen
Kostenpflichtige Aktionen laufen in zwei Schritten, damit kein Skript und kein KI-Agent versehentlich kauft. Ohne confirm kommt nur ein Angebot zurück:
curl https://app.trunkbeam.com/v1/number-requests \
-H "Authorization: Bearer $TRUNKBEAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "geographic", "siteId": 3}'
{
"confirmRequired": true,
"action": "order_number",
"monthlyEur": <Monatspreis netto>,
"message": "Ortsnetznummer im Ortsnetz 07422 für … € netto im Monat …"
}
Dieselbe Anfrage mit "confirm": true bestellt verbindlich:
{
"request": { "id": 41, "kind": "geographic", "status": "fulfilled", "numberE164": "+497422944121" },
"assigned": { "id": 12, "e164": "+497422944121", "status": "active" }
}
Ist gerade keine Nummer sofort verfügbar, ist assigned gleich null und die Bestellung bleibt offen, bis wir die Nummer zuteilen. Für eine 032-Nummer schickst du {"kind": "national032"}. Die Antworten sind hier gekürzt, die vollständigen Felder stehen in der OpenAPI-Beschreibung.
Fehler
{ "error": "Standort ist noch nicht geprüft", "code": "invalid" }
| HTTP | code | Bedeutung |
|---|---|---|
| 400 | invalid | Eingabe fehlt oder ist falsch |
| 401 | unauthorized | Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen |
| 403 | forbidden | Dem Schlüssel fehlt das Recht, oder die Funktion gibt es nur im Dashboard |
| 403 | org_pending | Vor der ersten Rufnummer muss die Prüfung abgeschlossen sein |
| 404 | not_found | Nummer, Anbindung oder Bestellung gibt es nicht |
| 409 | invalid | Passt gerade nicht, zum Beispiel Nummernlimit erreicht |
| 429 | forbidden | Mehr als 120 Anfragen pro Minute |
Preise und Abrechnung
So schlüsseln wir Rufnummern, Gesprächsminuten und weitere Leistungen auf. Die geltenden Konditionen erhältst du vor deinem Start.
Kapitel einzeln öffnenWir bauen TrunkBeam mit dem Anspruch, Telefonie zu fairen und nachvollziehbaren Preisen anzubieten. Dazu gehört eine transparente Preisaufschlüsselung.
Die öffentlichen Tarife stehen noch nicht fest. Die für deinen Einsatz geltenden Preise und Abrechnungsregeln klären wir mit dir vor dem Start. Für diese Leistungen erhältst du Konditionen auf Anfrage:
| Leistung | Preis |
|---|---|
| Deutsche Ortsnetznummer | Auf Anfrage |
| 032-Nummer ohne Ortsbezug | Auf Anfrage |
| Eingehende Anrufe | Auf Anfrage |
| Ausgehend ins deutsche Festnetz | Auf Anfrage |
| Ausgehend in deutsche Mobilfunknetze | Auf Anfrage |
| Durchstellen per SIP REFER | Auf Anfrage |
| Einrichtung und Prüfung | Auf Anfrage |
Sag uns, welche Rufnummern und Anrufziele du brauchst. Frag deinen Zugang und die passenden Konditionen an.
Transparente Preisaufschlüsselung
Rufnummern, Gesprächsminuten und weitere Leistungen weisen wir getrennt aus. So kannst du nachvollziehen, welcher Teil deiner Kosten auf die Nummern entfällt und welcher durch die Nutzung entsteht. Falls zusätzliche Leistungen oder Einrichtungskosten anfallen, führen wir diese als eigene Posten auf und besprechen sie vor deinem Start mit dir.
Abrechnung
Rufnummern und Gesprächsminuten werden getrennt erfasst. Beim Durchstellen zählen die eingehende Verbindung und die Verbindung zum Ziel. Die Kosten deiner Voice-Plattform für KI, Spracherkennung und Sprachausgabe werden unabhängig davon abgerechnet.
Verbrauch und Anrufe siehst du im Dashboard unter Tarif & Nutzung und Anrufe, oder per CLI:
trunkbeam usage --month 2026-10
trunkbeam calls ls --limit 20
TrunkBeam richtet sich an Unternehmen (B2B). Rufnummern vergeben wir erst nach Prüfung deiner Firma. Ortsnetznummern setzen einen Sitz oder eine Niederlassung im jeweiligen Ortsnetz voraus.