--- schema_version: "1" id: e8bef3552b83d0eb220158bf5e5e01e678d929e1a4ba0eb568d75584c20381b9 title: Update an AgentWork Record collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/interaction-service-api/references/api-agentWork-patch.md canonical_url: https://developer.salesforce.com/docs/service/messaging-byob/references/byob-reference/api-agentWork-patch.html source_site: developer.salesforce.com content_type: documentation content_hash: 7e063bb54d26588525cba8080b4ad72ed07e0337a3a759bf9b0f1ec62e17de84 products: - Bring Your Own Bot for Messaging - Service Cloud Developer Content --- # 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. ## Special Access Rules To use the Update an Agentwork Record API, the user specified in the `sub` value for [generating a signed JSON web token](https://developer.salesforce.com/docs/service/messaging-byob/references/guides/authorization.md) needs permission to update AgentWork status. Make sure this user is a Salesforce System Administrator or [use a role hierarchy](https://help.salesforce.com/s/articleView?id=platform.security_controlling_access_using_hierarchies.htm) to provide appropriate permission to update AgentWork records. ## Methods to Update AgentWork 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). ### Accept AgentWork For **Bring Your Own Bot**, set status to **Accept** to let a bot join a conversation by accepting the AgentWork record. ### Cancel AgentWork 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. ### Close AgentWork 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. ### Decline AgentWork For **Bring Your Own Bot**, set status to **Decline** to let a bot reject a the conversation by declining the AgentWork record. ## URI `v1/agentWork` ## HTTP Method PATCH ## Headers ### Authorization (User-Level Authentication) **Format:** `Bearer ` String. Standard header. Used to authenticate the user, where `` is the Salesforce access token used as the bearer token to make requests to the Interaction Service APIs. Required. ### Content-Type **Format:** `application/json` String. Standard header. Format of the request payload. Required for any request that includes a body. ### OrgId **Format:** `` String. Custom header. The Salesforce org. `` is the 15-character Org ID of the Salesforce org. Required. ### RequestId **Format:** `` String. Custom header. Universally Unique Identifier (``) that references and tracks this request. Required. ### AuthorizationContext **Format:** `` 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 `` to the developer name of the ConversationChannelDefinition record. For example, Partner1_ChannelDefinition1. Required. - For Bring Your Own Bot (BYOB), set `` to the developer name of the ExtConvParticipantIntegDef record. For example, Partnerapp_ExtConvParticipantIntegDef. Required. ### AuthorizationContextType **Format:** `` String. Custom header. Specifies the type of context for the request. - For Bring Your Own Bot (BYOB), set `` to **ExternalConversationParticipant**. ### AuthorizationContextType **Format:** `` String. Custom header. Specifies the type of context for the request. - For Bring Your Own Channel for CCaaS, set `` to **ConversationChannelDefinition**. ### Sample Header for Bring Your Own Channel for CCaaS ``` -H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \ -H "content-type: application/json" \ -H "OrgId: 00DSG000009SWby" \ -H "AuthorizationContext: Partner1_ChannelDefinition1" \ -H "AuthorizationContextType: ConversationChannelDefinition" \ -H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \ ``` ### Sample Header for Bring Your Own Bot ``` -H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \ -H "content-type: application/json" \ -H "OrgId: 00DSG000009SWby" \ -H "AuthorizationContext: Partnerapp_ExtConvParticipantIntegDef" \ -H "AuthorizationContextType: ExternalConversationParticipant" \ -H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \ ``` ## Parameters | Property Name | Type | Description | Required | | :------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | | workId | string | Salesforce 15-character AgentWork record ID. | Yes | | botId | string | The 15-character ID of the bot that’s handling the conversation. This is a relationship field. Required for Bring Your Own Bot (BYOB). | Yes | | workItemId | string | The 15-character ID of the associated MessagingSession record. Required for Bring Your Own Bot (BYOB). | Yes | | status | string | Status 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 | | contextType | string | Target 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 | ## Bring Your Own Channel for CCaaS Examples Request to cancel an AgentWork record if a rep doesn’t accept the conversation: ```json { "workId": "0BzSG000001gqPp0AI", "status": "Cancel", "contextType": "Agent" } ``` Request to close an AgentWork record from the partner system, for example, when the rep disconnects and you must release capacity: ```json { "workId": "0BzSG000001gqPp0AI", "status": "Close", "contextType": "Agent" } ``` ## Bring Your Own Bot Examples 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: ```json { "workId": "0BzSG000001gqPp0AI", "workItemId": "0Mw000000000000", "botId": "1JZSB000002jTO5", "status": "Accept", "contextType": "Chatbot" } ``` ## See Also - [Create an AgentWork Record](https://developer.salesforce.com/docs/service/messaging-byob/references/byob-reference/api-agentWork.md) - _GitHub_: [Interaction Service APIs](https://github.com/salesforce-misc/interaction-service-apis) - _Object Reference_: [AgentWork](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_agentwork.htm) - _Salesforce Help:_ [Route Work with Omni-Channel](https://help.salesforce.com/s/articleView?id=service.omnichannel_intro.htm) - _Salesforce Help:_ [Controlling Access Using the Role Hierarchy](https://help.salesforce.com/s/articleView?id=platform.security_controlling_access_using_hierarchies.htm)