Register Capabilities
Registers the capabilities that a messaging channel supports, including structured content message types and their format types, as well as progress indicators. Include a format type field restriction, if needed.
After a partner registers message format types, an admin sets up interactive messaging components for their Messaging channel as needed. If a partner has registered the capability and an admin has set up the messaging component, a rep can send a message to a Messaging end user with the supported structured content format type. A Messaging end user can also select an option for an inbound response. Certain format types, like rich links for link previews, don’t require that an admin set up a messaging component.
Partners only need to register capabilities for an integration once, unless those capabilities change.
This API applies to the following products:
- Bring Your Own Channel for Messaging
- Bring Your Own Channel for Contact Center as a Service
This API is available in version 61.0 and later.
v1/capabilities
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 Channel for Messaging, 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 and Bring Your Own Channel for Messaging, set <AuthorizationContextType> to the ConversationChannelDefinition. If not set, this header defaults to ConversationChannelDefinition.
| Property Name | Type | Description | Required |
|---|---|---|---|
| capabilities | object | An object that defines the various capabilities of the application. | Yes |
| appType | string | The app type for which the capabilities are being registered. Set this value to custom to represent a custom channel. | Yes |
| channelCapabilities | array | A list of the capabilities and restrictions for the requested app’s channels. | Yes |
| channelCapabilities.channelType | array | The channel type. Set this value to custom to represent a custom channel. | No |
| channelCapabilities.customIntegration | object | Specifies the custom integration type, integration namespace, and conversation channel definition to register capabilities for. customIntegrationType specifies the type of custom integration. Set this value to CustomChannelIntegration for Bring Your Own Channel. integrationNamespace specifies the namespace or orgId. Partners producing an integration, use the integration’s Namespace value. Customers who are self-implementing, use the OrgId value. conversationChannelDefinitionDevName specifies the developer name of the Conversation Channel Definition. | Yes |
| channelCapabilities.messageTypeCapabilities | array | A list of the message type and format type capabilities and any field restrictions. | Yes |
| messageTypeCapabilities.messageType | string | Specifies a list of supported message types. See Message Types for valid values and their descriptions. | Yes |
| messageTypeCapabilities.formatTypeCapabilities | array | Specifies a list of format types that are supported for a message type. | Yes |
| formatTypeCapabilities.formatType | string | Specifies the name of the format type to register for the message type. See Format Types for valid values and their descriptions for each supported message type. | Yes |
| formatTypeCapabilities.fieldRestrictions | array | Specifies a list of restrictions on the fields on the message format type. To set a restriction, include restriction with fieldRestrictionType. See Field Restriction Types for valid values and details for each fieldRestrictionType. Also include fieldJsonPath, a pointer to a field in the message JSON to which the restriction is applied. This value supports the Root ($) and child (.) operators only. For example, $.some.field, $.some.array, $.some.array.field. | No |
| progressIndicatorTypeCapabilities | array | A list of progress indicator capabilities for the integration. | No |
| progressIndicatorTypeCapabilities.progressIndicatorType | string | Specifies the type of progress indicator. Set this value to ProgressUpdateIndicator. | No |
| progressIndicatorTypeCapabilities.formatTypeCapabilities | array | Lists the format types supported for the progress indicator capability. Set formatType to Text. | No |
| Message Type (messageType) | Description |
|---|---|
| StaticContentMessage | A message containing static content. |
| ChoicesMessage | A message with some choices from which the recipient can choose. This API doesn't cause CRM changes, such as creating and updating records, but sometimes results in conversation routing in bots. |
| ChoicesResponseMessage | A message with the selected choices as a response to a Choices message. |
| FormMessage | A message with a form containing multiple single or multiselect choices that a recipient can choose from. |
| FormResponseMessage | A message with the form selection as a response to a Form message. The message results in a record being created or updated in the CRM database. |
This table lists all supported message types and their possible format types.
| Message Type (messageType) | Format Type (formatType) | Description |
|---|---|---|
| StaticContentMessage | Text | Plain text. The Text format is the default format for messaging components, and is used if the formats added to the component aren’t available or supported in a channel. |
| StaticContentMessage | RichLink | A rich link containing additional metadata like an inline image or video. |
| StaticContentMessage | Links | A URL in a string format. |
| StaticContentMessage | Attachments | Attachments stored in the CRM. Sent with MT messages. Can have optional text. |
| StaticContentMessage | Media | A link name and image. |
| StaticContentMessage | WebView | Web page sent. |
| StaticContentMessage | Application | A link to an external application or iOS extension. |
| StaticContentMessage | ExperienceType | Rich, interactive UI components with full formatting. Handles dynamic, structured data and supports interactive UI elements. Supports ESTypes. |
| ChoicesMessage | Buttons | A text with buttons with a title. The buttons can be postbacks. |
| ChoicesMessage | Carousel | A set of items that can include images, text, and buttons. The buttons can be postbacks. |
| ChoicesMessage | MessageDefinition | Reference and use existing messaging components by their ID or developer name. |
| ChoicesMessage | QuickReplies | An optional text with buttons that has titles and/or images. All buttons are postbacks. |
| ChoicesMessage | ListPicker | A clickable text prompt that leads to a vertical list of up to 10 clickable options. |
| ChoicesMessage | TimePicker | A prompt with a list of open time slots. |
| ChoicesResponseMessage | Selections | Selections of options from choices or forms. Always set for choice and form response. |
| FormMessage | Inputs | Sends a form from the rep side. |
| FormMessage | Flow | Rich, customizable fields to guide customers through a structured business interaction in a form. |
| FormMessage | MessageDefinition | Reference and use existing messaging components by their ID or developer name. |
| FormResponseMessage | Result | The end user’s responses to the form sent from the rep. |
For sample field restriction payloads, see Register a Capability with a Field Restriction.
| Field Restriction Type Value | Type | Description |
|---|---|---|
| StringFieldRestriction | object | Specifies the encoding and maxLength for a string restriction on a message field. encoding is the character encoding to use when evaluating the string. Valid values are UTF8, GSM, UCS2. maxLength is the character length maximum for the field, in int64. |
| MimeTypeRestriction | object | Specifies the mimeType for a mime type restriction on a message field. |
| FileSizeRestriction | object | Specifies the maxSizeInKb to limit the maximum file size in kilobytes for a messaging field, in int64. |
| DimensionRestriction | object | Specifies the x, y, and dimensionType information to set dimension restrictions for the message field. x specifies x dimension limits for the media. y specifies y dimension limits for the media. dimensionType indicates how the dimension field is interpreted. Valid values are PIXEL or RATIO. |
| ArrayRestriction | object | Specifies the maxItems to limit the maximum number of items in the array for a message field, in int64. |
| RequiredFieldRestriction | object | Specifies fieldRequired, a boolean value that notes whether a flag is required for a message field. |
| TypeRestriction | object | Specifies the type restriction as a string for a message field. |
Use the Register Capabilities API to register capabilities for more than one channel, message type, or format type at a time. Or register a message type with a format type along with a progress indicator capability. You can also set restrictions on fields while registering capabilities.
You can register channel capabilities for more than one channel at a time.
You can register more than one message type at a time.
You can register more than one format type at the same time.
If preferred, you can register a single message type and format type for a channel at a time.
You can add registration for progress indicators for AI agents to a payload that registers a messaging type and its format type.
You can set field restrictions for arrays, strings, mime type, file size, dimension, whether a field is required, or type.