Ausgehende Anrufe

Die Funktion für ausgehende Anrufe ermöglicht es Ihrem Bot, Telefonanrufe zu externen Telefonnummern programmatisch zu initiieren. Dies ermöglicht Anwendungsfälle wie Terminerinnerungen, Benachrichtigungen, Umfragen und proaktive Kundenansprache.

Übersicht

Das System für ausgehende Anrufe funktioniert in zwei Hauptschritten:

1. Konfiguration: Richten Sie Ihre Einstellungen für ausgehende Anrufe in der Telefonkanalkonfiguration ein
2. API-Integration: Verwenden Sie die REST-API, um ausgehende Anrufe zu initiieren und zu überwachen

Voraussetzungen

Bevor Sie die Funktion für ausgehende Anrufe verwenden, stellen Sie sicher, dass Sie Folgendes haben:

• Einen Bot mit einem konfigurierten Telefonkanal
• Zugriff auf die Telefonkanalkonfiguration (Rolle des Kanalmanagers erforderlich)
• API-Anmeldedaten mit den entsprechenden Berechtigungen

---

Schritt 1: Einstellungen für ausgehende Anrufe konfigurieren

Navigieren Sie zu den Telefoneinstellungen Ihres Bots und konfigurieren Sie die Parameter für ausgehende Anrufe.

Konfigurationsparameter

1. Ausgehende Anrufe aktivieren

Schalten Sie die Option "Ausgehende Anrufe aktivieren" ein, um die Funktion zu aktivieren.

2. Anzeigename (Optional)

• Beschreibung: Der Name, der dem Anrufempfänger angezeigt wird
• Beispiel: "Unternehmen GmbH", "Kundendienst"
• Hinweis: Dies kann je nach Telefonsystem des Empfängers und der Richtlinie des SIP-Anbieters angezeigt werden oder nicht

3. Anzeigennummer (Erforderlich)

• Beschreibung: Die Telefonnummer, die dem Anrufempfänger angezeigt wird
• Format: Internationales Format empfohlen (z.B. +4912345678)
• Hinweis: Es können Einschränkungen oder Anforderungen bezüglich der Anzeigennummer je nach Richtlinie des SIP-Anbieters bestehen

4. Ausgehende Leitung (Erforderlich)

• Beschreibung: Die SIP-Trunk- oder Leitungskonfiguration für ausgehende Anrufe
• Beispiel: "Outbound_Trunk"
• Hinweis: Dies sollte von Ihrem Telefonadministrator konfiguriert werden

Konfiguration speichern

Nachdem Sie alle erforderlichen Felder konfiguriert haben, klicken Sie auf Speichern, um die Einstellungen für ausgehende Anrufe zu übernehmen.

---

Schritt 2: Einen API-Schlüssel generieren

Um Anfragen für ausgehende Anrufe zu stellen, benötigen Sie einen API-Schlüssel mit den entsprechenden Berechtigungen.

Den API-Schlüssel erstellen

Lesen Sie die API-Schlüssel-Dokumentation für detaillierte Anweisungen zur Erstellung eines API-Schlüssels mit den folgenden erforderlichen Einstellungen:

• Umfang: Lese- und Schreibberechtigungen
• Rollen: Rolle des Kanalmanagers

Wichtig: Kopieren Sie den API-Schlüssel sofort nach der Erstellung, da er nur einmal angezeigt wird.

---

Schritt 3: Einen ausgehenden Anruf initiieren

Verwenden Sie die REST-API, um eine Anfrage für einen ausgehenden Anruf zu erstellen.

API-Endpunkt

POST /bots/{botId}/phone-outbound-calls

Anfrage-Header

x-api-key: {your-api-key}
Content-Type: application/json

Anfragetext

{
    "targetNumber": "+49123456789",
    "timeout": 30,
    "metadata": {
        "campaignId": "summer-2024",
        "customerId": "CUST-12345"
    },
    "sipHeader": {
        "X-Custom-Header": "value"
    }
}

Anfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
targetNumber	string	Ja	Die Telefonnummer, die angerufen werden soll (internationales Format empfohlen)
timeout	number	Nein	Maximale Klingeldauer in Sekunden, bevor der Anruf abgebrochen wird, wenn er nicht beantwortet wird (Standard: 30)
metadata	object	Nein	Benutzerdefinierte Metadaten, die dem Anruf hinzugefügt werden. Die angegebenen Metadaten werden als Wert des Slots sys_phone_session_start_metadata gesetzt
sipHeader	object	Nein	Benutzerdefinierte SIP-Header, die im Anruf enthalten sein sollen. Diese Header werden als Teil der SIP INVITE-Nachricht an den Empfänger übertragen

