Konversationsmitglied-API

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 7 Minuten Lesedauer

    • Die Konversationsmitglied Die API bietet Methoden zum Ändern des Mitgliedsstatus eines bestimmten Service Desk-Mitarbeiters in „entfernt“ oder „aktualisiert“ in einer bestimmten Mitarbeiterchat-Konversation.

    Diese API bietet die Möglichkeit, den Status eines Service Desk-Mitarbeiters in -Konversationen programmgesteuert zu verwalten Mitarbeiterchat Experience von Konversations-Schnittstellen. Siehe Mitarbeiterchat Weitere Informationen finden Sie unter .

    Diese API ist standardmäßig verfügbar. Der aufrufende Anwender muss über die Rolle Awa_Integration_user verfügen.

    Konversationsmitglied – PUT /now/Conversation/member/{user_ID}/Drop

    Löscht einen Service Desk-Mitarbeiter aus einer Konversation.

    URL-Format

    Standard-URL: /api/now/Conversation/member/{user_ID}/Drop

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    user_id SYS_ID des Service Desk-Mitarbeiters, der aus der Konversation abgelegt werden soll.

    Datentyp: Zeichenfolge

    Tabelle: Benutzer [sys_user]
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    interaction_id Erforderlich. SYS_ID des Konversationsdatensatzes, aus dem der Agent abgelegt werden soll.

    Datentyp: Zeichenfolge

    Tabelle: Interaktion [Interaktion]

    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.
    400Fehler beim Verarbeiten von Vorgängen für Konversationsmitglieder. Zum Beispiel:
    • Konversation für die angegebene Interaktion nicht gefunden.
    • Anwender ist kein Mitglied der bereitgestellten Interaktionskonversation.

      Geben Sie eine andere user_ID oder Interaction_ID in der Anforderung an.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    403 Unzulässig. Der Anwender hat keine Zugriffsrechte für den angegebenen Datensatz.

    Antworttext-Parameter (JSON oder XML)

    Name Beschreibung
    Conversation_member Objekt, das Informationen zum Status des Service Desk-Mitarbeiters als Konversationsmitglied enthält, nachdem die Anforderung zum Ablegen verarbeitet wurde.

    Datentyp: Objekt

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    Conversation_member.Active Kennzeichnung, die angibt, ob der aktuelle Anwender in der Konversation anwesend ist.
    Mögliche Werte:
    • Wahr: Service Desk-Mitarbeiter ist in der Konversation aktiv.
    • Falsch: Der Service Desk-Mitarbeiter wird aus der Konversation entlassen und ist kein aktiver Teilnehmer mehr im Chat.

    Datentyp: Boolesch
    Conversation_member.member Type Typ des Mitglieds-Service Desk-Mitarbeiters.
    Mögliche Werte:
    • Public_Fulfiller: Ermöglicht dem Service Desk-Mitarbeiter, in einer bestimmten Konversation öffentlich mit anderen Service Desk-Mitarbeitern und anfordernden Personen zu chatten.
    • Beobachter: Nur für den Anwender mit der Managerrolle verfügbar. Gewährt das Recht, den Konversationsinhalt anzuzeigen, ohne der Konversation beizutreten.
    • Private_Fulfiller: Ermöglicht Service Desk-Mitarbeitern, an einem privaten Chat zwischen den Service Desk-Mitarbeitern teilzunehmen, um die aktive Konversation zu besprechen.

    Datentyp: Zeichenfolge

    Tabelle: Konversationsmitglied [sys_cs_Conversation_member]
    Conversation_member.Conversation_ID Erforderlich. SYS_ID des Konversationsdatensatzes, aus dem der Agent abgelegt wurde.

    Datentyp: Zeichenfolge

    Tabelle: Interaktion [Interaktion]
    Erfolg Kennzeichnung, die angibt, ob der Prozess zum Löschen des Service Desk-Mitarbeiters erfolgreich war.
    Gültige Werte:
    • Wahr: Service Desk-Mitarbeiter erfolgreich verworfen.
    • Falsch: Der Service Desk-Mitarbeiter konnte nicht verworfen werden und wird in der Konversation weiterhin als aktiv betrachtet.

    Datentyp: Boolesch
    Nachricht Antwortnachricht zur Bestätigung einer erfolgreichen Zuweisung oder Ausnahme.

    Erfolgsmeldung: Anforderung zum Verwerfen des Service Desk-Mitarbeiters erfolgreich verarbeitet.

    Mögliche Ausnahmen:
    • Ungültige Anforderung. Unzureichende Eingabe : Sys_ID oder sys_ID der Interaktion des Service Desk-Mitarbeiters ist in der Anforderung nicht angegeben.
    • Angegebene Interaktion ist keine Drittpartei-Interaktion : Die Anforderung funktioniert nur für die Drittparteiinteraktion, und die angegebene Interaction_ID ist keine Drittparteiinteraktion.
    • Konversation für entsprechende Interaktion wurde nicht gefunden : Der entsprechende Konversationsdatensatz mit der angegebenen Interaktions-sys_ID kann nicht gefunden werden
    • Ungültige Anforderung. Anwender ist kein Mitglied der angegebenen Interaktion : Sys_ID des Service Desk-Mitarbeiters ist kein Mitglied der angegebenen Interaktionskonversation.

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Beispiel zeigt, wie die Anwender-ID des angegebenen Service Desk-Mitarbeiters aus der angegebenen Interaktions-ID abgelegt wird.

    curl "https://instance.servicenow.com/api/now/conversation/member/0b10223c57a313005baaaa65ef94f970/drop" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\" interaction_id":\"27f675e3739713004a905ee515f6a7c3\"}" \ 
