SMS API

Mit der Contact Center AI Platform (CCAI Platform) können Sie die SMS API verwenden, um eingehende und ausgehende SMS-Nachrichten zu verarbeiten.

Authentifizierung

Für die Verwendung der SMS API benötigen Sie Anmeldedaten.

So erstellen Sie Anmeldedaten für die SMS API:

  1. Klicken Sie im CCAI Platform-Portal auf Einstellungen > Entwicklereinstellungen > API-Anmeldedatenverwaltung.

  2. Klicken Sie auf die Schaltfläche + API-Anmeldedaten hinzufügen. Die Meldung API-Anmeldedaten hinzufügen wird geöffnet.

  3. Geben Sie einen Namen für die Anmeldedaten ein.

  4. Klicken Sie auf Erstellen.

Ausgehende SMS API

Die ausgehende SMS API bietet einen Endpunkt zum Initiieren ausgehender SMS-Nachrichten. So können Sie programmatisch SMS-Nachrichten an Kunden senden.

Bei der Verwendung dieser API sind drei wichtige Punkte zu beachten:

  • Dieser Dienst ist nicht dafür konzipiert, Zehntausende von Nachrichten gleichzeitig zu senden. Ziel ist die ereignisgesteuerte Nachrichtenübermittlung.

  • Kunden können auf die SMS-Nachricht antworten und eine Supportsitzung starten.

  • Diese API funktioniert nicht, wenn Sie mehrere SMS-Nachrichten am selben Tag an dieselbe Nummer senden müssen.

Anwendungsbereiche

Beispielhafte Anwendungsfälle für die ausgehende SMS API sind ereignisbasiert. Beispielsweise, wenn Sie den Kunden benachrichtigen möchten, dass seine Bestellung zur Abholung bereit ist, UND ihm die Möglichkeit geben möchten, zu antworten. Wenn eine ausgehende SMS gesendet wird, wird eine aktive Sitzung erstellt. Wenn der Kunde antwortet, wird er an einen Kundenservicemitarbeiter weitergeleitet.

Der Unterschied zwischen dieser und der sitzungslosen ausgehenden SMS API besteht darin, dass Sie bei der sitzungslosen API nur die Benachrichtigung senden. Wenn der Kunde antwortet, erhält er eine Standardnachricht (falls konfiguriert) und wird nicht an einen Kundenservicemitarbeiter weitergeleitet.

Weitere mögliche Anwendungsfälle:

  • Anmeldung im Konto
  • Kontoaktivität
  • Wichtige Ereignisse bei der Kontonutzung
  • Erkennung von Problemen mit verbundenen Geräten
  • Benachrichtigungen zur voraussichtlichen Ankunftszeit für On-Demand-Dienste wie Lieferungen und Mitfahrgelegenheiten
  • Terminerinnerungen
  • Proaktive Service- oder Kontowarnungen
  • Bestätigung in zwei Schritten (erfordert, dass der Kunde einen vorhandenen Codegenerator und einen Dienstprozess hat)

Endpunkt der ausgehenden SMS API

Der Basis-URI für diesen neuen Endpunkt ist:

POST https://<subdomain>.<domain>/apps/api/v1/sms

Unterstützung für eingehende SMS

Wenn eine Umgebung eingehende SMS-Antworten unterstützen soll, muss die ausgehende Nummer auch als eingehende SMS-Nummer eingerichtet werden, die einer Warteschlange zugewiesen ist. Jede SMS-Telefonnummer kann nur einer Warteschlange zugewiesen werden. Weitere Informationen finden Sie unter Allgemeine SMS-Chatkonfiguration.

Wenn ein Endnutzer auf eine so konfigurierte SMS antwortet, wird er zum Menü der SMS-Warteschlange weitergeleitet, der die eingehende SMS-Telefonnummer zugewiesen ist. Weitere Informationen finden Sie unter SMS-Chat-Einstellungen – Telefonnummer.

API-Vorgänge

In diesem Abschnitt werden die API-Vorgänge, Textparameter und Antwortcodes beschrieben.

Text und Parameter

Die folgenden Felder sollten im Text der API-Anfrage enthalten sein:

