Eigene Rufnummern einbringen

Dieses Dokument beschreibt, wie Sie Rufnummern mit der Audact-Anrufvalidierungsplattform über zwei verschiedene Wege integrieren: von Audact bereitgestellte Nummern (über Telnyx verwaltet) und Bring-Your-Own-Trunks (BYO-Trunks, verwaltet über Ihren eigenen Telefonieanbieter).

Zwei Nummerntypen

Audact unterstützt zwei grundlegende Wege, um Rufnummern für das eingehende Anruf-Routing bereitzustellen:

Typ 1: Von Audact bereitgestellte Nummern (Telnyx)

Audact verwaltet den gesamten Nummernlebenszyklus über seine Telnyx-Carrier-Beziehung.

Erwerb: Sie fordern Nummern über den KYC-Dokumenteneinreichungs- und Nummernbestellungsablauf an, der in Nummernbereitstellung & KYC dokumentiert ist. Audact verschlüsselt Ihre Compliance-Dokumente, übermittelt sie zur Genehmigung an Telnyx, und nach der Genehmigung können Sie DIDs in jeder vom Dokumentenset abgedeckten Länder-/Typkombination bestellen.

Lebenszyklus: Nummern werden im Pool von Audact gespeichert, Agenten über die Plattform-API zugewiesen und automatisch über das Telnyx-Konto von Audact abgerechnet. Die Plattform konfiguriert die Telnyx-SIP-Trunk-Verbindung in Ihrem Auftrag — Sie müssen keine Verbindungsparameter angeben.

Abbau: Es gibt zwei Operationen:

• Freigabe: Agentenzuweisung aufheben und die Nummer in den Pool zurückgeben (DELETE /v1/numbers/{id}/release). Die DID verbleibt im Besitz von Audact und kann für zukünftige Neuzuweisungen kontaktiert werden.
• Löschen: Die Nummer dauerhaft entfernen und die DID an den Bestand von Telnyx zurückgeben (DELETE /v1/numbers/{id}). Dies ist irreversibel; die Nummer ist weder auf der Plattform noch im Carrier-Pool vorhanden.

Verbindung: Automatisch. Sie verweisen Ihr Telnyx-Konto auf den im Dashboard angezeigten SIP-Ingress-Host (abgerufen über GET /v1/byo/config), und Audact übernimmt den Rest.

Typ 2: Bring-Your-Own-Trunk (BYO-Trunk)

Sie verwalten den Nummernkauf und die Beziehung zum Telefonieanbieter; Audact nimmt eingehende Anrufe an, die über Ihren SIP-Trunk geroutet werden.

Erwerb: Nummern werden direkt bei Ihrem Telefonieanbieter erworben (Twilio, Telnyx oder ein generischer SIP-Anbieter). Sie kontrollieren Abrechnung, Carrier-Beziehung und Nummernpool.

Lebenszyklus: Sie besitzen die Nummern und können sie nach eigenem Ermessen neu zuweisen oder freigeben. Audact stellt diese DIDs nicht bereit, rechnet sie nicht ab und verwaltet sie nicht — es routet nur Anrufe, die auf diesen Nummern eingehen.

Abbau: Sie geben Nummern bei Ihrem Carrier frei. Audact stellt das Routing für diese Nummer einfach ein.

Verbindung: Sie konfigurieren die SIP-Trunk-Origination-URI so, dass sie auf den SIP-Ingress von Audact verweist (im Dashboard angezeigt über GET /v1/byo/config). Audact validiert eingehende Anrufe gegen Ihren Pool konfigurierter BYO-Nummern und routet sie an die entsprechenden Agenten.

Einrichtung Typ 1: Von Audact bereitgestellte Nummern

Den vollständigen Lebenszyklus finden Sie unter Nummernbereitstellung & KYC. Zusammengefasst:

1. KYC-Dokumente hochladen via POST /v1/kyc/documents
2. Dokumentenset erstellen via POST /v1/kyc/document-sets (Telnyx genehmigt asynchron)
3. Nach der Genehmigung eine Nummernbestellung aufgeben via POST /v1/numbers/orders
4. Nummern Agenten zuweisen via POST /v1/numbers/{id}/assign
5. Audact konfiguriert den Telnyx-SIP-Trunk automatisch

Für Nummern des Typs 1 ist keine manuelle SIP-Trunk-Konfiguration erforderlich.

Einrichtung Typ 2: Eigene SIP-Trunks einbringen

Ihr SIP-Trunk initiiert Anrufe zum SIP-Ingress von Audact. Die folgenden Abschnitte dokumentieren drei gängige Anbieter-Setups und eine generische SIP-Vorlage.

SIP-Ingress-Konfiguration abfragen

Bevor Sie einen BYO-Trunk konfigurieren, rufen Sie die SIP-Ingress-Einstellungen Ihres Mandanten ab:

curl -X GET https://api.audact.ai/v1/byo/config \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Antwort:

{
  "sip_ingress_host": "sip.us.audact.ai",
  "sip_ingress_port": 5060,
  "allowed_source_cidrs": ["203.0.113.0/24"],
  "healthy_numbers": ["+14155551234", "+14155551235"],
  "failed_numbers": []
}

