Openframe-API

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

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

Um auf diese API zuzugreifen, muss das Plugin com.sn_openframe_Store auf der Instanz installiert sein, und der aufrufende Anwender muss entweder über die Rolle sn_openframe_api_user oder sn_openframe_user verfügen. Die Offener Frame API wird in ausgeführt sn_openframe Namespace.

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 Tabelle „Interaktion“ [Interaktion]. CCaaS-Anbieter (Contact Center as a Service) können diese Datensätze dann verwenden, um Telefonanrufe nachzuverfolgen.

URL-Format

Versionierte URL: /api/now/openframe/{api_Version}/Voice-Interaction/{interactionSysId}

Standard-URL: /api/now/openframe/Voice-Interaction/{interactionSysId}

Hinweis:

Verfügbare Versionen werden in angegeben REST API-Explorer . Für geskriptete REST-APIs gibt es zusätzliche Versionsinformationen auf der Formular „geskripteter REST-Service“ .

Unterstützte Anforderungsparameter

Tabelle : 1. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. 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 von zurückgegeben Sprachinteraktion/POST erstellen Endpunkt. Datentyp: Zeichenfolge Tabelle: Interaktion [Interaktion]

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" }
Interaktion.zusätzliche Parameter	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ückruftelefonnummer des Anrufers. Dies ist die Nummer, die der Service Desk-Mitarbeiter verwendet, um den Anrufer zu erreichen, falls der Anruf abbricht. Datentyp: Zeichenfolge Format: E.164 Standard: Keine
Interaction.clientSessionId	Eindeutiger Bezeichner des Datensatzes in einem externen System, das zum Nachverfolgen 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 „eingehende ID“ in der Tabelle „Anbieterkanalanwendung“ [sys_cs_Provider_Application]. Standard: Keine
interaction.userPhoneNumber	Telefonnummer des Anwenders, der den Anruf getätigt hat, der der Sprachinteraktion zugeordnet ist. 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
Telefonprotokolle	Name-Wert-Paare der Telefonprotokolle, die einem Anruf erstellt und zugeordnet werden sollen. Sie können ein beliebiges 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
Verknüpfte Datensätze	Datensätze im Zusammenhang mit dem Anruf. Datentyp: Array von Objekten "relatedRecords":[ { "documentId": "String", "documentTable": "String" } ] Standard: Keine
RelatedDatensätze.DokumentId	SYS_ID des zugehörigen Datensatzes. Datentyp: Zeichenfolge Tabelle: Angegeben in relatedRecords.documentTableParameter.
RelatedDatensätze.Dokumenttabelle	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
Inhaltstyp	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 REST API-HTTP-Antwortcodes .

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.

Antworttext-Parameter (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 der Interaktionsdatensatz mit der sys_ID 12961fff7fb2d2102d0cd3cf8c86652b aktualisiert wird.

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: NACH /openframe/Voice-Interaction

Erstellt einen Interaktionsdatensatz in der Tabelle „Interaktion“ [Interaktion], wenn ein Service Desk-Mitarbeiter einen Anruf akzeptiert. CCaaS-Anbieter (Contact Center as a Service) können diese Datensätze dann verwenden, um Telefonanrufe nachzuverfolgen.

Verwenden Sie diesen Endpunkt, um Service Desk-Mitarbeitern bei der Annahme von Telefonanrufen eine konsistente Experience zu bieten, ähnlich wie andere native Kanäle wie Chat und Fall.

URL-Format

Versionierte URL: /api/now/openframe/{api_Version}/Voice-Interaction

Standard-URL: /api/now/openframe/Voice-Interaction

Hinweis:

Verfügbare Versionen werden in angegeben REST API-Explorer . Für geskriptete REST-APIs gibt es zusätzliche Versionsinformationen auf der Formular „geskripteter REST-Service“ .

Unterstützte Anforderungsparameter

Tabelle : 7. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. 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" }
Interaktion.zusätzliche Parameter	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ückruftelefonnummer des Anrufers. Dies ist die Nummer, die der Service Desk-Mitarbeiter verwendet, um den Anrufer zu erreichen, falls der Anruf abbricht. Datentyp: Zeichenfolge Format: E.164 Standard: Keine
Interaction.clientSessionId	Eindeutiger Bezeichner des Datensatzes in einem externen System, das zum Nachverfolgen 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 „eingehende ID“ in der Tabelle „Anbieterkanalanwendung“ [sys_cs_Provider_Application]. Standard: Keine
interaction.userPhoneNumber	Erforderlich. Telefonnummer des Anwenders, der den Anruf getätigt hat, der der Sprachinteraktion zugeordnet ist. 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
Telefonprotokolle	Name-Wert-Paare der Telefonprotokolle, die einem Anruf erstellt und zugeordnet werden sollen. Sie können ein beliebiges 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
Verknüpfte Datensätze	Datensätze im Zusammenhang mit dem Anruf. Datentyp: Array von Objekten "relatedRecords":[ { "documentId": "String", "documentTable": "String" } ] Standard: Keine
RelatedDatensätze.DokumentId	SYS_ID des zugehörigen Datensatzes. Datentyp: Zeichenfolge Tabelle: Angegeben in relatedRecords.documentTableParameter.
RelatedDatensätze.Dokumenttabelle	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
Inhaltstyp	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 REST API-HTTP-Antwortcodes .

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.

Antworttext-Parameter (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 [Interaktion]

cURL-Anforderung

Das folgende Codebeispiel zeigt, wie ein neuer Interaktionsdatensatz erstellt wird.

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"
  }
}