Feldname Typ Erforderlich Beschreibung Werte Hinweise
agent_id Ganzzahl Nein Der Agent, der dieser ID entspricht, wird einem neuen Chat zugewiesen, wenn zwischen den angegebenen Nummern kein Chat vorhanden ist. Wenn der Agent mit einem vorhandenen Chat verbunden ist, wird die Nachricht in seinem Namen gesendet.
agent_email String Nein Die E-Mail-Adresse des Agenten.
chat_type String Ja SMS SMSAP
chat_subtype String Ja api_initiated
end_user_number String Ja Nummer, an die die SMS gesendet werden soll Bestätigung: Gültige Telefonnummer: +18882468888 für eine US-Telefonnummer
outbound_number String Ja Ausgehende Telefonnummer, die zum Senden der SMS verwendet werden soll Bestätigung: a) Die Telefonnummer muss eine SMS-Telefonnummer sein, die mit dem Mandanten verknüpft ist, b) fehlende Telefonnummer, c) Telefonnummer im falschen Format: +18882468888 für eine US-Telefonnummer
message String Ja SMS-Nachricht, die an den Kunden gesendet werden soll Lange Nachrichten: Lange Nachrichten in mehrere Nachrichten aufteilen (sollte in der vorhandenen Funktion für ausgehende SMS enthalten sein) Bestätigung: a) Fehlende Nachricht, b) Nachricht überschreitet die maximale Anzahl von Zeichen (um x)
ticket_id id Nein Sitzung mit einer bestimmten CRM-Ticket-ID verknüpfen Hinweis: Ungültige Ticket-IDs werden ignoriert.

Fehler und Erfolg

Fall Erwartetes Ergebnis Kopieren
SMS-Dienst ist aktiviert
Ausgehender SMS-Dienst ist aktiviert
Der Wert von „chat_type“ ist „OutboundSMSAPI“
„end_user_number“ ist angegeben und korrekt formatiert
„outbound_number“ ist angegeben und korrekt formatiert
Für nicht US-amerikanische Telefonnummern: Nicht US-amerikanische Telefonnummer ist aktiviert
Nachricht ist angegeben
Kein aktiver Chat zwischen „outbound_number“ und „end_user_number“		 Erfolgreich (200) Beispiel für eine erfolgreiche Antwort
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
Agent-ID und E-Mail-Adresse des Agenten sind angegeben Fehler Es kann nur entweder agent_id oder agent_email angegeben werden.
Agent-ID oder E-Mail-Adresse des Agenten ist angegeben
Agent ist nicht mit einem vorhandenen Chat verbunden		 Fehler Ausgehende SMS fehlgeschlagen. Agent ist nicht mit dem Chat verbunden.
SMS-Dienst ist nicht aktiviert Fehler „SMS-Dienst ist nicht aktiviert“.
Ausgehender SMS-Dienst ist nicht aktiviert Fehler „Ausgehender SMS-Dienst ist nicht aktiviert“
„chat_type“ ist nicht angegeben Fehler „chat_type“ muss angegeben werden
„chat_type“ ist angegeben, aber nicht auf „sms“ gesetzt Fehler „Ein gültiger chat_type muss angegeben werden“
„end_user_number“ ist angegeben, aber nicht korrekt formatiert Fehler „end_user_number“ ist ungültig
(Hinweis: Gültige Telefonnummer: „+18882468888“ für eine US-Telefonnummer)
„end_user_number“ ist nicht angegeben Fehler „end_user_number“ ist erforderlich
„outbound_number“ ist angegeben, aber nicht korrekt formatiert Fehler „outbound_number“ ist ungültig
(Hinweis: Gültige Telefonnummer: „+18882468888“ für eine US-Telefonnummer)
„outbound_number“ ist angegeben, aber für diesen Mandanten nicht vorhanden Fehler „outbound_number“ wurde nicht gefunden
„outbound_number“ ist nicht angegeben Fehler „outbound_number“ ist erforderlich
„outbound_number“ ist eine nicht US-amerikanische Telefonnummer und der Dienst für nicht US-amerikanische Telefonnummern ist nicht aktiviert Fehler "Der Dienst für nicht US-amerikanische Telefonnummern ist nicht aktiviert"
Hinweis: Abhängig von der Einstellung Nicht US-amerikanische Telefonnummer unter Einstellungen > SMS im Anruf > Konfigurationen für nicht US-amerikanische Telefonnummern
Nachricht ist leer Fehler „message“ ist erforderlich
Aktiver Chat zwischen „outbound_number“ und „end_user_number“ Fehler „Ausgehende SMS fehlgeschlagen. Der Kunde befindet sich bereits in einer aktiven SMS-Sitzung.“
„ticket_id“ ist ausgefüllt, aber nicht im CRM vorhanden Fehler „Ticket wurde nicht gefunden“

SMS-Ablauf

Ausgehende SMS-Nachrichten sind aktiv, sobald sie gesendet werden.