Verwenden Sie sip_ingress_host und sip_ingress_port in den folgenden Abschnitten.

Twilio-Trunk verbinden

Twilios SIP-Trunking-Produkt ermöglicht es Ihnen, Anrufe zu einem externen SIP-Server zu initiieren.

1. Twilio-SIP-Trunk erstellen

1. Melden Sie sich in der Twilio-Konsole an → Elastic SIP Trunks
2. Klicken Sie auf +, um einen neuen Trunk zu erstellen
3. Wählen Sie einen Anzeigenamen (z. B. audact-sip-trunk)
4. Klicken Sie auf Erstellen

2. Origination-URI konfigurieren

Klicken Sie in den Trunk-Einstellungen unter Originating SIP Address:

1. Klicken Sie auf +, um eine Origination-URI hinzuzufügen
2. Eingabe: sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (z. B. sip:sip.us.audact.ai:5060)
3. Setzen Sie Priority auf 10 (niedrigere Zahl = höhere Priorität)
4. Setzen Sie Weight auf 100
5. Lassen Sie Enabled aktiviert
6. Klicken Sie auf Hinzufügen

3. Credential-Liste erstellen (falls erforderlich)

Falls Sie SIP-Authentifizierungsdaten an Audact übermitteln müssen:

1. Scrollen Sie im Trunk zu Credential List
2. Klicken Sie auf +, um Credentials hinzuzufügen
3. Geben Sie Ihren Credential-Listen-Namen ein (z. B. audact-credentials)
4. Wählen Sie Credential Type: SIP Credentials
5. Geben Sie Username und Password ein (koordinieren Sie mit dem Audact-Support)
6. Klicken Sie auf Erstellen
7. Weisen Sie die Credential-Liste dem Trunk zu

Hinweis: Die meisten Twilio-Trunks verwenden IP-Authentifizierung (IP-Zulassungsliste) anstelle von Credentials. Überprüfen Sie dies mit Ihrem Setup.

4. Rufnummern-Routing konfigurieren

Für jede Rufnummer, die Sie über diesen Trunk routen möchten:

1. Gehen Sie in der Twilio-Konsole zu Phone Numbers → Active Numbers
2. Wählen Sie die Nummer aus
3. Setzen Sie unter Voice & Fax:
   • Configure With: SIP Trunk
   • SIP Trunk: wählen Sie Ihren neu erstellten audact-sip-trunk
4. Speichern

5. Audact-IPs zulassen (optional)

Falls Ihr Twilio-Trunk IP-Authentifizierung verwendet:

1. Suchen Sie in den Trunk-Einstellungen nach Originating SIP Address
2. Beachten Sie alle IP-Einschränkungen bei der Origination-URI
3. Bitten Sie den Audact-Support um die Liste der ausgehenden SIP-Server-IPs
4. Fügen Sie diese zur IP-Zulassungsliste Ihres Twilio-Trunks hinzu

Telnyx-Trunk verbinden

Das SIP-Trunking-Produkt von Telnyx ähnelt dem von Twilio. Wenn Sie bereits Telnyx-Nummern besitzen, aber BYO-Trunking verwenden möchten (anstatt von Audact bereitgestellte Nummern), folgen Sie dieser Anleitung.

1. Telnyx-SIP-Verbindung erstellen

1. Melden Sie sich im Telnyx-Portal an → Connections → SIP Connections
2. Klicken Sie auf Create SIP Connection
3. Wählen Sie einen Connection Name (z. B. audact-sip-connection)
4. Fügen Sie unter Outbound eine Originating SIP Address hinzu:
   • Eingabe: sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (z. B. sip:sip.us.audact.ai:5060)
5. Klicken Sie auf Erstellen

2. Authentifizierung konfigurieren

Option A: IP-Authentifizierung

1. Suchen Sie in Ihren Telnyx-Verbindungseinstellungen nach IP Authentication
2. Fügen Sie die SIP-Server-IPs von Audact zur Zulassungsliste hinzu
3. Bitten Sie den Audact-Support um die genauen IP-Bereiche

Option B: SIP-Credentials

1. Wählen Sie in Ihren Verbindungseinstellungen unter Authentication die Option Username & Password
2. Geben Sie Ihren Username ein (z. B. Ihre Mandanten-ID oder API-Key-Kennung)
3. Setzen Sie ein Password
4. Klicken Sie auf Speichern
5. Teilen Sie diese Credentials sicher mit Audact

3. Rufnummern zuweisen

Weisen Sie jede BYO-Nummer der SIP-Verbindung zu:

1. Gehen Sie zu Inventory → Phone Numbers
2. Wählen Sie eine Nummer aus
3. Setzen Sie unter Routing:
   • Connection Type: SIP Connection
   • Connection: wählen Sie Ihre audact-sip-connection
4. Geben Sie die Sip Termination-URI ein: sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT}
5. Speichern

4. Abrechnung konfigurieren

Stellen Sie sicher, dass die Abrechnung direkt über Telnyx eingerichtet ist — Audact stellt Ihnen BYO-Nummern nicht in Rechnung. Telnyx fakturiert Ihnen Minuten, Terminierung und Nummernmiete.