--user 'username':'password'

    Die Antwort zeigt einen erfolgreichen Löschvorgang für den angegebenen Service Desk-Mitarbeiter aus der Interaktion an. Beachten Sie, dass das aktive Feld auf „falsch“ festgelegt ist und die Meldung einen erfolgreichen Löschvorgang anzeigt.

    {
  "result": {
    "conversation_member": {
      "active": false,
      "memberType": "public_fulfiller",
      "conversation_id": "27f675e3739713004a905ee515f6a7c3"
    },
    "success": true,
    "message": "Request to drop agent processed successfully."
  }
}

    Konversationsmitglied – PUT /now/Conversation/member/{user_ID}/Update

    Aktualisiert den Mitgliedstyp des Service Desk-Mitarbeiters in einer bestimmten Konversation auf einen öffentlichen Erfüller aus einem Beobachtertyp oder privaten Erfüller.

    Sie können diesen Endpunkt nur verwenden, um den aktuellen Beobachtertyp oder privaten Erfüller eines Service Desk-Mitarbeiters auf einen öffentlichen Erfüller-Typ zu aktualisieren. Dieser Endpunkt unterstützt nicht das Wechseln des Service Desk-Mitarbeiters zurück zu einem Beobachtertyp oder privaten Typ. Die Antwort gibt einen Statuscode 500 zurück, wenn der angegebene Service Desk-Mitarbeiter bereits eine öffentliche Erfüller-Rolle innehat.

    Das folgende Szenario ist ein Beispiel dafür, wie der Mitgliedstyp eines Service Desk-Mitarbeiters mit aktualisiert wird Konversationsmitglied – Update PLATZIEREN Endpunkt:
    1. Der Vorgesetzte öffnet und beobachtet eine laufende Konversation, bei der der Service Desk-Mitarbeiter um Hilfe bittet.
    2. Der Vorgesetzte entscheidet sich, der Konversation beizutreten, um Hilfe anzubieten, und klickt in der Anwenderoberfläche auf die Schaltfläche „Konversation beitreten“. Die Anforderung zum Beitritt zur Konversation wird an den Drittparteiserver gesendet.
    3. Der Drittparteiserver verarbeitet die Anforderung zum Beitritt zur Konversation und ruft den auf Konversationsmitglied – Update PLATZIEREN Endpunkt und aktualisiert den Mitgliedstyp des Vorgesetzten vom Beobachter zum öffentlichen Erfüller.
    4. Die Client-UI des Service Desk-Mitarbeiters spiegelt den aktualisierten Konversationsstatus wider.

    URL-Format

    Versionierte URL: /api/now/{api_Version}/Conversation/member/{user_ID}/Update

    Standard-URL: /api/now/Conversation/member/{user_ID}/Update

    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
    user_id SYS_ID des Service Desk-Mitarbeiters, der mit einem neuen Mitgliedstyp in der Konversation aktualisiert werden soll.

    Datentyp: Zeichenfolge

    Tabelle: Benutzer [sys_user]
    Tabelle : 8. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 9. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    interaction_id Erforderlich. SYS_ID des Konversationsdatensatzes, in dem der Mitgliedstyp des Service Desk-Mitarbeiters aktualisiert werden soll.

    Datentyp: Zeichenfolge

    Tabelle: Interaktion [Interaktion]
    member_type Erforderlich. Typ des Mitglieds, auf das der Service Desk-Mitarbeiter in der angegebenen Konversation aktualisiert werden soll.

    Nur gültiger Wert: Public_Fulfiller

    Datentyp: Zeichenfolge

    Tabelle: Konversationsmitglied [sys_cs_conversation_member], Feld: Mitgliedstyp

    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
    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 Fehler beim Verarbeiten von Vorgängen für Konversationsmitglieder.
    Zum Beispiel:
    • Konversation für die angegebene Interaktion nicht gefunden.
    • Anwender ist kein Mitglied der bereitgestellten Interaktionskonversation.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    403 Unzulässig. Der Anwender hat keine Zugriffsrechte für den angegebenen Datensatz.
    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
    Conversation_member Objekt, das Informationen zum Status des Mitarbeiters enthält, sobald die Aktualisierungsanforderung verarbeitet wurde.

    Datentyp: Objekt

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    Conversation_member.Active Kennzeichnung, die angibt, ob der aktuelle Anwender in der Konversation anwesend ist.
    Mögliche Werte:
    • Wahr: Service Desk-Mitarbeiter ist in der Konversation aktiv.
    • Falsch: Der Service Desk-Mitarbeiter wird aus der Konversation entlassen und ist kein aktiver Teilnehmer mehr im Chat.

    Datentyp: Boolesch
    Conversation_member.member Type Typ des Mitglieds-Service Desk-Mitarbeiters.
    Mögliche Werte:
    • Public_Fulfiller: Ermöglicht dem Service Desk-Mitarbeiter, in einer bestimmten Konversation öffentlich mit anderen Service Desk-Mitarbeitern und anfordernden Personen zu chatten.
    • Beobachter: Nur für den Anwender mit der Managerrolle verfügbar. Gewährt das Recht, den Konversationsinhalt anzuzeigen, ohne der Konversation beizutreten.
    • Private_Fulfiller: Ermöglicht Service Desk-Mitarbeitern, an einem privaten Chat zwischen den Service Desk-Mitarbeitern teilzunehmen, um die aktive Konversation zu besprechen.

    Datentyp: Zeichenfolge

    Tabelle: Konversationsmitglied [sys_cs_Conversation_member]
    Conversation_member.Conversation_ID SYS_ID des Konversationsdatensatzes, in dem der Service Desk-Mitarbeiter aktualisiert wurde.

    Datentyp: Zeichenfolge

    Tabelle: Interaktion [Interaktion]
    Erfolg Kennzeichnung, die angibt, ob der Aktualisierungsprozess erfolgreich war.
    Gültige Werte:
    • Wahr: Service Desk-Mitarbeiter erfolgreich aktualisiert.
    • Falsch: Agent konnte nicht aktualisiert werden.

    Datentyp: Boolesch
    Nachricht Antwortnachricht zur Bestätigung einer erfolgreichen Zuweisung oder Ausnahme.

    Erfolgsmeldung: Anforderung zum Aktualisieren des Mitgliedstyps des Service Desk-Mitarbeiters erfolgreich verarbeitet.

    Mögliche Ausnahmen:
    • Ungültige Anforderung. Unzureichende Eingabe : Sys_ID oder sys_ID der Interaktion des Service Desk-Mitarbeiters ist in der Anforderung nicht angegeben.
    • Angegebene Interaktion ist keine Drittpartei-Interaktion : Die Anforderung funktioniert nur für die Drittparteiinteraktion, und die angegebene ist keine Drittparteiinteraktion.
    • Ungültige Anforderung. Mitgliedstyp muss einer der folgenden Werte sein: [Zulässiger Mitgliedstyp] : Der in der Anforderung angegebene Mitgliedstyp befindet sich nicht in einem der zulässigen Typen, auf die aktualisiert werden soll.
    • Konversation für entsprechende Interaktion wurde nicht gefunden : Der entsprechende Konversationsdatensatz mit der angegebenen Interaktions-sys_ID konnte nicht gefunden werden
    • Ungültige Anforderung. Anwender ist kein Mitglied der angegebenen Interaktion : Die angegebene sys_ID des Service Desk-Mitarbeiters ist kein Mitglied der angegebenen Interaktionskonversation.

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Die folgende Anforderung zeigt, wie ein Agent-Anwender in einer bestimmten Konversation auf eine öffentliche Erfüller-Rolle aktualisiert wird.

    curl "https://instance.servicenow.com/api/now/conversation/member/{user_id}/update" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{ 
 \"interaction_id"":\"< interaction_sys_id" >\", 
 \"member_type\":\"public_fulfiller\" 
}" \ 
--user 'username':'password'

    Die Antwort gibt Informationen über die erfolgreiche Aktualisierung einer öffentlichen Erfüller-Rolle zurück. Beachten Sie, dass der Mitgliedstyp aktualisiert wird, das aktive Feld jedoch „wahr“ bleibt, was darauf hinweist, dass sich der Typ des Service Desk-Mitarbeiters geändert hat, aber in der Konversation noch aktiv ist.

    {
  "result": {
    "conversation_member": {
      "active": true,
      "memberType": "public_fulfiller",
      "conversation_id": " <conversation_sys_id>"
    },
    "success": true,
    "message": "Request to update agent member type processed successfully."
  }
}