openframe API

Die openframe API stellt Endpunkte bereit, die Contact Center as a Service (CCaaS) die Möglichkeit geben, Interaktionsdatensätze ohne Verwendung des Vorgangs-Handlers zu erstellen und zu aktualisieren.

Verwenden Sie diese API, um Interaktionsdatensätze für die Nachverfolgung von Telefonanrufen von Service Desk-Mitarbeitern zu erstellen. Sobald ein Interaktionsdatensatz erstellt wurde, kann die Interaktion automatisch in Konfigurierbarer Arbeitsbereich für CSM angezeigt werden, wenn ein Service Desk-Mitarbeiter einen Anruf erhält.

Für den Zugriff auf diese API muss das Plugin „com.sn_openframe_store“ in der Instanz installiert sein, und der aufrufende Anwender muss entweder über die Rolle „sn_openframe_api_user“ oder „sn_openframe_user“ verfügen. Die openframe -API wird im Namespace sn_openframe ausgeführt.

Weitere Informationen zu CSM-Sprachinteraktionsdatensätzen finden Sie unter CSM voice interaction record page.

openframe – PATCH /openframe/voice-interaction/{interactionSysId}

Aktualisiert den angegebenen Interaktionsdatensatz in der Interaktionstabelle [interaction]. CCaaS-Anbieter (Contact Center as a Service) können diese Datensätze dann zur Nachverfolgung von Telefonanrufen verwenden.

URL-Format

URL mit Versionsnummer: /api/now/openframe/{api_version}/voice-interaction/{interactionSysId}

Standard-URL: /api/now/openframe/voice-interaction/{interactionSysId}

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 1. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
interactionSysId	Sys_id des zu aktualisierenden Interaktionsdatensatzes. Dieser Wert wird vom Endpunkt „Sprachinteraktion erstellen“/POST zurückgegeben. Datentyp: Zeichenfolge Tabelle: Interaktion [interaction]

Tabelle : 2. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 3. Anforderungstextparameter (XML oder JSON)

Name	Beschreibung
Interaktion	Erforderlich. Details der Sprachinteraktion. Mindestens ein Parameter muss übergeben werden. Datentyp: Objekt "interaction": { "additionalParams": {Object}, "callbackPhoneNumber": "String", "clientSessionId": "String", "inboundId": "String", "userPhoneNumber": "String" }
interaction.additionalParameters	Name-Wert-Paare der zugehörigen Interaktionsdatensatzfelder und ihre jeweiligen Werte. Zum Beispiel: "additionalParams": { "direction": "inbound", "short_description": "New outbound call", "assigned_to": "a8f98bb0eb32010045e1a5115206fe3a" } Datentyp: Objekt Standard: Keine
„interaction.callbackPhoneNumber“	Rückruf-Telefonnummer des Anrufers. Dies ist die Nummer, unter der der Service Desk-Mitarbeiter den Anrufer erreicht, falls der Anruf unterbrochen wird. Datentyp: Zeichenfolge Format: E.164 Standard: Keine
„interaction.clientSessionId“	Eindeutiger Bezeichner des Datensatzes in einem externen System, der zur Nachverfolgung dieses Telefonanrufs verwendet wird. Diese Informationen verknüpfen die Datensätze zwischen den beiden Systemen. Datentyp: Zeichenfolge Standard: Keine
„interaction.inboundId“	Eindeutiger Bezeichner des Anwendungsanbieters für den Sprachservice. Tabelle: Feld für eingehende ID in der Tabelle „Anbieterkanalanwendung“ [sys_cs_provider_application]. Standard: Keine
„interaction.userPhoneNumber“	Telefonnummer des Benutzers, der den der Sprachinteraktion zugeordneten Anruf getätigt hat. Datentyp: Zeichenfolge Format: E.164
interactionContext	Festzulegende Interaktionskontextvariablen. Name-Wert-Paare der Interaktionskontextvariablen, die im Interaktionsdatensatz gespeichert werden sollen. Diese Werte werden von CCaaS bestimmt. Zum Beispiel: "interactionContext":{ "devicetype": "genesys", "requester_session_language": "en-US" } Datentyp: Objekt Standard: Keine
phoneLogs	Name-Wert-Paare der Telefonprotokolle, die erstellt und einem Anruf zugeordnet werden sollen. Sie können jedes Feld in der Tabelle „Telefonprotokoll“ [sn_open_frame_phone_log] angeben. Zum Beispiel: "phoneLogs":[ { "agent": "String", "call_id": "String", "start_time": "String" } ] Datentyp: Array von Objekten Standard: Keine
Zugehörige Datensätze	Datensätze im Zusammenhang mit dem Anruf. Datentyp: Array von Objekten "relatedRecords":[ { "documentId": "String", "documentTable": "String" } ] Standard: Keine
ZugehörigeDatensätze.DokumentID	Sys_id des zugehörigen Datensatzes. Datentyp: Zeichenfolge Tabelle: im Parameter relatedRecords.documentTable angegeben.
relatedRecords.documentTable	Name der Tabelle, die den zugehörigen Datensatz enthält. Datentyp: Zeichenfolge

