API de membre de conversation

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 9 minutes de lecture

    • L’API de membre de conversation fournit des méthodes pour changer l’état membre d’un agent spécifique à supprimer ou à mettre à jour dans une conversation de Messagerie instantanée d’agent donnée.

    Cette API offre la possibilité de gérer par programmation l’état d’un membre agent dans les conversations dans Messagerie instantanée d'agent l’expérience Interfaces conversationnelles. Voir Messagerie instantanée d’agent pour plus d’informations.

    Cette API est disponible par défaut. L’utilisateur appelant doit avoir le rôle awa_integration_user.

    Membre de la conversation : PUT /now/conversation/member/{user_id}/drop

    Supprime un agent d’une conversation.

    Format d'URL

    URL par défaut : /api/now/conversation/member/{user_id}/drop

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    Nom Description
    user_id Sys_id de l’agent à abandonner de la conversation.

    Type de données : chaîne

    Table : Utilisateur [sys_user]
    Tableau 2. Paramètres de requête
    Nom Description
    Aucun
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    interaction_id Requis. Sys_id de l’enregistrement de conversation à partir duquel abandonner l’agent.

    Type de données : chaîne

    Table : Interaction [interaction]

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Type de contenu Format de données du corps de la demande. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 5. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 6. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    400Erreur lors du traitement des opérations de membres de la conversation. Par exemple :
    • La conversation est introuvable pour l’interaction fournie.
    • L’utilisateur n’est pas membre de la conversation d’interaction fournie.

      Fournissez une user_id ou une interaction_id différente dans la demande.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    403 Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié.

    Paramètres du corps de la réponse (JSON ou XML)

    Nom Description
    conversation_member Objet contenant des informations sur l’état de l’agent en tant que membre d’une conversation, après le traitement de la demande de dépôt.

    Type de données : objet

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.actif Marqueur indiquant si l’utilisateur actuel est présent dans la conversation.
    Valeurs possibles :
    • vrai : l’agent est actif dans la conversation.
    • faux : l’agent est supprimé de la conversation et n’est plus un participant actif à la messagerie instantanée.

    Type de données : booléennes
    conversation_member.memberType Type d’agent membre.
    Valeurs possibles :
    • public_fulfiller : permet à l’agent de discuter publiquement avec d’autres agents et le demandeur dans une conversation donnée.
    • observateur : uniquement disponible pour l’utilisateur ayant le rôle de gestionnaire. Accorde le droit de consulter le contenu de la conversation sans y participer.
    • private_fulfiller : permet à l’agent de rejoindre une conversation privée entre les agents pour discuter de la conversation en cours.

    Type de données : chaîne

    Table : Membre de la conversation [sys_cs_conversation_member]
    conversation_member.id_conversation_conversation Requis. Sys_id de l’enregistrement de conversation duquel l’agent a été supprimé.

    Type de données : chaîne

    Table : Interaction [interaction]
    réussite Marqueur indiquant si le processus d’agent de dépôt a réussi.
    Valeurs valides :
    • vrai : l’agent a été abandonné avec succès.
    • faux : l’agent n’a pas été abandonné et est toujours considéré comme actif dans la conversation.

    Type de données : booléennes
    message Message de réponse confirmant l’affectation réussie ou l’exception.

    Message de réussite : La demande d’abandon de l’agent a été traitée avec succès.

    Exceptions possibles :
    • Demande non valide. Entrée insuffisante : l’sys_id de l’agent ou le sys_id d’interaction n’est pas fourni dans la demande.
    • L’interaction fournie n’est pas une interaction de tiers : la demande ne fonctionne que pour l’interaction de tiers et la interaction_id donnée n’est pas une interaction de tiers.
    • La conversation pour l’interaction correspondante est introuvable : impossible de trouver l’enregistrement de conversation correspondant avec le sys_id d’interaction donné.
    • Demande non valide. L’utilisateur n’est pas membre de l’interaction fournie : l’agent sys_id n’est pas membre de la conversation d’interaction donnée.

    Type de données : chaîne

    Demande cURL

    L’exemple suivant montre comment supprimer l’ID utilisateur de l’agent donné à partir de l’ID d’interaction donné.

    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'

    La réponse indique une opération d’abandon réussie pour l’agent donné à partir de l’interaction. Notez que le champ actif est défini sur false et que le message indique une opération de dépôt réussie.

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

    Membre de la conversation : PUT /now/conversation/member/{user_id}/update

    Met à jour le type de membre de l’agent dans une conversation donnée vers un prestataire public à partir d’un type de prestataire observateur ou privé.

    Vous ne pouvez utiliser ce point de terminaison que pour mettre à jour le type Observateur actuel ou Prestataire privé d’un agent sur un type de prestataire public. Ce point de terminaison ne prend pas en charge le retour de l’agent à un type observateur ou privé. La réponse renvoie un code d’état 500 si l’agent donné détient déjà un rôle de prestataire public.

    Le scénario suivant est un exemple de la façon dont le type de membre d’un agent est mis à jour à l’aide du point de terminaison de mise à jour PUT du membre de la conversation :
    1. Le superviseur ouvre et observe une conversation en cours à laquelle l’agent demande de l’aide.
    2. Le superviseur décide de rejoindre la conversation pour proposer de l’aide et clique sur le bouton « Rejoindre la conversation » dans l’interface utilisateur. La demande de participation à la conversation est envoyée au serveur tiers.
    3. Le serveur tiers traite la demande de participation à la conversation et appelle le point de terminaison de mise à jour PUT de membre de la conversation et met à jour le type de membre du superviseur d’observateur à prestataire public.
    4. L’interface utilisateur cliente de l’agent reflète l’état de la conversation mis à jour.

    Format d'URL

    URL versionnée : /api/now/{api_version}/conversation/member/{user_id}/update

    URL par défaut : /api/now/conversation/member/{user_id}/update

    Paramètres de demande pris en charge

    Tableau 7. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière.

    Type de données : chaîne
    user_id Sys_id de l’agent à mettre à jour avec un nouveau type de membre dans la conversation.

    Type de données : chaîne

    Table : Utilisateur [sys_user]
    Tableau 8. Paramètres de requête
    Nom Description
    Aucun
    Tableau 9. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    interaction_id Requis. Sys_id de l’enregistrement de conversation dans lequel mettre à jour le type de membre de l’agent.

    Type de données : chaîne

    Table : Interaction [interaction]
    member_type Requis. Type de membre auquel mettre à jour l’agent dans la conversation donnée.

    Seule valeur valide : public_fulfiller

    Type de données : chaîne

    Table : Membre de la conversation [sys_cs_conversation_member], Champ : Type de membre

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 10. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 11. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 12. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    400 Erreur lors du traitement des opérations de membres de la conversation.
    Par exemple :
    • La conversation est introuvable pour l’interaction fournie.
    • L’utilisateur n’est pas membre de la conversation d’interaction fournie.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    403 Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres du corps de la réponse (JSON ou XML)

    Nom Description
    conversation_member Objet contenant des informations sur l’état du membre de l’agent une fois la demande de mise à jour traitée.

    Type de données : objet

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.actif Marqueur indiquant si l’utilisateur actuel est présent dans la conversation.
    Valeurs possibles :
    • vrai : l’agent est actif dans la conversation.
    • faux : l’agent est supprimé de la conversation et n’est plus un participant actif à la messagerie instantanée.

    Type de données : booléennes
    conversation_member.memberType Type d’agent membre.
    Valeurs possibles :
    • public_fulfiller : permet à l’agent de discuter publiquement avec d’autres agents et le demandeur dans une conversation donnée.
    • observateur : uniquement disponible pour l’utilisateur ayant le rôle de gestionnaire. Accorde le droit de consulter le contenu de la conversation sans y participer.
    • private_fulfiller : permet à l’agent de rejoindre une conversation privée entre les agents pour discuter de la conversation en cours.

    Type de données : chaîne

    Table : Membre de la conversation [sys_cs_conversation_member]
    conversation_member.id_conversation_conversation Sys_id de l’enregistrement de conversation dans lequel l’agent a été mis à jour.

    Type de données : chaîne

    Table : Interaction [interaction]
    réussite Marqueur indiquant si le processus de mise à jour a réussi.
    Valeurs valides :
    • vrai : agent mis à jour avec succès.
    • faux : échec de la mise à jour de l’agent.

    Type de données : booléennes
    message Message de réponse confirmant l’affectation réussie ou l’exception.

    Message de réussite : La demande de mise à jour du type de membre d’agent a été traitée avec succès.

    Exceptions possibles :
    • Demande non valide. Entrée insuffisante : l’sys_id de l’agent ou le sys_id d’interaction n’est pas fourni dans la demande.
    • L’interaction fournie n’est pas une interaction de tiers : la demande ne fonctionne que pour l’interaction de tiers et celle donnée n’est pas une interaction de tiers.
    • Demande non valide. Le type de membre doit être l’un des [type de membre autorisé] : le type de membre fourni dans la demande n’appartient pas à l’un des types autorisés à être mis à jour.
    • La conversation pour l’interaction correspondante est introuvable : impossible de trouver l’enregistrement de conversation correspondant avec le sys_id d’interaction donné.
    • Demande non valide. L’utilisateur n’est pas un membre de l’interaction fournie : l’agent donné sys_id n’est pas membre de la conversation d’interaction donnée.

    Type de données : chaîne

    Demande cURL

    La demande suivante montre comment mettre à jour un utilisateur agent vers un rôle de prestataire public dans une conversation donnée.

    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'

    La réponse renvoie des informations sur la mise à jour réussie d’un rôle de prestataire public. Notez que memberType est mis à jour, mais que le champ actif reste vrai, ce qui indique que le type de l’agent a changé mais qu’il est toujours actif dans la conversation.

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