--- schema_version: "1" id: 2de18357c5a642751c2edd79d40da63d0d94f7a57285b7359ebe1564c1921103 title: Register Capabilities collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/interaction-service-api/references/api-capabilities.md canonical_url: https://developer.salesforce.com/docs/service/messaging-byob/references/byob-reference/api-capabilities.html source_site: developer.salesforce.com content_type: documentation content_hash: 21b18404fea90012de9ec9bcbf8f1b036576c6003a294b643d9cde366c7fb9d1 products: - Bring Your Own Bot for Messaging - Service Cloud Developer Content --- # 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](https://help.salesforce.com/s/articleView?id=service.messaging_components_parent.htm) 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 should register capabilities for an integration at regular intervals, such as weekly or daily. This API applies to the following products: - Bring Your Own Channel for Messaging - Bring Your Own Channel for Contact Center as a Service - Bring Your Own Bot (BYOB) This API is available in version 61.0 and later. ## URI v1/capabilities ## 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 Channel for Messaging, set `` to the developer name of the ConversationChannelDefinition record. For example, Partner1_ChannelDefinition1. Required. ### AuthorizationContextType **Format:** `` String. Custom header. Specifies the type of context for the request. - For Bring Your Own Channel for CCaaS, set `` to **ConversationChannelDefinition**. - For Bring Your Own Channel for Messaging, set `` to **ConversationChannelDefinition**. - For Bring Your Own Bot (BYOB), set `` to **ExternalConversationParticipant**. If not set, this header defaults to **ConversationChannelDefinition**. ### Sample Header ``` -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" \ ``` ## Parameters | 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 or external conversation participant integration definition to register capabilities for.
`customIntegrationType` specifies the type of custom integration. Set this value to **CustomChannelIntegration** for Bring Your Own Channel for Messaging or Bring Your Own Channel for CCaaS, or **CustomBotIntegration** for Bring Your Own Bot (BYOB).
`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. Required for Bring Your Own Channel.
`extConvParticipantIntegDefDevName` specifies the developer name of the `ExtConvParticipantIntegDef` record. Required for Bring Your Own Bot (BYOB). | 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](#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](#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](#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. Not supported for Bring Your Own Bot (BYOB). | No | | progressIndicatorTypeCapabilities.progressIndicatorType | string | Specifies the type of progress indicator. Set this value to **ProgressUpdateIndicator**. Not supported for Bring Your Own Bot (BYOB). | No | | progressIndicatorTypeCapabilities.formatTypeCapabilities | array | Lists the format types supported for the progress indicator capability. Set `formatType` to **Text**. Not supported for Bring Your Own Bot (BYOB). | No | ## Message Types | 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. | ## Format Types 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. | ## Field Restriction Types For sample field restriction payloads, see [Register a Capability with a Field Restriction](#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. | ## Sample Register Capabilites API Payloads 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. ### Register Multiple Channel Capabilities You can register channel capabilities for more than one channel at a time. ```json { "capabilities": { "appType": "Custom", "channelCapabilities": [ { "channelType": "Custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "", "conversationChannelDefinitionDevName": "" }, "messageTypeCapabilities": [ { "messageType": "StaticContentMessage", "formatTypeCapabilities": [ { "formatType": "Text" } ] } ] }, { "channelType": "Custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "", "conversationChannelDefinitionDevName": "" }, "messageTypeCapabilities": [ { "messageType": "StaticContentMessage", "formatTypeCapabilities": [ { "formatType": "Text" } ] } ] } ] } } ``` ### Register Multiple Message Types You can register more than one message type at a time. ```json { "capabilities": { "appType": "Custom", "channelCapabilities": [ { "channelType": "Custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "", "conversationChannelDefinitionDevName": "" }, "messageTypeCapabilities": [ { "messageType": "StaticContentMessage", "formatTypeCapabilities": [ { "formatType": "Text" } ] }, { "messageType": "ChoicesMessage", "formatTypeCapabilities": [ { "formatType": "Buttons" } ] } ] } ] } } ``` ### Register Multiple Format Types You can register more than one format type at the same time. ```json { "capabilities": { "appType": "Custom", "channelCapabilities": [ { "channelType": "Custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "", "conversationChannelDefinitionDevName": "" }, "messageTypeCapabilities": [ { "messageType": "StaticContentMessage", "formatTypeCapabilities": [ { "formatType": "Text" }, { "formatType": "RichLink" } ] } ] } ] } } ``` ### Register a Single Message and Format Type If preferred, you can register a single message type and format type for a channel at a time. ```json { "capabilities": { "appType": "Custom", "channelCapabilities": [ { "channelType": "Custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "", "conversationChannelDefinitionDevName": "" }, "messageTypeCapabilities": [ { "messageType": "StaticContentMessage", "formatTypeCapabilities": [ { "formatType": "Text" } ] } ] } ] } } ``` ### Register a Message Type, Format Type, and Progress Indicator Type You can add registration for progress indicators for AI agents to a payload that registers a messaging type and its format type. ```json { "capabilities": { "appType" : "Custom", "channelCapabilities" : [{ "channelType" : "Custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "", "conversationChannelDefinitionDevName": "" }, "messageTypeCapabilities": [{ "messageType": "StaticContentMessage", "formatTypeCapabilities": [{ "formatType": "Text" }] }], "progressIndicatorTypeCapabilities": [{ "progressIndicatorType": "ProgressUpdateIndicator", "formatTypeCapabilities": [{ "formatType": "Text" }] }] }] } } ``` ### Register a Capability with a Field Restriction You can set field restrictions for arrays, strings, mime type, file size, dimension, whether a field is required, or type. ```json { "capabilities": { "appType" : "custom", "channelCapabilities" : [{ "channelType" : "custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "00Dxx0000006GuB", "conversationChannelDefinitionDevName": "CCaaSDot_ChannelDefinition1" }, "messageTypeCapabilities": [{ "messageType": "StaticContentMessage", "formatTypeCapabilities": [{ "formatType": "Text", "capabilityFieldRestriction": [{ "fieldJsonPath": "$.staticContent.text", "restriction":{ "fieldRestrictionType": "ArrayRestriction", "maxItems": 9 } }] }] }] }] } } ``` ```json { "capabilities": { "appType": "custom", "channelCapabilities": [{ "channelType": "custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "sdb6byo", "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" }, "messageTypeCapabilities": [{ "messageType": "StaticContentMessage", "formatTypeCapabilities": [{ "formatType": "Text", "capabilityFieldRestriction": [{ "fieldJsonPath": "$.staticContent.text", "restriction": { "fieldRestrictionType": "StringFieldRestriction", "encoding": "UTF8", "maxLength": 10 } }] }] }] }] } } ``` ```json { "capabilities": { "appType": "custom", "channelCapabilities": [ { "channelType": "custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "sdb6byo", "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" }, "messageTypeCapabilities": [{ "messageType": "StaticContentMessage", "formatTypeCapabilities": [{ "formatType": "Attachments", "capabilityFieldRestriction": [{ "fieldJsonPath": "$.staticContent.attachments.mimeType", "restriction": { "fieldRestrictionType": "MimeTypeRestriction", "mimeType": "image/png" } }] }] }] }] } } ``` ```json { "capabilities": { "appType": "custom", "channelCapabilities": [ { "channelType": "custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "sdb6byo", "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" }, "messageTypeCapabilities": [{ "messageType": "StaticContentMessage", "formatTypeCapabilities": [{ "formatType": "Attachments", "capabilityFieldRestriction": [{ "fieldJsonPath": "$.staticContent.attachments", "restriction": { "fieldRestrictionType": "FileSizeRestriction", "maxSizeInKb": 1000 } }] }] }] }] } } ``` ```json { "capabilities": { "appType": "custom", "channelCapabilities": [ { "channelType": "custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "sdb6byo", "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" }, "messageTypeCapabilities": [{ "messageType": "StaticContentMessage", "formatTypeCapabilities": [{ "formatType": "Attachments", "capabilityFieldRestriction": [{ "fieldJsonPath": "$.staticContent.attachments", "restriction": { "fieldRestrictionType": "DimensionRestriction", "dimensionType": "PIXEL", "x": 0.1, "y": 0.1 } }] }] }] }] } } ``` ```json { "capabilities": { "appType": "custom", "channelCapabilities": [{ "channelType": "custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "sdb6byo", "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" }, "messageTypeCapabilities": [{ "messageType": "StaticContentMessage", "formatTypeCapabilities": [{ "formatType": "RichLink", "capabilityFieldRestriction": [{ "fieldJsonPath": "$.staticContent.image", "restriction": { "fieldRestrictionType": "RequiredFieldRestriction", "fieldRequired": false } }] }] }] }] } } ``` ```json { "capabilities": { "appType": "custom", "channelCapabilities": [ { "channelType": "custom", "customIntegration": { "customIntegrationType": "CustomChannelIntegration", "integrationNamespace": "", "conversationChannelDefinitionDevName": "" }, "messageTypeCapabilities": [ { "messageType": "StaticContentMessage", "formatTypeCapabilities": [ { "formatType": "Text", "capabilityFieldRestriction": [ { "fieldJsonPath": "$.staticContent.text", "restriction": { "fieldRestrictionType": "TypeRestriction", "type": "string" } }, { "fieldJsonPath": "$.staticContent.metadata", "restriction": { "fieldRestrictionType": "TypeRestriction", "type": "object" } } ] }, { "formatType": "Attachments", "capabilityFieldRestriction": [ { "fieldJsonPath": "$.staticContent.attachments", "restriction": { "fieldRestrictionType": "TypeRestriction", "type": "array" } } ] } ] }, { "messageType": "FormMessage", "formatTypeCapabilities": [ { "formatType": "Inputs", "capabilityFieldRestriction": [ { "fieldJsonPath": "$.form.inputs", "restriction": { "fieldRestrictionType": "TypeRestriction", "type": "array" } } ] } ] } ] } ] } } ``` ## Sample Bring Your Own Bot Register Capabilities API Payloads ### Register Bring Your Own Bot Capabilities For Bring Your Own Bot (BYOB), register the capabilities that the bot integration supports. Set `customIntegrationType` to `CustomBotIntegration` and use the `extConvParticipantIntegDefDevName` field (instead of `conversationChannelDefinitionDevName`) to identify the `ExtConvParticipantIntegDef` record. The BYOB flow typically registers `StaticContentMessage`, `ChoicesResponseMessage`, and `FormResponseMessage` capabilities. Progress indicators (`progressIndicatorTypeCapabilities`) aren’t supported for BYOB; omit this field from BYOB payloads. ```json { "capabilities": { "appType": "custom", "channelCapabilities": [ { "channelType": "custom", "customIntegration": { "customIntegrationType": "CustomBotIntegration", "integrationNamespace": "", "extConvParticipantIntegDefDevName": "" }, "messageTypeCapabilities": [ { "messageType": "StaticContentMessage", "formatTypeCapabilities": [ {} ] }, { "messageType": "ChoicesResponseMessage", "formatTypeCapabilities": [ { "formatType": "Selections" } ] }, { "messageType": "FormResponseMessage", "formatTypeCapabilities": [ { "formatType": "Result" } ] } ] } ] } } ```