API für Sprachinteraktionsressourcen

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 15 Minuten Lesedauer

    • Mit der Sprachinteraktions -API können Sie Sprachinteraktionen zwischen Service Desk-Mitarbeitern und Anrufern während eines Telefongesprächs transkribieren und speichern. Es funktioniert in Verbindung mit Virtual Agent - und Service Desk-Mitarbeiter -Chats.

    Sie können diese API verwenden, um transkribierte Nachrichten aus einem laufenden Telefonanruf in Echtzeit beizubehalten oder eine vorhandene Sprachunterhaltungsaufzeichnung für Verlaufszwecke zu transkribieren und zu speichern. Transkribierte Nachrichten werden in Mitarbeiterbereichangezeigt, sodass Service Desk-Mitarbeiter Funktionen wie Agent Assist und Suche nutzen können, während sie mit einem Anrufer sprechen. Transkribierte Nachrichten werden in der Tabelle „Konversationsnachricht“ [sys_cs_message] gespeichert.

    Transkribierte Nachrichten in Agent Workspace

    Anruf-Flow

    Der folgende Anruf-Flow zeigt, wie Sie die Sprachinteraktions -API verwenden, um einen Sprachinteraktionsdatensatz zu erstellen, die Nachrichten in dieser Sprachkonversation zu transkribieren und zu speichern und den Sprachkonversationsdatensatz dann zu schließen. Sie können auch Geschäftsregeln und andere Skripts verwenden, um diese Funktionalität auszuführen. Diese Art der Implementierung wird jedoch in diesem Abschnitt nicht behandelt.
    1. Rufen Sie zuerst den Endpunkt Sprachinteraktionsressource – POST /cs/voice-interactions auf, um einen Sprachinteraktionsdatensatz in der Interaktionstabelle [interaction] zu erstellen.
    2. Rufen Sie dann den Endpunkt Sprachinteraktionsressource – POST /cs/voice-interactions/{interactionId}/messages auf, um übersetzte Nachrichten aus der Sprachkonversation in der Tabelle „ Konversationsnachricht ] zu speichern. Wenn Sie eine Echtzeitkonversation verarbeiten, sollten Sie diesen Endpunkt häufig aufrufen, damit die Nachrichten zeitnah in Mitarbeiterbereich angezeigt werden. Wenn Sie eine Aufzeichnung für Verlaufszwecke verarbeiten, können Sie alle Nachrichten in einem einzelnen Endpunktaufruf übergeben.
    3. Wenn Sie mit dem Beibehalten der Sprachnachrichten fertig sind, rufen Sie den Endpunkt Sprachinteraktionsressource – PATCH /cs/voice-interactions/{interactionId}/state auf, um die Erfassung zu beenden und den Sprachinteraktionsdatensatz zu schließen.

    Verfügbarkeit

    Diese API ist im Basissystem ServiceNow verfügbar. Der Zugriff wird durch die ACLs eingeschränkt, die den Tabellen „Interaktion“ [interaction] und „Konversation“ [sys_cs_conversation] auferlegt wurden.

    Sprachinteraktionsressource – PATCH /cs/voice-interactions/{interactionId}/state

    Beendet die angegebene Sprachinteraktion. Nach dem Anruf werden keine zusätzlichen Sprachnachrichten für die Telefonkonversation übersetzt und gespeichert.

    URL-Format

    Versionierte URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/state

    Standard-URL: /api/now/v1/cs/voice-interactions/{interactionId}/state

    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
    interactionId Sys_id des Interaktionsdatensatzes, dessen Sprachinteraktion beendet werden soll. Befindet sich in der Interaktionstabelle [interaction] und wird vom Sprachinteraktionsressource – POST /cs/voice-interactions -Endpunkt zurückgegeben.

    Datentyp: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    Recording-URL URL, unter der sich die ursprüngliche Sprachaufzeichnung befindet.

    Wenn dies konfiguriert ist, wird diese URL in Mitarbeiterbereichangezeigt.

    Datentyp: Zeichenfolge

    Standard: Keine
    Status Erforderlich. Status der Sprachinteraktion.

    Einziger unterstützter Wert: closed_complete

    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-Antwortcodesder REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Ungültige Anforderung. Falsch formatiertes JSON-Objekt oder erforderliche Parameter wurden nicht übergeben.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    Ergebnis Status des Vorgangs.
    Mögliche Werte:
    • Erfolg
    • Fehlgeschlagen

    Wenn ein Fehler auftritt, wird auch eine Meldung zurückgegeben, die den Fehler beschreibt. Wenn der Fehler in der Instanz ServiceNow auftritt, protokolliert die Instanz den zugehörigen Stack Trace.

    cURL-Anforderung

    Das folgende Beispiel zeigt, wie eine Sprachinstanz beendet wird.

    curl "http://instance.servicenow.com/api/now/v1/ cs/voice-interactions/86837a386f0331003b3c498f5d3ee4ca/state" \ 
