Telefonie

curl -X POST "https://app.talkturo.com/api/assistants/asst_7f3c2d91-5d8b-4f3e-a1a9-62fb3ec82d10/telephony/test-call" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=authenticated_session" \
  -d '{
    "accountSlug": "acme-support",
    "fromNumber": "+14155550120",
    "toNumber": "+14155550199"
  }'

const response = await fetch(
  "https://app.talkturo.com/api/assistants/asst_7f3c2d91-5d8b-4f3e-a1a9-62fb3ec82d10/telephony/test-call",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    credentials: "include",
    body: JSON.stringify({
      accountSlug: "acme-support",
      fromNumber: "+14155550120",
      toNumber: "+14155550199",
    }),
  }
);

const data = await response.json();
console.log(data);

{
  "success": true,
  "roomName": "call_asst_7f3c2d91_20250115_184455",
  "sipCallId": "sip_2fd91c8b7a8e4d51",
  "message": "Test call started successfully"
}

{
  "error": "Insufficient credits"
}

Telefonie-Endpunkte

Verwalten Sie die Anrufkonfiguration eines Assistenten, zugewiesene Telefonnummern, ausgehende Testanrufe und Compliance-Vorlagen. Alle Telefonie-Routen sind auf einen einzelnen Assistenten beschränkt und erfordern eine authentifizierte Browser-Sitzung.

Basis-Pfad: /api/assistants/[assistantId]/telephony

Endpunktübersicht

Testanruf starten

POST /telephony/test-call startet einen ausgehenden SIP-Testanruf für einen Assistenten. Vor dem Start prüft der Endpunkt Guthaben, die Outbound-Konfiguration und ob die Ausgangsnummer aktiv und dem Assistenten zugewiesen ist.

Request-Body

Antwortfelder

Validierungsregeln vor dem Start

Der Endpunkt lehnt die Anfrage ab, wenn eine der erforderlichen Telefonie-Voraussetzungen fehlt. Diese Prüfungen laufen vor dem eigentlichen SIP-Aufbau.

• Das Konto muss genügend Guthaben für ausgehende Anrufe haben. Bei unzureichendem Guthaben gibt der Endpunkt 402 zurück.
• Für den Assistenten muss outbound_enabled aktiviert sein.
• Der Assistent muss eine gültige livekit_outbound_trunk_id haben.
• fromNumber muss aktiv und diesem Assistenten zugewiesen sein.
• Die aktuelle Browser-Sitzung muss Zugriff auf das angegebene Konto haben.

Ausführungsablauf

Nach einer erfolgreichen Vorabprüfung führt der Testanruf-Endpunkt drei Schritte in fester Reihenfolge aus:

Wenn alle drei Schritte erfolgreich sind, enthält die Antwort roomName und sipCallId. Daran erkennen Sie, dass der Assistent bereitgestellt und der ausgehende Anruf initiiert wurde.

POST inbound

POST /telephony/inbound schaltet eingehende Anrufe für einen Assistenten ein oder aus. Bei Aktivierung wird ein LiveKit Inbound-SIP-Trunk und eine Dispatch-Regel bereitgestellt. Bei Deaktivierung werden diese entfernt.

Pfadparameter

Body-Parameter

Antwortfelder

POST outbound

POST /telephony/outbound schaltet ausgehende Anrufe für einen Assistenten ein oder aus. Bei Aktivierung wird ein LiveKit Outbound-SIP-Trunk bereitgestellt. Bei Deaktivierung wird dieser entfernt.

Pfadparameter

Body-Parameter

Antwortfelder

POST settings

POST /telephony/settings ist der Hauptendpunkt für Telefonie-Einstellungen. Er weist Telefonnummern zu, setzt die Telnyx-FQDN-Verbindung, aktiviert oder deaktiviert ein- und ausgehende Anrufe, stellt LiveKit-SIP-Trunks bereit und konfiguriert optional Anrufbeantworter-Erkennung und Compliance-Briefing.