Jeder SMS-Chat muss beendet werden, bevor eine neue SMS-Chatsitzung zwischen einer bestimmten ausgehenden und einer Kunden-Telefonnummer eingerichtet werden kann. Dazu gehören auch ausgehende SMS-Nachrichten, die mit der API gesendet wurden. Jede ausgehende SMS schlägt fehl, wenn zwischen der ausgehenden und der Kunden-Telefonnummer ein vorhandener, aktiver Chat vorhanden ist.

Optionen für das automatische Chat-Timeout

Optionen für das automatische Chat-Timeout werden unter Einstellungen > Chat > SMS-Ablauf und globales Timeout konfiguriert. Hier können Sie festlegen, wie lange eine Chatsitzung aktiv bleibt, wenn in der Chatsitzung keine Aktivität oder kein Fortschritt erfolgt.

Unterschiede beim Chatstatus

Im Folgenden werden die Unterschiede zwischen den Statusänderungen des Chatprozesses beschrieben:

  • Status „Warteschlange auswählen“ – Chat-AblaufAusgehende Chats, die mit der API gesendet werden, befinden sich im Status „Warteschlange auswählen“, bis der Kunde antwortet

    Jede Chatsitzung, die nicht über den Status „Warteschlange auswählen“ hinausgegangen ist. Dazu gehören gesendete ausgehende SMS-Nachrichten, auf die ein Kunde nicht geantwortet hat. Sie können festlegen, wie lange ein Chat in diesem Status bleiben kann, bevor er abläuft (Nachricht gesendet und Kunde antwortet nicht innerhalb des Timers – Chat läuft ab).

  • Ablauf von unbeantworteten SMS-Chats (während der Geschäftszeiten)Die Zeit, die ein Chat in einer Warteschlange unbeantwortet bleiben kann, bevor er innerhalb der festgelegten Geschäftszeiten für die jeweilige Warteschlange abläuft.

  • Ablauf von unbeantworteten SMS-Chats (außerhalb der Geschäftszeiten)Die Zeit, die ein Chat in einer Warteschlange unbeantwortet bleiben kann, bevor er außerhalb der festgelegten Geschäftszeiten für die jeweilige Warteschlange abläuft.

  • Timeout für ausgehende SMS-Chats Ausgehende SMS-Chatsitzungen laufen automatisch ab, wenn [x] Minuten lang keine Aktivität erfolgt.

Details zum Chatstatus

  • Wenn eine ausgehende SMS mit der API gesendet wird, gilt der Chat als aktiv , aber nicht als verbunden.

  • Diese aktiven ausgehenden SMS-Chats befinden sich im Status Warteschlange auswählen , bis der Kunde antwortet.

  • Chats gelten als verbunden , sobald der Kunde antwortet und ein Agent dem Chat zugewiesen wird.

Auswirkungen des Chatstatus auf angewendete Timer

  • Für aktive Chats, die mit der API gesendet wurden und auf die der Kunde nicht geantwortet hat, gilt der Timer für den Status „Warteschlange auswählen“.

  • Für Chats, die mit einem Agenten verbunden sind, gilt der Ablauf-Timer für ausgehende Nachrichten.

  • Wenn ein Kunde auf die erste Nachricht antwortet, aber nie ein Agent zugewiesen wird, ist der Chat nicht verbunden und unterliegt dem Ablauf-Timer für unbeantwortete Chats, innerhalb oder außerhalb der Geschäftszeiten.

Beispiel für API-Nachrichtenfluss und -Status:

  1. SMS-Nachricht wird mit der API an den Kunden gesendet – der Chat befindet sich im Status Warteschlange auswählen und ist nicht mit einem Agenten verbunden.

  2. Der Ablauf-Timer für den Status „Warteschlange auswählen“ wird gestartet. Der Chat läuft ab und wird beendet, wenn der Kunde nicht innerhalb des Timer-Schwellenwerts antwortet.

  3. Der Kunde antwortet auf den Chat – der Chat ist jetzt mit einem Agenten verbunden.

  4. Der Kunde sendet die letzte Nachricht – der Timeout-Timer für ausgehende SMS-Chats wird gestartet.

  5. Der Schwellenwert des Timeout-Timers für ausgehende SMS-Chats wurde erreicht – der Chat wird beendet.

Kein Timer für das Schließen von Chats – Bei ausgehenden SMS-Sitzungen, die mit der API initiiert wurden, wird der Timer für das Schließen von Chats nicht ausgeführt. Daher tritt kein Ereignis zum Schließen von Chats auf, auch wenn dieser Chat als eingehender Chat eingeht, wenn ein Kunde auf die Nachricht antwortet.