--request PATCH \
--header "Content-Type: application/json" \
--header "Accept:application/json" \
--user 'username':'password' \
-d {
  "state": "closed_complete",
  "recordingURL": "https: //zoom_instance/rec/QbF7XmPFHPlX1LG"
}’

    Antwort:

    {
  "result": "Success"
}

    Sprachinteraktionsressource – POST /cs/voice-interactions

    Erstellt einen Sprachinteraktionsdatensatz in der Interaktionstabelle [interaction].

    Sie müssen diesen Datensatz erstellen, bevor Sie versuchen, transkribierte Sprachnachrichten zu speichern. Sie können diesen Endpunkt auch verwenden, um einen Anruf einem bestimmten Service Desk-Mitarbeiter zuzuweisen, indem Sie dessen spezifische Benutzer-ID übergeben.

    URL-Format

    Versionierte URL: /api/now/{api_version}/cs/voice-interactions

    Standard-URL: /api/now/v1/cs/voice-interactions

    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
    agentId Eindeutiger Bezeichner des Service Desk-Mitarbeiters, dem die Sprachinteraktion zugewiesen werden soll. Befindet sich im Feld Benutzer-ID in der Benutzertabelle [sys_user].

    Datentyp: Zeichenfolge

    Standard: Virtual Agent aufrufen
    callerPhoneNumber Telefonnummer für Rückruf des Anrufers. Dies ist die Nummer, die der Service Desk-Mitarbeiter verwendet, um den Anrufer zu erreichen, falls der Anruf abgebrochen wird.

    Datentyp: Zeichenfolge

    Format: Konform mit E.164-Standard

    Standard: Keine
    clientSessionId Eindeutiger Bezeichner eines Datensatzes in einem externen System, der zum Nachverfolgen dieses Telefonanrufs verwendet wird. Diese Informationen verknüpfen die Datensätze zwischen den beiden Systemen.

    Datentyp: Zeichenfolge

    Standard: Keine
    eingehendeId Eindeutiger Identifier des Anwendungsanbieters für den Sprachservice. Befindet sich im Feld Eingehende ID in der Tabelle „Provider-Kanalanwendung“ [sys_cs_provider_application].

    Datentyp: Zeichenfolge

    Standard: Aus Chat abgerufen
    userId Erforderlich. Telefonnummer des Anrufers, der den der Sprachtransaktion zugeordneten Anruf getätigt hat.

    Datentyp: Zeichenfolge

    Format: Wird von der Software definiert, die das Sprachkonversationsskript erstellt hat. In der Regel konform mit dem E.164-Standard.

    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-Antwortcodesder REST-API.

    Tabelle : 12. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Ungültige Anforderung. Falsch formatiertes JSON-Objekt oder erforderliche Parameter wurden nicht übergeben.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    interactionId Sys_id des neu erstellten Sprachinteraktionsdatensatzes. Befindet sich in der Interaktionstabelle [interaction].
    Verwenden Sie diese sys_id in folgenden Fällen:

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie eine Sprachinteraktion initiiert und der Anruf an einen bestimmten Service Desk-Mitarbeiter übertragen wird.

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions" \ 
--request POST \ 
--header "Accept:application/json" \ 
--user 'username':'password' \ 
--header "Content-Type: application/json"\ 
-d '{ 
  "userId": "+14089178877",
  "agentId": "beth.anglin",
  "callerPhoneNumber": "+14089178878",
  "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z"
}'

    Antwort:

    {
  "result": {
    "interactionId": "4462cb4753751110b6e8ddeeff7b12ca"
  }
}

    Sprachinteraktionsressource – POST /cs/voice-interactions/{interactionId}/conversation

    Erstellt einen Konversationsdatensatz in der Konversationstabelle [sys_cs_conversation] für die angegebene Interaktion.

    URL-Format

    Versionierte URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/conversation

    Standard-URL: /api/now/v1/cs/voice-interactions/{interactionId}/conversation

    Unterstützte Anforderungsparameter

    Tabelle : 13. 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
    interactionId Sys_id des Interaktionsdatensatzes, für den der Konversationsdatensatz erstellt werden soll. Dieser Wert wird vom Endpunkt Sprachinteraktionsressource – POST /cs/voice-interactions zurückgegeben und in der Interaktionstabelle [interaction] gespeichert.

    Datentyp: Zeichenfolge
    Tabelle : 14. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 15. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    agentId Eindeutiger Bezeichner des Service Desk-Mitarbeiters, dem die Sprachinteraktion zugewiesen werden soll. Befindet sich im Feld Benutzer-ID in der Benutzertabelle [sys_user].

    Datentyp: Zeichenfolge

    Standard: Virtual Agent aufrufen
    callerPhoneNumber Telefonnummer für Rückruf des Anrufers. Dies ist die Nummer, die der Service Desk-Mitarbeiter verwendet, um den Anrufer zu erreichen, falls der Anruf abgebrochen wird.

    Datentyp: Zeichenfolge

    Format: Konform mit E.164-Standard

    Standard: Keine
    clientSessionId Eindeutiger Bezeichner eines Datensatzes in einem externen System, der zum Nachverfolgen dieses Telefonanrufs verwendet wird. Diese Informationen verknüpfen die Datensätze zwischen den beiden Systemen.

    Datentyp: Zeichenfolge

    Standard: Keine
    eingehendeId Eindeutiger Identifier des Anwendungsanbieters für den Sprachservice. Befindet sich im Feld Eingehende ID in der Tabelle „Provider-Kanalanwendung“ [sys_cs_provider_application].

    Datentyp: Zeichenfolge

    Standard: Aus dem Chat abrufen
    userId Erforderlich. Telefonnummer des Anrufers, der den der Sprachtransaktion zugeordneten Anruf getätigt hat.

    Datentyp: Zeichenfolge

    Format: Wird von der Software definiert, die das Sprachkonversationsskript erstellt hat. In der Regel konform mit dem E.164-Standard.

    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 : 16. 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 : 17. 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-Antwortcodesder REST-API.

    Tabelle : 18. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Ungültige Anforderung. Falsch formatiertes JSON-Objekt oder erforderliche Parameter wurden nicht übergeben.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    conversationId Sys_id des neu erstellten Konversationsdatensatzes. Befindet sich in der Konversationstabelle [sys_cs_conversation].

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie dieser Endpunkt aufgerufen wird.

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/7662cb4721751ea0b6e8dda1b27b131f/conversation" \  
--request POST \  
--header "Accept:application/json" \  
--user 'username':'password' \  
--header "Content-Type: application/json"\  
-d '{  
  "userId": "+14089178877", 
  "agentId": "admin@example.com", 
  "callerPhoneNumber": "+14089178878", 
  "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z" 
}'

    Antwort:

    { 
  "result": "a47e1afdb7471110b6e8bc15ae11a934" 
}

    Sprachinteraktionsressource – POST /cs/voice-interactions/{interactionId}/messages

    Fügt die angegebenen Sprachkonversationsnachrichten dem angegebenen Sprachtransaktionsdatensatz hinzu. Diese Nachrichten werden normalerweise mit Software von Drittanbietern generiert. Derzeit wird nur Amazon Connect unterstützt.

    Sie können diesen Endpunkt während der Echtzeittranskription des Anrufs mehrmals aufrufen oder alle Nachrichten in einem einzigen Anruf übergeben, wenn Sie den Anruf für Verlaufszwecke transkribieren. Wenn Sie eine Echtzeitkonversation verarbeiten, sollten Sie diesen Endpunkt häufig aufrufen, damit die Nachrichten zeitnah in Mitarbeiterbereich angezeigt werden. Nachrichten werden basierend auf ihren Start- und Endzeiten im Verhältnis zum Beginn des Anrufs sortiert.

    URL-Format

    Versionierte URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/messages

    Standard-URL: /api/now/v1/cs/voice-interactions/{interactionId}/messages

    Unterstützte Anforderungsparameter

    Tabelle : 19. 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
    interactionId Sys_id des Interaktionsdatensatzes, dem die angegebenen Nachrichten hinzugefügt werden sollen. Dieser Wert wird vom Endpunkt Sprachinteraktionsressource – POST /cs/voice-interactions zurückgegeben und in der Interaktionstabelle [interaction] gespeichert.

    Datentyp: Zeichenfolge
    Tabelle : 20. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 21. Anforderungstextparameter (Amazon Connect)
    Name Beschreibung
    <json_string>
    Liste der Nachrichten, die an die angegebene Sprachinteraktion angehängt werden sollen.
    "<json_string>":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "Number",
    "participantId": "String",
    "sentiment": "String"
  }
]
    <json_string>.Attribute
    Schlüssel-Wert-Paare, die der Sprachinteraktion zugeordnet werden sollen.

    Dies kann jede Art von Datenobjekt sein, von einfachen Objekten bis hin zu komplexen zusammengesetzten Objekten. Sie werden beim Aufruf von Amazon Web Services-APIs als eindeutige Bezeichner verwendet.

    Datentyp: Array von Objekten

    Standard: Keine
    <json_string>.beginOffsetMillis Erforderlich. Zeitversatz zwischen dem Beginn der Sprachinteraktion und dem Beginn der zugehörigen Nachricht. Beispiel: "beginOffsetMillis": 2650.

    Datentyp: Lang

    Einheit: Millisekunden
    <json_string>.Inhalt Erforderlich. Text der Nachricht, der der Sprachinteraktion hinzugefügt werden soll.

    Datentyp: Zeichenfolge
    <json_string>.endOffsetMillis Erforderlich. Zeitversatz zwischen dem Beginn der Sprachinteraktion und dem Ende der Nachricht. Beispiel: „endOffsetMillis“: 9380.

    Datentyp: Lang

    Einheit: Millisekunden
    <json_string>.id Nachrichten-UUID der Quelle dieser Sprachkonversation, z. B. für AmazonConnect. Legt den Spaltenwert der Quellnachrichten-ID fest.

    Datentyp: Zeichenfolge

    Standard: Keine
    <json_string>.isEvent
    Wird von Amazon Connect festgelegt, aber derzeit nicht von der Methode verwendet. Kennzeichnung, die angibt, ob die zugeordnete Nachricht ein Event ist.
    Gültige Werte:
    • true: Nachricht ist ein Event.
    • false: Nachricht ist kein Event.

    Datentyp: Boolesch

    Standardwert: false
    <json_string>.isInternalMessage
    Kennzeichnung, die angibt, ob dies eine interne Nachricht ist und dem Anrufer nicht angezeigt werden soll.

    Transkriptionen werden in der Regel als interne Nachrichten betrachtet und nur für den Service Desk-Mitarbeiter, nicht für den Anrufer angezeigt. Darüber hinaus wird die Flüsterfunktion verwendet, wenn eine stille Drittpartei ohne Wissen des Anrufers mit einer stillen Drittpartei chattet oder in eine Telefonkonversation einbezogen wird, und einem Service Desk-Mitarbeiter Ratschläge gibt. Der Anrufer hört oder sieht diese Nachrichten nicht, der Service Desk-Mitarbeiter jedoch.

    Gültige Werte:
    • true: Interne Nachricht, wird dem Anrufer nicht angezeigt.
    • false: Keine interne Nachricht, wird dem Anrufer angezeigt.

    Datentyp: Boolesch

    Standardwert: false
    <json_string>.Lautstärkepunktzahl
    Messung, wie laut ein Kunde oder Service Desk-Mitarbeiter während eines Anrufs spricht.

    Contact Lens zeigt eine Analyse der Konversation an, die zeigt, wo die Person möglicherweise laut redet und eine negative Stimmung hat.

    Datentyp: Zahl

    Bereich: -1,0 (negativ) bis 1,0 (positiv)

    Standard: Null
    <json_string>.Teilnehmer-ID
    Erforderlich. Teilnehmer, der der Nachricht zugeordnet ist.
    Gültige Werte:
    • KUNDE
    • AGENT

    Datentyp: Zeichenfolge
    <json_string>.Stimmung
    Stimmung der Nachricht.

    Dieser Wert wird von einem Drittanbieter generiert. Basierend auf den ServiceNow Instanzkonfigurationseinstellungen wird dieser Wert dann entweder in positiv, negativ oder neutral übersetzt und im Konversations- und Interaktionsdatensatz gespeichert.

    Gültige Werte:
    • NEGATIV
    • NEUTRAL
    • POSITIV

    Datentyp: Zeichenfolge

    Standard: Null

    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 : 22. 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 : 23. 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-Antwortcodesder REST-API.

    Tabelle : 24. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Ungültige Anforderung. Falsch formatiertes JSON-Objekt oder erforderliche Parameter wurden nicht übergeben.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    Ergebnis Nachricht, die die Ergebnisse des Anrufs beschreibt.

    Datentyp: Zeichenfolge
    Konversations-ID Sys_id des erstellten Sprachinteraktionsnachrichtendatensatzes. Befindet sich in der Tabelle „Sprachtranskript-Konversationsnachricht“ [sys_cs_message_voice_transcript].

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Beispiel zeigt, wie Nachrichten zu einem vorhandenen Sprachinteraktionsdatensatz hinzugefügt werden.

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/86837a386f0331003b3c498f5d3ee4ca/messages" \ 
--request POST \
--header "Accept:application/json" \
--header "Content-Type: application/json"\ 
--user 'username':'password' \
-d ' [ 
  { 
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 10000,  
    "content": "This is John. How can I help you?",  
    "endOffsetMillis": 15000,  
    "id": "954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8",  
    "participantId": "AGENT",  
    "sentiment": "NEUTRAL",  
    "loudnessScore": "null",  
    "attributes": [{  
      "key": "key1",  
      "value": "value1"  
      }, {  
      "key": "key2",  
      "value": "value2"  
    }] 
  },  
  {  
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 20000,  
    "content": "Uh, yes, John. Um, I'm a little very frustrated right now.",  
    "endOffsetMillis": 25000,  
    "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",  
    "participantId": "CUSTOMER",  
    "sentiment": "NEGATIVE"  
  },  
  {  
    "isEvent": "false",  
    "isInternalMessage": "false",  
    "beginOffsetMillis": 30000,  
    "content": "I am sorry to hear that",  
    "endOffsetMillis": 35000,  
    "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",  
    "participantId": "AGENT",  
    "sentiment": "NEGATIVE",  
 
  },  
  {  
    "isEvent":"false",
    "isInternalMessage":"false",
    "beginOffsetMillis":40000,
    "content":"Can you help me with my insurance? My ssn is 123-12-1234",
    "endOffsetMillis":45000,
    "id":"ab09b3b6-23fd-4e41-be05-6b2b53c19059",
    "participantId":"CUSTOMER",
    "sentiment":"NEUTRAL" 
  },  
  {  
    "isEvent":"False",
    "isInternalMessage":"False",
    "beginOffsetMillis":50000, 
    "content":"Of course, let me check your account",
    "endOffsetMillis":55000,
    "id":"18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f",
    "participantId":"AGENT",
    "sentiment":"NEUTRAL" 
  }  
]'

    Antwort:

    { 
  "result": "Voice conversation transcript has been successfully saved. Conversation id: 8439d3c753b51110b6e8ddeeff7b12e2" 
}

    Sprachinteraktionsressource – POST /cs/voice-interactions/transcript

    Fügt Nachrichten zu einer vorhandenen Sprachinteraktion hinzu, nachdem ein Anruf abgeschlossen ist. Sie können diese API verwenden, um transkribierte Nachrichten eines Sprachanrufs zwischen einem Service Desk-Mitarbeiter und einem Anrufer anzuhängen.

    URL-Format

    Versionierte URL: /api/now/{api_version}/cs/voice-interactions/{interactionId}/transcript

    Standard-URL: /api/now/v1/cs/voice-interactions/{interactionId}/transcript

    Unterstützte Anforderungsparameter

    Tabelle : 25. 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 : 26. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 27. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    KonversationGestartet Startzeit der Konversation. Befindet sich in der Interaktionstabelle [interaction].

    Datentyp: Zeichenfolge

    Format: JJJJ-MM-TT HH:MM:SS
    interactionId Sys_id des Interaktionsdatensatzes, dem die angegebenen Nachrichten hinzugefügt werden sollen. Dieser Wert wird vom Endpunkt Sprachinteraktionsressource – POST /cs/voice-interactions zurückgegeben und in der Interaktionstabelle [interaction] gespeichert.

    Datentyp: Zeichenfolge
    Quelle Name des Kanals, der das Transkript der Konversationsinteraktion ursprünglich erstellt hat.

    Derzeit ist der einzige unterstützte Wert Amazon Connect.

    Datentyp: Zeichenfolge
    Transkript Liste der Nachrichten, die an die angegebene Sprachinteraktion angehängt werden sollen.
    "transcript":[
  {
    "attributes": [Array],
    "beginOffsetMillis": Long,
    "content": "String"
    "endOffsetMillis": Long,
    "id": "String",
    "isEvent": Boolean,
    "isInternalMessage": Boolean,
    "loudnessScore": "String",
    "participantId": "String",
    "sentiment": "String"
  }
]

    Datentyp: Array von Objekten
    transcript.attribute
    Schlüssel-Wert-Paare, die der Sprachinteraktion zugeordnet werden sollen.

    Dies kann jede Art von Datenobjekt sein, von einfachen Objekten bis hin zu komplexen zusammengesetzten Objekten. Sie werden beim Aufruf von Amazon Web Services-APIs als eindeutige Bezeichner verwendet.

    Datentyp: Array von Objekten

    Standard: Keine
    transcript.beginOffsetMillis Erforderlich. Zeitversatz zwischen dem Beginn der Sprachinteraktion und dem Beginn der zugehörigen Nachricht. Beispiel: "beginOffsetMillis": 2650.

    Datentyp: Lang

    Einheit: Millisekunden
    transcript.content Erforderlich. Text der Nachricht, der der Sprachinteraktion hinzugefügt werden soll.

    Datentyp: Zeichenfolge
    transcript.endOffsetMillis Erforderlich. Zeitversatz zwischen dem Beginn der Sprachinteraktion und dem Ende der Nachricht. Beispiel: „endOffsetMillis“: 9380.

    Datentyp: Lang

    Einheit: Millisekunden
    transcript.id Nachrichten-UUID der Quelle dieser Sprachkonversation, z. B. für AmazonConnect. Legt den Spaltenwert der Quellnachrichten-ID fest.

    Datentyp: Zeichenfolge

    Standard: Keine
    transcript.isEvent
    Wird von Amazon Connect festgelegt, aber derzeit nicht von der Methode verwendet. Kennzeichnung, die angibt, ob die zugeordnete Nachricht ein Event ist.
    Gültige Werte:
    • true: Nachricht ist ein Event.
    • false: Nachricht ist kein Event.

    Datentyp: Boolesch

    Standardwert: false
    transcript.isInternalMessage
    Kennzeichnung, die angibt, ob dies eine interne Nachricht ist und dem Anrufer nicht angezeigt werden soll.

    Transkriptionen werden in der Regel als interne Nachrichten betrachtet und nur für den Service Desk-Mitarbeiter, nicht für den Anrufer angezeigt. Darüber hinaus wird die Flüsterfunktion verwendet, wenn eine stille Drittpartei ohne Wissen des Anrufers mit einer stillen Drittpartei chattet oder in eine Telefonkonversation einbezogen wird, und einem Service Desk-Mitarbeiter Ratschläge gibt. Der Anrufer hört oder sieht diese Nachrichten nicht, der Service Desk-Mitarbeiter jedoch.

    Gültige Werte:
    • true: Interne Nachricht, wird dem Anrufer nicht angezeigt.
    • false: Keine interne Nachricht, wird dem Anrufer angezeigt.

    Datentyp: Boolesch

    Standardwert: false
    transcript.lautheitPunktzahl
    Messung, wie laut ein Kunde oder Service Desk-Mitarbeiter während eines Anrufs spricht.

    Contact Lens zeigt eine Analyse der Konversation an, die zeigt, wo die Person möglicherweise laut redet und eine negative Stimmung hat.

    Datentyp: Zahl

    Bereich: -1,0 (negativ) bis 1,0 (positiv)

    Standard: Null
    transcript.participantId
    Erforderlich. Teilnehmer, der der Nachricht zugeordnet ist.
    Gültige Werte:
    • KUNDE
    • AGENT

    Datentyp: Zeichenfolge
    transkript.Stimmung
    Stimmung der Nachricht.

    Dieser Wert wird von einem Drittanbieter generiert. Basierend auf den ServiceNow Instanzkonfigurationseinstellungen wird dieser Wert dann entweder in positiv, negativ oder neutral übersetzt und im Konversations- und Interaktionsdatensatz gespeichert.

    Gültige Werte:
    • NEGATIV
    • NEUTRAL
    • POSITIV

    Datentyp: Zeichenfolge

    Standard: Null

    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 : 28. 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 : 29. 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-Antwortcodesder REST-API.

    Tabelle : 30. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Ungültige Anforderung. Falsch formatiertes JSON-Objekt oder erforderliche Parameter wurden nicht übergeben.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    Ergebnis Nachricht, die die Ergebnisse des Anrufs beschreibt.

    Datentyp: Zeichenfolge
    Konversations-ID Sys_id der Sprachkonversationstabelle, an die die Nachrichten angehängt wurden. Befindet sich in der Konversationstabelle [sys_cs_message_conversation].

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Beispiel zeigt, wie Nachrichten zu einem vorhandenen Sprachinteraktionsdatensatz hinzugefügt werden.

    curl "http://instance.servicenow.com/api/now/v1/cs/voice-interactions/transcript" \  
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type: application/json"\  
--user 'username':'password' \ 
-d ' { 
  "interactionId": "e67a6c30c7233010967a34c91dc26068", 
  "source": "Amazon Connect", 
  "conversationStarted": "2021-08-06 15:07:51", 
  "transcript": [ 
    { 
      "isEvent": "False", 
      "isInternalMessage": "False", 
      "beginOffsetMillis": 100000, 
      "content": "This is John. How can I help you?", 
      "endOffsetMillis": 150000, 
      "id": "954c4edc-31a8-48b0-8f6e-7fa0c4ca00a8", 
      "participantId": "AGENT", 
      "sentiment": "NEUTRAL" 
    }, 
    { 
      "isEvent": "False",
      "isInternalMessage": "False", 
      "beginOffsetMillis": 200000, 
      "content": "Uh, yes, John. Um, I'm a little frustrated right now.", 
      "endOffsetMillis": 25000, 
      "id": "18bcf19c-4a9b-4af1-9bd7-7bfb5ba53b9f", 
      "participantId": "CUSTOMER", 
      "sentiment": "NEGATIVE" 
    } 
  ] 
} ' 

    Antwort:

    {  
  "result": "Voice conversation transcript has been successfully saved. Conversation id: 8439d3c753b51110b6e8ddeeff7b12e2"  
}