Header

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 4. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json
Content-Type	Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 5. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 6. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Parameter des Antworttexts (JSON oder XML)

Name	Beschreibung
status	Status der Datensatzaktualisierung. Mögliche Werte: ERFOLG: Der Interaktionsdatensatz wurde erfolgreich aktualisiert. FEHLER: Der Interaktionsdatensatz wurde nicht aktualisiert.

cURL-Anforderung

Das folgende Codebeispiel zeigt, wie Sie den Interaktionsdatensatz mit der sys_id 12961fff7fb2d2102d0cd3cf8c86652b aktualisieren.

curl "http://instance.service-now.com/api/now/openframe/voice-interaction/12961fff7fb2d2102d0cd3cf8c86652b" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"interaction\":{
      \"additionalParams\":{
         \"direction\":\"inbound\",
         \"short_description\":\"New Poonam outbound call\",
         \"assigned_to\":\"a8f98bb0eb32010045e1a5115206fe3a\"
      }
   },
   \"interactionContext\":{
      \"devicetype\":\"genesys\",
      \"requester_session_language\":\"en-US\"
   },
   \"phoneLogs\":[
      {
         \"call_id\":\"2323223\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"33535353\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"1997654\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      }
   ],
   \"relatedRecords\":[
      {
         \"documentTable\":\"csm_consumer\",
         \"documentId\":\"59e788fbdb1b1200b6075200cf9619d2\"
      },
      {
         \"documentTable\":\"sys_user\",
         \"documentId\":\"62826bf03710200044e0bfc8bcbe5df1\"
      }
   ]
}" \
--user 'username':'pasword'

Antwort:

{
  "result": {
    "status": "SUCCESS"
  }
}

openframe: POST /openframe/voice-interaction

Erstellt einen Interaktionsdatensatz in der Interaktionstabelle [interaction], wenn ein Service Desk-Mitarbeiter einen Anruf annimmt. CCaaS-Anbieter (Contact Center as a Service) können diese Datensätze dann zur Nachverfolgung von Telefonanrufen verwenden.

Verwenden Sie diesen Endpunkt, um Service Desk-Mitarbeitern eine konsistente Experience zu bieten, ähnlich wie bei anderen nativen Kanälen wie Chat und Fall, wenn Sie Telefonanrufe annehmen.

URL-Format

URL mit Versionsnummer: /api/now/openframe/{api_version}/voice-interaction

Standard-URL: /api/now/openframe/voice-interaction

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 7. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge

Tabelle : 8. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 9. Anforderungstextparameter (XML oder JSON)