Pfadparameter

Body-Parameter

Antwortfelder

GET und PATCH phone-numbers

GET /telephony/phone-numbers listet dem Assistenten verfügbare Telefonnummern auf. PATCH /telephony/phone-numbers ersetzt die Telefonnummer-Zuweisungen des Assistenten. Die GET-Methode gibt Nummern zurück, die aktiv und entweder nicht zugewiesen oder bereits diesem Assistenten zugewiesen sind.

Pfadparameter

GET-Abfrageparameter

PATCH-Body-Parameter

GET-Antwortfelder

PATCH-Antwortfelder

Telefonnummern zuweisen

POST /telephony/assign-phone-numbers weist einem Assistenten Telefonnummern zu. Verwenden Sie diesen Endpunkt, nachdem die Nummern bereits vorhanden oder beschafft wurden.

Wann Sie diesen Endpunkt verwenden sollten

Dieser Endpunkt trennt die Zuweisung bewusst von der allgemeinen Nummernverwaltung. Dadurch können Sie Nummern zunächst abrufen oder vorbereiten und sie erst danach gezielt einem Assistenten zuordnen.

Prüfen Sie nach einer erfolgreichen Zuweisung die Nummernliste des Assistenten erneut. Die aktualisierte Liste zeigt, ob die gewünschten Nummern jetzt mit dem Assistenten verknüpft sind.

Compliance-Vorlagen auflisten

GET /telephony/compliance-templates listet die verfügbaren Compliance-Vorlagen für den Assistenten auf. Diese Vorlagen unterstützen telefoniespezifische Freigabe- und Registrierungsabläufe.

Warum Compliance-Vorlagen wichtig sind

Einige Carrier- oder Regionenanforderungen verlangen zusätzliche Registrierungsdaten, bevor Nummern vollständig nutzbar sind. Mit den verfügbaren Vorlagen können Sie diese Anforderungen konsistent erfassen und im richtigen Format weiterverarbeiten.

Wenn Ihre Telefonie-Einrichtung von regulatorischen Anforderungen abhängt, rufen Sie die verfügbaren Vorlagen ab, bevor Sie Nummern kaufen oder aktivieren.

Gemeinsame Integrationshinweise

Alle Telefonie-Endpunkte in diesem Abschnitt sind einem einzelnen Assistenten untergeordnet. Sie arbeiten immer unter dem Pfad /api/assistants/[assistantId]/telephony.

Kontoebene Telefonie-Endpunkte

Diese Endpunkte verwalten die Telefonie-Anbieterkonfiguration auf Kontoebene. Im Gegensatz zu den übrigen Routen auf dieser Seite sind sie nicht auf einen einzelnen Assistenten beschränkt.

Endpunktübersicht

Telefonie-Konto

GET, POST und PATCH /api/telephony/account lesen, erstellen oder aktualisieren die Telefonie-Anbieterkonfiguration eines Kontos. Alle drei Methoden erfordern eine authentifizierte Session-Cookie-Anfrage.

Body-Parameter

Antwortfelder

Telefonie-Regionen

GET /api/telephony/regions listet verfügbare Telefonie-Regionen und Anbieter auf. Dieser Endpunkt ist öffentlich und erfordert keine Authentifizierung.

Abfrageparameter

Antwortfelder

Telefonie-Regulatorik

GET und POST /api/telephony/regulatory rufen regulatorische Anforderungen ab oder übermitteln die erforderlichen Compliance-Daten für eine Telefoniekonfiguration. Beide Methoden erfordern eine Session-Cookie-Authentifizierung.

GET-Abfrageparameter

POST-Body-Parameter

Antwortfelder

Verwandter Telefonie-Kontext

Die Endpunkte auf dieser Seite decken die assistentenspezifische Telefoniekonfiguration ab. Verwandte Funktionen liegen in benachbarten API-Bereichen, insbesondere bei Telefonnummern und kontoweiten Zuordnungen.