Generischen SIP-Trunk verbinden

Wenn Ihr Anbieter weder Twilio noch Telnyx ist, verwenden Sie diese generische SIP-Origination-Vorlage.

Voraussetzungen

• Ihr SIP-Anbieter erlaubt ausgehende Origination zu einem externen SIP-Server
• Sie haben ausgehende SIP-Credentials oder Zugang zur IP-Zulassungsliste
• Ihr Anbieter unterstützt E.164-Rufnummernformatierung in SIP-INVITE-Headern

Konfigurationsschritte

1. Audact als Originating Peer im Portal Ihres Anbieters hinzufügen:

   • Peer Address: ${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (z. B. sip.us.audact.ai:5060)
   • Protocol: SIP (UDP oder TCP, koordinieren Sie mit Audact)
   • Port: 5060 (Standard; bestätigen Sie mit Ihrem Anbieter und Audact)

2. Authentifizierung (eine Option wählen):

   Option A: IP-Authentifizierung

   • Fügen Sie die öffentliche IP Ihres SIP-Servers oder Gateways zur Zulassungsliste von Audact hinzu
   • Bitten Sie den Audact-Support um den SIP-Server-IP-Bereich
   • Fügen Sie die IPs von Audact zur Zulassungsliste Ihres Anbieters hinzu

   Option B: Digest-Authentifizierung (Username & Password)

   • Setzen Sie Username: Ihren API-Key, Ihre Mandanten-ID oder vom Anbieter zugewiesene Credentials
   • Setzen Sie Password: ein sicheres Geheimnis
   • Stellen Sie sicher, dass Ihr Anbieter Credentials im SIP-INVITE oder REGISTER sendet
   • Teilen Sie Credentials mit dem Audact-Support, damit diese validiert werden können

3. Origination-Regeln konfigurieren:

   • Routen Sie für jede Rufnummer eingehenden Traffic an den Audact-Peer
   • Stellen Sie sicher, dass das SIP-INVITE die E.164-formatierte Nummer im To-Header enthält (z. B. To: <sip:+14155551234@sip.us.audact.ai>)

4. Verbindung testen:

   • Überprüfen Sie, ob SIP-Pakete Audact erreichen, indem Sie die Anruflogs Ihres Anbieters überwachen
   • Prüfen Sie im Audact-Dashboard, ob der Anruf eingeht (der Health-Status sollte von unverified zu healthy wechseln)

Trunk-Health-Status

Sobald ein BYO-Trunk konfiguriert ist, verfolgt Audact dessen Health-Status. Verwenden Sie diese Status, um Verbindungsprobleme zu diagnostizieren.

Bedeutung der Health-Status

Trunk-Status prüfen

Verwenden Sie den Endpunkt GET /v1/byo/config, um den Trunk-Health-Status anzuzeigen:

curl -X GET https://api.audact.ai/v1/byo/config \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Die Antwort enthält health_status und last_check_timestamp für jeden Trunk.

Troubleshooting-Workflow

1. DNS-Auflösung prüfen:

   bash

   nslookup ${SIP_INGRESS_HOST}

   Sollte die IP Ihres SIP-Servers auflösen.

2. SIP-Verbindung von Ihrem Server testen:

   bash

   # Using a SIP client or tool (e.g., sipvious, sipp)
   sipp -sf register.xml ${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT}

3. Firewall-Regeln prüfen:

   • Stellen Sie sicher, dass UDP/TCP 5060 zwischen Ihrem Anbieter und Audact offen ist
   • Bestätigen Sie, dass der IP-Bereich von Audact auf Ihrer Seite zugelassen ist (bei IP-Authentifizierung)

4. SIP-Logs überprüfen:

   • Prüfen Sie die SIP-Logs Ihres Anbieters auf INVITE-Ablehnungen oder Timeouts
   • Prüfen Sie die eingehenden SIP-Fehler-Logs von Audact im Dashboard

5. Einen Anruf testen:

   • Führen Sie einen Testanruf von einem beliebigen Telefon zu einer Ihrer BYO-Nummern durch
   • Beobachten Sie den Anruffluss im Audact-Dashboard
   • Prüfen Sie den Health-Status: sollte nach dem ersten erfolgreichen Anruf von unverified zu healthy wechseln

BYO-Trunk-Abrechnung & Verantwortlichkeiten

Nummerntypen mischen

Ein Mandant kann sowohl von Audact bereitgestellte Nummern als auch BYO-Trunks gleichzeitig verwenden. Zum Beispiel:

• Von Audact bereitgestellte Nummern (+1415..., +44204...) bestimmten Agenten zuweisen
• BYO-Nummern (+1212... von Twilio, +61... von Telnyx-als-BYO) an andere Agenten routen
• Audact routet alle eingehenden Anrufe entsprechend der DID

Es ist keine spezielle Konfiguration erforderlich — konfigurieren Sie einfach beide Typen parallel. Der Endpunkt GET /v1/byo/config gibt sowohl von Audact verwaltete als auch BYO-Trunks aus.