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

Zur 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.

Outbound SMS API

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

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

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

  • Nutzer können auf die SMS antworten und eine Support-Sitzung starten.

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

Anwendungsbereiche

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

Der Unterschied zur API Sessionless Outbound SMS 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 im Zusammenhang mit der Kontonutzung.
  • Erkennung von Problemen mit verbundenen Geräten.
  • Benachrichtigungen zur voraussichtlichen Ankunftszeit für On-Demand-Dienste wie Lieferungen und Fahrdienste.
  • Terminerinnerungen.
  • Proaktive Service- oder Kontobenachrichtigungen.
  • 2‑Faktor-Authentifizierung (erfordert, dass der Kunde einen vorhandenen Codegenerator und Serviceprozess hat).

API-Endpunkt für ausgehende SMS

Die Basis-URI für diesen neuen Endpunkt lautet:

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

Support für eingehende SMS

Wenn in einer Umgebung eingehende SMS-Antworten unterstützt werden sollen, 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 SMS-Warteschlangenmenü weitergeleitet, dem die Telefonnummer für eingehende SMS zugewiesen ist. Weitere Informationen finden Sie unter Chat-Einstellungen für SMS-Nachrichten – Telefonnummer.

API-Vorgänge

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

Body und Parameter

Die folgenden Felder sollten im Body 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 KI-Agent mit einem bestehenden Chat verbunden ist, wird die Nachricht in seinem Namen gesendet.
agent_email String Nein Die E-Mail-Adresse des Kundenservicemitarbeiters.
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 Validierung: Gültige Telefonnummer: +18882468888 für eine US-Telefonnummer
outbound_number String Ja Ausgehende Telefonnummer, die zum Senden der SMS-Nachricht verwendet werden soll Validierung: a) Die Telefonnummer muss eine SMS-Telefonnummer sein, die mit dem Mandanten verknüpft ist, b) Telefonnummer fehlt, c) Telefonnummer hat das falsche Format: +18882468888 für eine US-Telefonnummer
Nachricht String Ja SMS, die an den Nutzer gesendet werden soll Lange Nachrichten: Lange Nachrichten in mehrere Nachrichten aufteilen (sollte durch die vorhandene Funktion für ausgehende SMS abgedeckt werden) Validierung: a) Nachricht fehlt, b) Nachricht überschreitet die maximale Anzahl von Zeichen (um x)
ticket_id id Nein Ordnet die Sitzung einer bestimmten CRM-Ticket-ID zu Hinweis: Ungültige Ticket-IDs werden ignoriert.

Fehler und Erfolg