Name	Beschreibung
Interaktion	Erforderlich Details der Sprachinteraktion. Mindestens ein Parameter muss übergeben werden. Datentyp: Objekt "interaction": { "additionalParams": {Object}, "callbackPhoneNumber": "String", "clientSessionId": "String", "inboundId": "String", "userPhoneNumber": "String" }
interaction.additionalParameters	Name-Wert-Paare der zugehörigen Interaktionsdatensatzfelder und ihre jeweiligen Werte. Zum Beispiel: "additionalParams": { "direction": "inbound", "short_description": "New outbound call", "assigned_to": "a8f98bb0eb32010045e1a5115206fe3a" } Datentyp: Objekt Standard: Keine
„interaction.callbackPhoneNumber“	Rückruf-Telefonnummer des Anrufers. Dies ist die Nummer, unter der der Service Desk-Mitarbeiter den Anrufer erreicht, falls der Anruf unterbrochen wird. Datentyp: Zeichenfolge Format: E.164 Standard: Keine
„interaction.clientSessionId“	Eindeutiger Bezeichner des Datensatzes in einem externen System, der zur Nachverfolgung dieses Telefonanrufs verwendet wird. Diese Informationen verknüpfen die Datensätze zwischen den beiden Systemen. Datentyp: Zeichenfolge Standard: Keine
„interaction.inboundId“	Eindeutiger Bezeichner des Anwendungsanbieters für den Sprachservice. Tabelle: Feld für eingehende ID in der Tabelle „Anbieterkanalanwendung“ [sys_cs_provider_application]. Standard: Keine
„interaction.userPhoneNumber“	Erforderlich. Telefonnummer des Benutzers, der den der Sprachinteraktion zugeordneten Anruf getätigt hat. Datentyp: Zeichenfolge Format: E.164
interactionContext	Festzulegende Interaktionskontextvariablen. Name-Wert-Paare der Interaktionskontextvariablen, die im Interaktionsdatensatz gespeichert werden sollen. Diese Werte werden von CCaaS bestimmt. Zum Beispiel: "interactionContext":{ "devicetype": "genesys", "requester_session_language": "en-US" } Datentyp: Objekt Standard: Keine
phoneLogs	Name-Wert-Paare der Telefonprotokolle, die erstellt und einem Anruf zugeordnet werden sollen. Sie können jedes Feld in der Tabelle „Telefonprotokoll“ [sn_open_frame_phone_log] angeben. Zum Beispiel: "phoneLogs":[ { "agent": "String", "call_id": "String", "start_time": "String" } ] Datentyp: Array von Objekten Standard: Keine
Zugehörige Datensätze	Datensätze im Zusammenhang mit dem Anruf. Datentyp: Array von Objekten "relatedRecords":[ { "documentId": "String", "documentTable": "String" } ] Standard: Keine
ZugehörigeDatensätze.DokumentID	Sys_id des zugehörigen Datensatzes. Datentyp: Zeichenfolge Tabelle: im Parameter relatedRecords.documentTable angegeben.
relatedRecords.documentTable	Name der Tabelle, die den zugehörigen Datensatz enthält. Datentyp: Zeichenfolge

Header

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 10. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json
Content-Type	Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 11. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 12. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Parameter des Antworttexts (JSON oder XML)

Name	Beschreibung
Nummer	Wird nur bei Erfolg zurückgegeben. Interaktionsnummer der neu erstellten Sprachinteraktion. Datentyp: Zeichenfolge
status	Status der Datensatzerstellung. Mögliche Werte: ERFOLG: Der Interaktionsdatensatz wurde erfolgreich erstellt. FEHLER: Der Interaktionsdatensatz wurde nicht erstellt.
sysId	Wird nur bei Erfolg zurückgegeben. Sys_id des neu erstellten Sprachinteraktionsdatensatzes. Tabelle: Interaktion [interaction]

cURL-Anforderung

Das folgende Codebeispiel zeigt, wie Sie einen neuen Interaktionsdatensatz erstellen.

curl "http://instance.service-now.com/api/now/openframe/voice-interaction" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"interaction\":{
      \"userPhoneNumber\":\"[phone]\",
      \"clientSessionId\":\"a545t65678\",
      \"callbackPhoneNumber\":\"[phone]\",
      \"additionalParams\":{
         \"direction\":\"inbound\",
         \"short_description\":\"New outbound call\",
         \"assigned_to\":\"a8f98bb0eb32010045e1a5115206fe3a\"
      }
   },
   \"interactionContext\":{
      \"devicetype\":\"genesys\",
      \"requester_session_language\":\"en-US\"
   },
   \"phoneLogs\":[
      {
         \"call_id\":\"2323223\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"33535353\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"1997654\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      }
   ],
   \"relatedRecords\":[
      {
         \"documentTable\":\"csm_consumer\",
         \"documentId\":\"59e788fbdb1b1200b6075200cf9619d2\"
      },
      {
         \"documentTable\":\"sys_user\",
         \"documentId\":\"62826bf03710200044e0bfc8bcbe5df1\"
      }
   ]
}" \
--user 'username':'password'

Antwort:

{
  "result": {
    "status": "SUCCESS",
    "sysId": "12961fff7fb2d2102d0cd3cf8c86652b",
    "number": "IMS0000052"
  }
}