Antwort

Eine erfolgreiche Anfrage gibt ein Anrufdokument mit der folgenden Struktur zurück:

{
    "_id": "507f1f77bcf86cd799439011",
    "botId": "507f191e810c19729de860ea",
    "tenantId": "507f191e810c19729de860eb",
    "targetNumber": "+49123456789",
    "callId": "1701234567890-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "initialized",
    "timeout": 30,
    "metadata": {
        "campaignId": "summer-2024",
        "customerId": "CUST-12345"
    },
    "sipHeader": {
        "X-Custom-Header": "value"
    },
    "createdAt": "2024-12-05T10:30:00.000Z",
    "updatedAt": "2024-12-05T10:30:00.000Z"
}

Anruf-ID

Das Feld callId ist ein eindeutiger Bezeichner für den Anruf, formatiert als: {timestamp}-{uuid}

Speichern Sie diese callId, um den Anrufstatus später zu überwachen.

Beispielanfrage (cURL)

curl -X POST https://your-instance.com/bots/507f191e810c19729de860ea/phone-outbound-calls \
  -H "x-api-key: 507f1f77bcf86cd799439011.a3b2c1d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "targetNumber": "+49123456789",
    "timeout": 30,
    "metadata": {
      "campaignId": "summer-2024",
      "customerId": "CUST-12345"
    }
  }'

---

Schritt 4: Anrufstatus überwachen

Nachdem Sie einen Anruf initiiert haben, können Sie seinen Status mithilfe der Anruf-ID abfragen.

API-Endpunkt

GET /bots/{botId}/phone-outbound-calls/{callId}

Anfrage-Header

x-api-key: {your-api-key}

Antwort

{
    "_id": "507f1f77bcf86cd799439011",
    "botId": "507f191e810c19729de860ea",
    "tenantId": "507f191e810c19729de860eb",
    "targetNumber": "+49123456789",
    "callId": "1701234567890-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "in_call",
    "statusDetails": "Anruf vom Empfänger beantwortet",
    "timeout": 30,
    "metadata": {
        "campaignId": "summer-2024",
        "customerId": "CUST-12345"
    },
    "sipHeader": {
        "X-Custom-Header": "value"
    },
    "createdAt": "2024-12-05T10:30:00.000Z",
    "updatedAt": "2024-12-05T10:30:45.000Z"
}

Anrufstatuswerte

Das Feld status gibt den aktuellen Zustand des Anrufs an:

Status	Beschreibung
initialized	Der Anruf wurde erstellt und wird für das Wählen vorbereitet
queued	Der Anruf ist in der Warteschlange und wird in Kürze gewählt
dialing	Der Anruf wird gewählt
ringing	Der Anruf klingelt beim Empfänger
in_call	Der Anruf wurde beantwortet und ist derzeit im Gange
completed	Der Anruf wurde erfolgreich abgeschlossen
failed	Der Anruf konnte nicht verbunden werden. Siehe statusDetails für weitere Informationen
no_answer	Der Anruf wurde vom Empfänger nicht beantwortet
rejected	Der Anruf wurde vom Empfänger abgelehnt
busy	Die Leitung des Empfängers ist besetzt

Beispielanfrage (cURL)

curl -X GET https://your-instance.com/bots/507f191e810c19729de860ea/phone-outbound-calls/1701234567890-a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-api-key: 507f1f77bcf86cd799439011.a3b2c1d4-e5f6-7890-abcd-ef1234567890"

---

Metadaten bei Anrufausfall

Wenn der Anruf nicht in_call erreicht (d.h. er endet als failed, no_answer, rejected oder busy), werden vier zusätzliche Felder in das Metadatenobjekt eingefügt, bevor es als sys_phone_session_start_metadata an das Bot-Gespräch übergeben wird. Dies ermöglicht es einem Flow, auf einen fehlgeschlagenen ausgehenden Anruf zu reagieren (z.B. einen Fallback/Retry auszulösen), obwohl kein Gespräch mit dem Empfänger stattgefunden hat.

