Update an AgentWork Record

Updates an AgentWork record.

For Bring Your Own Channel for Contact Center as a Service (BYOC for CCaaS), use this API to cancel work before a rep accepts or declines it or to close an AgentWork record from the partner integration side when client-side close paths aren’t available. For Bring Your Own Bot (BYOB), use this API to perform bot actions on AgentWork records, such as having a bot join, reject, or leave a conversation.

This API applies to the following products:

  • Bring Your Own Channel for Contact Center as a Service
  • Bring Your Own Bot (BYOB)

This API is available in version 64.0 and later.

To use the Update an Agentwork Record API, the user specified in the sub value for generating a signed JSON web token needs permission to update AgentWork status. Make sure this user is a Salesforce System Administrator or use a role hierarchy to provide appropriate permission to update AgentWork records.

Use the status field to specify how to update the AgentWork record. Available values are Accept, Cancel, Close, and Decline. Valid values differ based on product (BYOC for CCaaS and BYOB).

For Bring Your Own Bot, set status to Accept to let a bot join a conversation by accepting the AgentWork record.

For Bring Your Own Channel for CCaaS, set status to Cancel to cancel an AgentWork record for a rep before the conversation is assigned to another user, such as a supervisor or another rep.

In Salesforce, AgentWork records track and manage conversations as they’re routed. Each record contains information about the conversation’s routing details, including its routing status and the user assigned to the work. If the assigned user doesn’t accept or decline the work, reassign the work to another user.

To reassign the work to another user:

  1. Call this API with status set to Cancel to cancel the first AgentWork record.
  2. Call POST /v1/agentWork to create a new AgentWork record and assign it to another user.

If you don’t cancel the first AgentWork record before creating the second one, the first record remains assigned and visible to the first user who can still accept the work. If both the first and second users accept the work, they will be in the conversation simultaneously.

You can cancel AgentWork records that are assigned to but not yet accepted or declined by the user. If you try to cancel unassigned AgentWork records or assigned AgentWork records that have already been accepted or declined by the user, an error message is returned stating that the AgentWork record isn’t in a state that can be cancelled.

For Bring Your Own Bot, set status to Close to let a bot leave the conversation by closing the AgentWork record.

For Bring Your Own Channel for CCaaS, set status to Close to close an AgentWork record from your server when the rep can’t rely on client-side mechanisms such as the Omni-Channel toolkit, completing After Conversation Work, or closing the work tab. For example, use Close when the rep loses network connectivity, closes the browser, or disconnects from your application, and you must release capacity or reassign work from your partner system.

Closing an AgentWork record covers these use cases for BYOC for CCaaS.

  • End After Conversation Work immediately and free rep capacity, including for tab-based and status-based capacity models. For tab-based capacity, calling this API releases capacity without the rep closing the work tab.
  • When this API is called during an active messaging session, it inactivates the messaging session. This is appropriate, for example, when the rep is the only participant.
  • Notify a rep who still has the work open in Salesforce with an in-app message that the work item is closed.

If the AgentWork record isn’t in a state that allows close, or the request doesn’t pass validation, the API returns an error and the AgentWork record remains open.

For Bring Your Own Bot, set status to Decline to let a bot reject a the conversation by declining the AgentWork record.

v1/agentWork

PATCH

Format: Bearer <Salesforce Access Token>
String. Standard header. Used to authenticate the user, where <Salesforce Access Token> is the Salesforce access token used as the bearer token to make requests to the Interaction Service APIs. Required.

Format: application/json
String. Standard header. Format of the request payload. Required for any request that includes a body.

Format: <Salesforce Org ID>
String. Custom header. The Salesforce org. <Salesforce Org ID> is the 15-character Org ID of the Salesforce org. Required.

Format: <UUID>
String. Custom header. Universally Unique Identifier (<UUID>) that references and tracks this request. Required.

Format: <AuthorizationContext>
String. Custom header. Additional information for the request authorization used to authenticate and validate requests against the connected app scopes.

  • For Bring Your Own Channel for CCaaS, set <AuthorizationContext> to the developer name of the ConversationChannelDefinition record. For example, Partner1_ChannelDefinition1. Required.
  • For Bring Your Own Bot (BYOB), set <AuthorizationContext> to the developer name of the ExtConvParticipantIntegDef record. For example, Partnerapp_ExtConvParticipantIntegDef. Required.

Format: <AuthorizationContextType>
String. Custom header. Specifies the type of context for the request.

  • For Bring Your Own Bot (BYOB), set <AuthorizationContextType> to ExternalConversationParticipant.

Format: <AuthorizationContextType>
String. Custom header. Specifies the type of context for the request.

  • For Bring Your Own Channel for CCaaS, set <AuthorizationContextType> to ConversationChannelDefinition.
Property NameTypeDescriptionRequired
workIdstringSalesforce 15-character AgentWork record ID.Yes
botIdstringThe 15-character ID of the bot that’s handling the conversation. This is a relationship field. Required for Bring Your Own Bot (BYOB).Yes
workItemIdstringThe 15-character ID of the associated MessagingSession record. Required for Bring Your Own Bot (BYOB).Yes
statusstringStatus of the AgentWork record.
For Bring Your Own Channel for Contact Center as a Service, set this value to Cancel to cancel the AgentWork record. You can only cancel AgentWork records that are assigned to but not yet accepted or declined by the user. If the AgentWork record is unassigned or the rep has already accepted or declined the AgentWork record, setting this value to Cancel returns an error message stating that the AgentWork record isn’t in a state that can be cancelled. Set this value to Close to close the AgentWork record from your server when client-side close paths aren’t available. If the AgentWork record isn’t in a state that allows close, or the request doesn’t pass validation, the API returns an error.
For Bring Your Own Bot (BYOB), set this value to Accept to have the bot join the conversation, Decline to have the bot reject the conversation, or Close to have the bot leave the conversation.		Yes
contextTypestringTarget participant type this AgentWork record update applies to.
For Bring Your Own Channel for Contact Center as a Service, set this value to Agent (representing a rep). If set to Agent, also set status to Cancel or Close.
For Bring Your Own Bot (BYOB), set this value to Chatbot (representing a bot). If set to Chatbot, also set status to Accept, Decline, or Close.		Yes

Request to cancel an AgentWork record if a rep doesn’t accept the conversation:

Request to close an AgentWork record from the partner system, for example, when the rep disconnects and you must release capacity:

For Bring Your Own Bot (BYOB), use this API to perform bot actions on AgentWork records. Set contextType to Chatbot and status to one of the following values to change the bot’s status in the conversation:

  • Accept — Bot joins the conversation by accepting the AgentWork record.
  • Decline — Bot rejects the conversation by declining the AgentWork record.
  • Close — Bot leaves the conversation by closing the AgentWork record.

BYOB payloads also include botId (the 15-character ID of the bot that’s handling the conversation) and workItemId (the 15-character ID of the associated MessagingSession record).

Request for a bot to join the conversation by accepting the AgentWork record: