Create an AgentWork record
Creates an AgentWork record when the partner-owned routing system finds a rep to handle the work item.
Only use this API if routing is partner-owned (when ConversationChannelDefinition.routingOwner is set to Partner).
AgentWork is a Salesforce object that’s created when the partner-owned routing system finds a potential rep to handle the work item. The AgentWork record contains information about the work item and its routing status. By default, a Pending Service Routing (PSR) record is created at the start of routing (/route).
If a PSR record is automatically created when the /route API is called, only set the required parameters. The PSR has all of the other important details, so if you set any of the other unnecessary parameters, they'll be ignored.
If a PSR isn’t automatically created, in addition to the necessary parameters, also set the capacity weight or capacity percentage field, which the partner-owned system can use to make routing decisions. Salesforce service channels that respect the Status-Based Capacity Model, such as Messaging channels, can also leverage the capacity values to determine rep capacity.
When the AgentWork record is created, rep actions for the record are enabled or disabled by setting the agentActionVisibilities parameters.
This API applies to the following product:
- Bring Your Own Channel for Contact Center as a Service.
This API is available in version 62.0 and later.
v1/agentWork
Authorization: Bearer <Salesforce access token>
String. Standard header. The authorization token, where \<token\> is the JSON Web Token (JWT). Required.
Content-Type: <Request body format>
String. Standard header. The format of the request body. Valid format is multipart/form-data. Required.
OrgId: <Salesforce Org Id>
String. Standard header. The 15-character Org ID of the Salesforce org. Required.
AuthorizationContext: <ConversationChannel Definition developer name>
String. Standard header. The ConversationChannelDefinition developer name in the format {prefix}_{ConversationChannelDefinitionName}. The prefix must match the developer name prefix of the corresponding connected app. For example, Partner1_ChannelDefinition1. Required.
RequestId: <GUID>
String. Standard header. A globally unique ID (GUID). Required.
For example,
| Property Name | Type | Description | Required |
|---|---|---|---|
| userId | string | The 15-character ID of the Salesforce user or the CallCenterRoutingMap.ExternalId. | Yes |
| workItemId | string | The 15-character ID of the associated messaging session (MessagingSession) record. | Yes |
| capacityPercentage | string | The percentage of a rep’s capacity for work items that’s consumed by a specific type of work item from this service channel. After the AgentWork record is created, the partner-owned routing system can use this value to make routing decisions. Only set this parameter if the PSR isn’t automatically created. If the /route API is called, the values from this payload are ignored and this API uses the payload details from the PSR that was created from the /route API. Don’t set this parameter if capacityWeight is set. | No |
| capacityWeight | string | The amount of a rep’s capacity for work items that’s consumed by a work item from this service channel. After the AgentWork record is created, the partner-owned routing system can use this value to make routing decisions. Only set this parameter if the PSR isn’t automatically created. If the /route API is called, the values from this payload are ignored and this API uses the payload details from the PSR that was created from the /route API. Don’t set this parameter if capacityPercentage is set. | No |
| routingContext | object | An object representing the routing details for the agentWork record. Only set this parameter if the PSR isn’t automatically created. If the /route API is called, the values from this payload are ignored and this API uses the payload details from the PSR that was created from the /route API. | No |
| routingContext.conversationIdentifier | string | A unique ID for the conversation. The conversationIdentifier value is generated the first time you call the /interactions API. This value is required if routingContext is required. | No |
| routingContext.routingType | string | Determines whether the conversation that’s being routed is a new conversation or one that’s being transferred. Valid values include: - Initial - A newly-established conversation. - Transfer - An existing conversation that’s being transferred. This value is required if routingContext is required. | No |
| routingContext.routingCorrelationId | string | The unique ID for the routing attempt used to trace the conversation as it’s routed from system to system. If the route API is called, this value is the unique ID of the associated record. Otherwise, this value is any unique ID from the partner system. This value is required if routingContext is required. | No |
| agentActionVisibilities | object | Determines whether an action, such as the “Transfer” action, for the messaging session is enabled for reps to perform. Available in API version 63.0 and later. | Yes |
| agentActionVisibilities.agentAction | enum | Specifies which Messaging action is dynamically controlled to be enabled or disabled. Set this value to “Transfer” to control the transfer action for the messaging session. Available in API version 63.0 and later. | Yes |
| agentActionVisibilities.visible | boolean | Indicates whether the action being controlled is enabled (true) or disabled (false). For transfers, if the action (agentAction) is disabled, the button is still visible but not functional. Available in API version 63.0 and later. | Yes |
Request to create an AgentWork record when a PSR doesn’t exist, setting the rep’s capacity for work items by percentage and enabling the “Transfer” action capability:
Request to create an AgentWork record when a PSR doesn’t exist, setting the rep’s capacity for work items by weight and disabling the “Transfer” action capability:
Request to create an AgentWork record for an existing Pending Service Routing (PSR) record with the “Transfer” action capability enabled for reps:
- GitHub: Interaction Service APIs
- Bring Your Own Channel for CCaaS: Configure Partner-Owned Routing and Consent
- Bring Your Own Channel for CCaaS: Dynamically Control Messaging Actions
- Salesforce Help: Understand Capacity Models