Dies gilt auch, wenn der Anruf fehlschlägt, bevor das Wählen überhaupt beginnt (z.B. eine ungültige ausgehende Leitung): Die Anfrage POST /phone-outbound-calls selbst gibt eine HTTP 500-Antwort zurück, aber ein Bot-Gespräch wird parallel mit outbound_call_failed in den Metadaten gestartet, sodass ein Flow, der sys_phone_session_start_metadata liest, trotzdem ausgeführt wird, obwohl die API-Anfrage fehlgeschlagen ist.

Feld	Typ	Beschreibung
outbound_call_failed	boolean	Immer true, wenn diese Metadaten vorhanden sind — zeigt an, dass der Anruf nicht verbunden wurde
outbound_call_status	string	Der resultierende Anrufstatus, einer von failed, no_answer, rejected, busy (siehe Anrufstatuswerte)
outbound_call_cause	number oder null	Der vom Telefonsystem gemeldete Roh-SIP/Telephonie-Abbruchursachencode (kann 0 für nicht beantwortete Anrufe sein — 0 ist ein gültiger Ursachencode, nicht "nicht gesetzt"). null nur, wenn der Anruf nie den Punkt des Wählens erreicht hat (z.B. ein Konfigurationsfehler)
outbound_call_error	string oder null	Eine lesbare Fehlermeldung, nur gesetzt, wenn der Anruf vor dem Wählen fehlschlug (z.B. ungültige ausgehende Leitung). null für normale Anruf-Fortschrittsfehler (besetzt/nicht beantwortet/abgelehnt), bei denen outbound_call_cause stattdessen gesetzt ist

---

Fehlerbehandlung

Häufige Fehlerantworten

401 Unauthorisiert

{
    "statusCode": 401,
    "message": "Ungültiger API-Schlüssel"
}

Lösung: Überprüfen Sie, ob Ihr API-Schlüssel korrekt ist und nicht abgelaufen ist.

403 Verboten

{
    "statusCode": 403,
    "message": "Verboten. Erforderliche Rollen: Kanalmanager"
}

Lösung: Stellen Sie sicher, dass Ihr API-Schlüssel die Rolle des Kanalmanagers und den Schreibumfang hat.

404 Nicht gefunden

{
    "statusCode": 404,
    "message": "Anruf nicht gefunden"
}

Lösung: Überprüfen Sie, ob die callId und botId korrekt sind.

500 Interner Serverfehler

{
    "error": "Fehler beim Initiieren des ausgehenden Anrufs für call_id: <call_id>."
}

Dies wird zurückgegeben, wenn der Anruf überhaupt nicht gewählt werden konnte (z.B. eine ungültige oder falsch konfigurierte ausgehende Leitung). Beachten Sie, dass ein Bot-Gespräch unabhängig davon gestartet wird, mit outbound_call_failed in den Metadaten eingefügt — siehe Metadaten bei Anrufausfall — sodass ein Flow trotzdem auf den Fehler reagieren kann, obwohl die API-Antwort selbst eine 500 ist.

Lösung: Überprüfen Sie die konfigurierte ausgehende Leitung und prüfen Sie die Fehlerdetails in den Protokollen.

---

Fehlerbehebung

Anrufe werden nicht initiiert

Mögliche Ursachen:

1. Ausgehende Anrufe sind in der Telefonkanalkonfiguration nicht aktiviert
2. Fehlende oder falsche Konfiguration der ausgehenden Leitung
3. Ungültige Anzeigennummer
4. API-Schlüssel hat nicht die erforderlichen Berechtigungen

Lösungen:

1. Überprüfen Sie, ob alle Konfigurationsfelder ordnungsgemäß eingestellt sind
2. Überprüfen Sie die Protokolle des Telefonsystems auf Verbindungsprobleme
3. Stellen Sie sicher, dass der API-Schlüssel die Rolle des Kanalmanagers und den Schreibumfang hat

Anrufe schlagen sofort fehl

Mögliche Ursachen:

1. Ungültiges Format der Zieltelefonnummer
2. Blockierte Nummer oder Vorwahl
3. Unzureichende Kapazität des Telefonsystems
4. Netzwerkverbindungsprobleme

Lösungen:

1. Überprüfen Sie das Format der Telefonnummer
2. Überprüfen Sie die Liste der blockierten Nummern in den Telefoneinstellungen
3. Kontaktieren Sie Ihren Telefonadministrator
4. Überprüfen Sie die Konnektivität des Telefonservers