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 Einstellungen des Telefonkanals 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.

Erstellen des API-Schlüssels

Beziehen Sie sich auf 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

Anforderungsheader

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

Anforderungstext

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

Anforderungsparameter

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}

Anforderungsheader

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": "Call answered by recipient",
  "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. Weitere Informationen finden Sie in statusDetails
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"

---

Fehlerbehandlung

Häufige Fehlerantworten

401 Unauthorisiert

{
  "statusCode": 401,
  "message": "Invalid API Key"
}

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

403 Verboten

{
  "statusCode": 403,
  "message": "Forbidden. Required roles: channel-manager"
}

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

404 Nicht gefunden

{
  "statusCode": 404,
  "message": "Call not found"
}

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

---

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 Einstellungen des Telefonkanals
3. Kontaktieren Sie Ihren Telefonadministrator
4. Überprüfen Sie die Konnektivität des Telefonservers