Conversation Member API

The Conversation Member API provides methods for changing a specific agent’s member state to removed or updated in a given Agent Chat conversation.

This API provides the ability to programmatically manage an agent member’s state in conversations in Agent Chat experience of Conversational Interfaces. See Agent Chat for more information.

This API is available by default. The calling user must have the awa_integration_user role.

Parent Topic:REST API reference

Conversation Member - PUT /now/conversation/member/{user_id}/drop

Drops an agent from a conversation.

URL format

Default URL: /api/now/conversation/member/{user_id}/drop

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}

cURL request

The following example demonstrates how to drop the given Agent's user ID from the given interaction ID.

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'

The response shows a successful drop operation for the given Agent from the interaction. Note that the active field is set to false and the message indicates a successful drop operation.

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

Conversation Member - PUT /now/conversation/member/{user_id}/update

Updates the agent's member type in a given conversation to a public fulfiller from an observer or private fulfiller type.

You can only use this endpoint to update an agent's current observer or private fulfiller type to a public fulfiller type. This endpoint does not support switching the agent back to an observer or private type. The response returns a 500 status code if the given agent already holds a public fulfiller role.

The following scenario is an example of how an agent's member type is updated using the Conversation Member PUT update endpoint:

1. The supervisor opens and observes an ongoing conversation which the agent is asking for help.
2. The supervisor decides to join the conversation to offer help and clicks the 'Join Conversation' button in the UI. The join conversation request is sent to the third-party server.
3. The third-party server processes the join conversation request and calls the Conversation Member PUT update endpoint and updates the supervisor's member type from observer to public fulfiller.
4. The agent’s client UI reflects the updated conversation state.

URL format

Versioned URL: /api/now/{api_version}/conversation/member/{user_id}/update

Default URL: /api/now/conversation/member/{user_id}/update

Supported request parameters

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

"conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}

cURL request

The following request demonstrates how to update a Agent user to a public fulfiller role in a given conversation.

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'

The response returns information about the successful update to a public fulfiller role. Note that the memberType is updated but the active field remains true, indicating that the agent's type has changed but is still active in the 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."
  }
}