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 (POST /route).
If a PSR record is automatically created when the POST /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
POST
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.
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 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 POST /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 POST /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 POST /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 POST /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 POST /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 POST /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, one that’s being transferred, or one that’s bringing in more participants through conferencing. Valid values include: - Initial - A newly-established conversation. - Transfer - An existing conversation that’s being transferred. - Conference - An existing conversation that’s bringing in more participants through conferencing. 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” or "Conference" 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, or set it to Conference to control the conferencing 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 and conferencing, 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 “Conference” 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