Antwortdefinition

Die API antwortet mit einem einzelnen Aufrufobjekt, wie im Modell unter /calls zu sehen.

Sitzungslose ausgehende SMS API

Die CCAI Platform bietet eine ausgehende SMS API, die ausgehende SMS-Nachrichten ohne verknüpfte Sitzungen unterstützt.

Dieser API-Aufruf initiiert SMS-Nachrichten ohne Sitzung, die während eines vorhandenen Workflows mit der CCAI Platform ausgelöst werden können.

Eine sitzungslose SMS wird bevorzugt, wenn nur eine einmalige Nachricht an Kunden gesendet wird und kein CRM-Ticket geöffnet werden muss.

Mit dieser ausgehenden SMS API können bis zu 500 Nachrichten pro API-Aufruf gesendet werden.

Anwendungsbereiche

Häufige Anwendungsfälle für eine sitzungslose SMS:

  • Einmalpasswort einrichten

  • Bestätigungscode

  • Terminerinnerungen

  • Feedbacklinks

  • Marketing- oder Werbenachrichten

Die sitzungslose ausgehende API und die ausgehende SMS API unterscheiden sich darin, dass bei der ausgehenden SMS API eine aktive Sitzung initiiert wird, wenn ein Kunde antwortet, und er an einen Agenten weitergeleitet werden kann. Obwohl sie ähnliche Anwendungsfälle haben (Lieferbenachrichtigungen, Terminerinnerungen), besteht der Unterschied darin, was passiert, wenn der Kunde antwortet. Bei der sitzungslosen API erhält er möglicherweise eine Standardbenachrichtigung, dass er nicht antworten soll, bei der ausgehenden SMS wird er jedoch an einen Agenten weitergeleitet.

Endpunkt der sitzungslosen ausgehenden SMS API

Der Basis-URI für diesen Endpunkt ist:

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

API-Anmeldedaten hinzufügen

  1. Rufen Sie im CCAI Platform-Portal Einstellungen > Entwicklereinstellungen > API-Anmeldedatenverwaltung auf.

  2. Klicken Sie auf die Schaltfläche + API-Anmeldedaten hinzufügen. Die Meldung API-Anmeldedaten hinzufügen wird geöffnet.

  3. Geben Sie einen Namen für die Anmeldedaten unter Name ein.

  4. Klicken Sie auf Erstellen.

SMS werden gesendet

Wenn Sie eine sitzungslose ausgehende SMS senden möchten, rufen Sie POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms auf und übergeben Sie die folgenden Anfrageparameter:

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
Feldname Typ Erforderlich Beschreibung Hinweise
from_phone String Ja Die Telefonnummer, von der aus die Nachrichten gesendet werden. Muss eine gültige US-amerikanische Telefonnummer sein.
Der API-Aufruf gibt einen Fehler zurück, wenn:
* die Telefonnummer keine SMS-Telefonnummer ist, die mit dem Mandanten verknüpft ist
* das Feld „from_phone“ leer ist
* die Telefonnummer nicht dem richtigen Format entspricht. Beispielsweise ist die folgende Nummer eine gültige US-amerikanische Telefonnummer: +18882468888
to_phones Array [String] Ja Die Telefonnummern, an die die Nachrichten gesendet werden. So stellen Sie sicher, dass der API-Aufruf erfolgreich ist:
* Bestätigen Sie, dass Sie eine gültige Telefonnummer haben, z. B. +18882468888
Die maximale Anzahl von Telefonnummern beträgt 100 pro API-Aufruf.
messages Array [String] Ja Die zu sendenden Nachrichten. Sie können maximal 5 separate Nachrichten senden.
Jede Nachricht hat ein Limit von 320 Zeichen und darf dieses Limit nicht überschreiten.

API-Antworten

Wenn der API-Aufruf erfolgreich ist, sehen Sie Folgendes:

  • code: 200

  • Anfrage-ID

    Achten Sie darauf, dass Sie die Anfrage-ID in Ihren Systemdatensätzen protokollieren. Wenn Sie ein Problem beheben müssen, benötigt der Support die Anfrage-ID, um Ihnen helfen zu können.

Wenn der API-Aufruf fehlschlägt, sehen Sie Folgendes:

  • code: 4xx

  • Fehlermeldung

SMS-Beschränkungen

  • Die API verarbeitet maximal 300 Nachrichten pro Minute.

  • Alle nicht verarbeiteten Nachrichten laufen nach 2 Stunden ab.