Fall Erwartetes Ergebnis Kopieren
SMS-Dienst ist aktiviert
Ausgehender SMS-Dienst ist aktiviert
chat_type-Wert ist „OutboundSMSAPI“
end_user_number wird angegeben und ist wohlgeformt
outbound_number wird angegeben und ist wohlgeformt
Für Telefonnummern außerhalb der USA: Telefonnummer außerhalb der USA ist aktiviert
Nachricht wird angegeben
Kein aktiver Chat zwischen outbound_number und end_user_number		 Erfolgreich (200) Beispiel für Erfolgsantwort
{ 
  "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 Agent-E-Mail-Adresse werden angegeben Fehler Es kann nur agent_id oder agent_email angegeben werden.
Agent-ID oder ‑E-Mail-Adresse angegeben
Agent ist nicht mit dem vorhandenen Chat verbunden		 Fehler Ausgehende SMS fehlgeschlagen. Der Kundenservicemitarbeiter ist nicht mit dem Chat verbunden.
SMS-Dienst ist nicht aktiviert Fehler „SMS-Dienst ist nicht aktiviert“
Der Dienst für ausgehende SMS ist nicht aktiviert Fehler „Der Dienst für ausgehende SMS ist nicht aktiviert“
chat_type wurde nicht angegeben Fehler „chat_type muss angegeben werden“
chat_type wurde angegeben, ist aber nicht auf „sms“ festgelegt Fehler „Es muss ein gültiger chat_type angegeben werden“
end_user_number wurde angegeben, ist aber nicht wohlgeformt Fehler „end_user_number is invalid“
(Hinweis: Gültige Telefonnummer: „+18882468888“ für eine US-Telefonnummer)
end_user_number nicht angegeben Fehler „end_user_number is required“ (end_user_number ist erforderlich)
outbound_number wurde angegeben, ist aber nicht wohlgeformt Fehler „outbound_number is invalid“
(Hinweis: Gültige Telefonnummer: „+18882468888“ für eine US-Telefonnummer)
outbound_number wurde angegeben, ist aber für diesen Mandanten nicht vorhanden Fehler „outbound_number is not found“
outbound_number nicht angegeben Fehler „outbound_number is required“ (outbound_number ist erforderlich)
outbound_number ist keine US-Telefonnummer und der Dienst „non US phone number service“ ist nicht aktiviert Fehler „Non US phone number service is not enabled“ (Dienst für Telefonnummern außerhalb der USA ist nicht aktiviert) 
Hinweis:Hängt von der Einstellung Non-US phone number (Telefonnummer außerhalb der USA) unter Einstellungen > SMS während des Anrufs > Konfigurationen für Telefonnummern außerhalb der USA ab.
Nachricht ist leer Fehler „Nachricht ist erforderlich“
Aktiver Chat zwischen outbound_number und end_user_number Fehler „Ausgehende SMS fehlgeschlagen. Der Nutzer befindet sich bereits in einer aktiven SMS-Sitzung.“
ticket_id ist ausgefüllt, aber nicht im CRM vorhanden Fehler „Ticket wurde nicht gefunden“

Ablauf von SMS

Ausgehende SMS sind aktiv, sobald sie gesendet werden.

Ein SMS-Chat muss beendet werden, bevor eine neue SMS-Chat-Sitzung zwischen einer bestimmten Absender- und Verbrauchertelefonnummer gestartet werden kann. Dazu gehören auch ausgehende SMS-Nachrichten, die über die API gesendet werden. Alle ausgehenden SMS schlagen fehl, wenn ein aktiver Chat zwischen der Absender- und der Telefonnummer des Kunden vorhanden ist.

Optionen für das automatische Chat-Timeout

Optionen für das automatische Chat-Zeitlimit werden unter Einstellungen > Chat > SMS-Ablauf und globales Zeitlimit konfiguriert. Hier können Sie festlegen, wie lange eine Chatsitzung aktiv bleibt, wenn es keine Aktivität oder keinen Fortschritt im Chat-Ablauf gibt.

Unterscheidung des Chatstatus

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

  • Status „Warteschlangenauswahl“ für ChatablaufAusgehende Chats, die über die API gesendet werden, befinden sich im Status „Warteschlangenauswahl“, bis der Kunde antwortet.

    Alle Chatsitzungen, die nicht über die Auswahl der Warteschlange hinausgegangen sind. Dazu gehören gesendete SMS, auf die ein Kunde nicht geantwortet hat. Sie können festlegen, wie lange ein Chat in diesem Status verbleiben kann, bevor er abläuft (Nachricht gesendet – der Kunde antwortet nicht innerhalb des Timers – der Chat läuft ab).

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

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

  • Zeitüberschreitung bei SMS-Chats: SMS-Chats laufen automatisch ab, wenn [x] Minuten lang keine Aktivität erfolgt.

Details zum Chatstatus

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

  • Diese aktiven ausgehenden SMS-Chats befinden sich im Warteschlangenauswahlstatus, bis der Kunde antwortet.

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

Auswirkungen des Chatstatus auf angewendete Timer

  • Für aktive Chats, die über die API gesendet wurden und auf die der Kunde noch nicht geantwortet hat, gilt der Zeitgeber für den Status „Warteschlange wird ausgewählt“.

  • Für Chats, die mit einem Kundenservicemitarbeiter verbunden sind, gilt der Timer für ausgehende Anrufe.

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

Beispiel für API-Nachrichtenfluss und ‑Status:

  1. Die SMS-Nachricht wird über die API an den Verbraucher gesendet. Der Chat befindet sich im Auswahlstatus in der Warteschlange und ist nicht mit einem Kundenservicemitarbeiter verbunden.

  2. Der Ablauf-Timer für den Chat beginnt, sobald die Warteschlange ausgewählt wurde. Der Chat wird beendet, wenn der Kunde nicht innerhalb des Zeitlimits antwortet.

  3. Nutzer antwortet auf den Chat – der Chat ist jetzt mit einem Kundenservicemitarbeiter verbunden.

  4. Der Verbraucher sendet die letzte Nachricht – der Timer für das Zeitlimit für ausgehende SMS-Chats wird gestartet.

  5. Das Zeitlimit für ausgehende SMS-Chats wurde erreicht. Der Chat wurde beendet.

Kein Timer zum Schließen des Chats: Bei ausgehenden SMS-Sitzungen, die über die API initiiert werden, wird der Timer zum Schließen des Chats nicht verwendet. Ein Ereignis zum Schließen des Chats tritt also auch dann nicht ein, wenn der Chat als eingehender Chat eingeht, wenn ein Kunde auf die Nachricht antwortet.

Antwortdefinition

Die API antwortet mit einem einzelnen Call-Objekt, wie im Modell unter /calls zu sehen ist.

Sessionless Outbound SMS API

Die CCAI-Plattform bietet eine API für ausgehende SMS, die ausgehende SMS-Nachrichten ohne verknüpfte Sitzungen unterstützen kann.

Mit diesem API-Aufruf werden SMS-Nachrichten ohne Sitzungsverknüpfung initiiert, die während eines bestehenden Workflows mit der CCAI Platform ausgelöst werden können.

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

Mit dieser API für ausgehende SMS können bis zu 500 Nachrichten pro API-Aufruf gesendet werden.

Anwendungsbereiche

Gängige Anwendungsfälle für sitzungslose SMS:

  • Einmalpasswort einrichten

  • Bestätigungscode

  • Terminerinnerungen.

  • Feedback links.

  • Marketing- oder Werbebotschaften

Die sitzungslose Outbound API und die Outbound SMS API unterscheiden sich darin, dass bei der Outbound SMS API beim Antworten eines Kunden eine aktive Sitzung gestartet wird und der Kunde an einen Kundenservicemitarbeiter weitergeleitet werden kann. Sie haben ähnliche Anwendungsfälle (Versandbenachrichtigungen, Terminerinnerungen), aber der Unterschied liegt darin, was passiert, wenn der Kunde antwortet. Sie erhalten möglicherweise eine Standardbenachrichtigung, dass sie nicht antworten sollen, wenn sie keine Sitzung haben. Bei ausgehenden SMS werden sie jedoch an einen Kundenservicemitarbeiter weitergeleitet.

Sitzungsloser API-Endpunkt für ausgehende SMS

Der Basis-URI für diesen Endpunkt lautet:

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 unter Name einen Namen für die Anmeldedaten ein.

  4. Klicken Sie auf Erstellen.

SMS senden

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 die Nachrichten gesendet werden. Muss eine gültige US-Nummer 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. Die folgende Nummer ist beispielsweise eine gültige US-Telefonnummer: +18882468888
to_phones Array [String] Ja Die Telefonnummern, an die die Nachrichten gesendet werden. Damit der API-Aufruf erfolgreich ist, müssen Sie Folgendes beachten:
* Sie benötigen eine gültige Telefonnummer, z. B. +18882468888
Die maximale Anzahl von Telefonnummern beträgt 100 pro API-Aufruf.
Nachrichten Array [String] Ja Die zu sendenden Nachrichten. Sie können maximal fünf separate Nachrichten senden.
Jede Nachricht darf maximal 320 Zeichen lang sein.

API-Antworten

Wenn der API-Aufruf erfolgreich ist, wird Folgendes angezeigt:

  • code: 200

  • Anfrage-ID

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

Wenn der API-Aufruf fehlschlägt, wird Folgendes angezeigt:

  • Code: 4xx

  • Fehlermeldung

SMS-Einschränkungen

  • Die API verarbeitet maximal 300 Nachrichten pro Minute.

  • Alle nicht verarbeiteten Nachrichten laufen nach 2 Stunden ab.