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 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 <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.

Content-Type

Format: application/json
String. Standard header. Format of the request payload. Required for any request that includes a body.

OrgId

Format: <Salesforce Org ID>
String. Custom header. The Salesforce org. <Salesforce Org ID> is the 15-character Org ID of the Salesforce org. Required.

RequestId

Format: <UUID>
String. Custom header. Universally Unique Identifier (<UUID>) that references and tracks this request. Required.

AuthorizationContext

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.

AuthorizationContextType

Format: <AuthorizationContextType>
String. Custom header. Specifies the type of context for the request.

For Bring Your Own Channel for CCaaS, set <AuthorizationContextType> to ConversationChannelDefinition.
For Bring Your Own Channel for Messaging, set <AuthorizationContextType> to ConversationChannelDefinition.
For Bring Your Own Bot (BYOB), set <AuthorizationContextType> to ExternalConversationParticipant.

If not set, this header defaults to ConversationChannelDefinition.

Sample Header

1-H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \
2-H "content-type: application/json" \
3-H "OrgId: 00DSG000009SWby" \
4-H "AuthorizationContext: Partner1_ChannelDefinition1" \
5-H "AuthorizationContextType: ConversationChannelDefinition" \
6-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 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. 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.

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.

1{
2  "capabilities": {
3    "appType": "Custom",
4    "channelCapabilities": [
5      {
6        "channelType": "Custom",
7        "customIntegration": {
8          "customIntegrationType": "CustomChannelIntegration",
9          "integrationNamespace": "<OrgId/NameSpace>",
10          "conversationChannelDefinitionDevName": "<CCD_DevName1>"
11        },
12        "messageTypeCapabilities": [
13          {
14            "messageType": "StaticContentMessage",
15            "formatTypeCapabilities": [
16              {
17                "formatType": "Text"
18              }
19            ]
20          }
21        ]
22      },
23      {
24        "channelType": "Custom",
25        "customIntegration": {
26          "customIntegrationType": "CustomChannelIntegration",
27          "integrationNamespace": "<OrgId/NameSpace>",
28          "conversationChannelDefinitionDevName": "<CCD_DevName2>"
29        },
30        "messageTypeCapabilities": [
31          {
32            "messageType": "StaticContentMessage",
33            "formatTypeCapabilities": [
34              {
35                "formatType": "Text"
36              }
37            ]
38          }
39        ]
40      }
41    ]
42  }
43}

Register Multiple Message Types

You can register more than one message type at a time.

1{
2  "capabilities": {
3    "appType": "Custom",
4    "channelCapabilities": [
5      {
6        "channelType": "Custom",
7        "customIntegration": {
8          "customIntegrationType": "CustomChannelIntegration",
9          "integrationNamespace": "<OrgId/NameSpace>",
10          "conversationChannelDefinitionDevName": "<CCD_DevName>"
11        },
12        "messageTypeCapabilities": [
13          {
14            "messageType": "StaticContentMessage",
15            "formatTypeCapabilities": [
16              {
17                "formatType": "Text"
18              }
19            ]
20          },
21          {
22            "messageType": "ChoicesMessage",
23            "formatTypeCapabilities": [
24              {
25                "formatType": "Buttons"
26              }
27            ]
28          }
29        ]
30      }
31    ]
32  }
33}

Register Multiple Format Types

You can register more than one format type at the same time.

1{
2  "capabilities": {
3    "appType": "Custom",
4    "channelCapabilities": [
5      {
6        "channelType": "Custom",
7        "customIntegration": {
8          "customIntegrationType": "CustomChannelIntegration",
9          "integrationNamespace": "<OrgId/NameSpace>",
10          "conversationChannelDefinitionDevName": "<CCD_DevName>"
11        },
12        "messageTypeCapabilities": [
13          {
14            "messageType": "StaticContentMessage",
15            "formatTypeCapabilities": [
16              {
17                "formatType": "Text"
18              },
19              {
20                "formatType": "RichLink"
21              }
22            ]
23          }
24        ]
25      }
26    ]
27  }
28}

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.

1{
2  "capabilities": {
3    "appType": "Custom",
4    "channelCapabilities": [
5      {
6        "channelType": "Custom",
7        "customIntegration": {
8          "customIntegrationType": "CustomChannelIntegration",
9          "integrationNamespace": "<OrgId/NameSpace>",
10          "conversationChannelDefinitionDevName": "<CCD_DevName>"
11        },
12        "messageTypeCapabilities": [
13          {
14            "messageType": "StaticContentMessage",
15            "formatTypeCapabilities": [
16              {
17                "formatType": "Text"
18              }
19            ]
20          }
21        ]
22      }
23    ]
24  }
25}

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.

1{
2 "capabilities": {
3   "appType" : "Custom",
4   "channelCapabilities" : [{
5     "channelType" : "Custom",
6     "customIntegration": {
7       "customIntegrationType": "CustomChannelIntegration",
8       "integrationNamespace": "<OrgId/NameSpace>",
9       "conversationChannelDefinitionDevName": "<CCD_DevName>"
10   },
11     "messageTypeCapabilities": [{
12       "messageType": "StaticContentMessage",
13       "formatTypeCapabilities": [{
14         "formatType": "Text"
15       }]
16     }],
17     "progressIndicatorTypeCapabilities": [{
18        "progressIndicatorType": "ProgressUpdateIndicator",
19        "formatTypeCapabilities": [{
20          "formatType": "Text"
21        }]
22      }]
23   }]
24  }
25}

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.

1{
2  "capabilities": {
3    "appType" : "custom",
4    "channelCapabilities" : [{
5      "channelType" : "custom",
6      "customIntegration": {
7        "customIntegrationType": "CustomChannelIntegration",
8        "integrationNamespace": "00Dxx0000006GuB",
9        "conversationChannelDefinitionDevName": "CCaaSDot_ChannelDefinition1"
10      },
11      "messageTypeCapabilities": [{
12        "messageType": "StaticContentMessage",
13        "formatTypeCapabilities": [{
14          "formatType": "Text",
15          "capabilityFieldRestriction": [{
16            "fieldJsonPath": "$.staticContent.text",
17            "restriction":{
18              "fieldRestrictionType": "ArrayRestriction",
19              "maxItems": 9
20            }
21          }]
22        }]
23      }]
24    }]
25  }
26}

1{
2 "capabilities": {
3    "appType": "custom",
4    "channelCapabilities": [{
5      "channelType": "custom",
6      "customIntegration": {
7        "customIntegrationType": "CustomChannelIntegration",
8        "integrationNamespace": "sdb6byo",
9        "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" },
10        "messageTypeCapabilities": [{
11          "messageType": "StaticContentMessage",
12          "formatTypeCapabilities": [{
13            "formatType": "Text",
14            "capabilityFieldRestriction": [{
15              "fieldJsonPath": "$.staticContent.text",
16              "restriction": {
17                "fieldRestrictionType": "StringFieldRestriction",
18                "encoding": "UTF8",
19                "maxLength": 10
20              }
21            }]
22          }]
23       }]
24    }]
25  }
26}

1{
2 "capabilities": {
3    "appType": "custom",
4    "channelCapabilities": [ {
5      "channelType": "custom",
6      "customIntegration": {
7        "customIntegrationType": "CustomChannelIntegration",
8        "integrationNamespace": "sdb6byo",
9        "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" },
10      "messageTypeCapabilities": [{
11        "messageType": "StaticContentMessage",
12        "formatTypeCapabilities": [{
13          "formatType": "Attachments",
14          "capabilityFieldRestriction": [{
15            "fieldJsonPath": "$.staticContent.attachments.mimeType",
16            "restriction": {
17              "fieldRestrictionType": "MimeTypeRestriction",
18              "mimeType": "image/png"
19            }
20         }]
21       }]
22     }]
23  }]
24 }
25}

1{
2 "capabilities": {
3    "appType": "custom",
4    "channelCapabilities": [ {
5      "channelType": "custom",
6      "customIntegration": {
7        "customIntegrationType": "CustomChannelIntegration",
8        "integrationNamespace": "sdb6byo",
9        "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" },
10      "messageTypeCapabilities": [{
11        "messageType": "StaticContentMessage",
12        "formatTypeCapabilities": [{
13          "formatType": "Attachments",
14          "capabilityFieldRestriction": [{
15            "fieldJsonPath": "$.staticContent.attachments",
16            "restriction": {
17              "fieldRestrictionType": "FileSizeRestriction",
18              "maxSizeInKb": 1000
19            }
20         }]
21       }]
22     }]
23   }]
24 }
25}

1{
2 "capabilities": {
3    "appType": "custom",
4    "channelCapabilities": [ {
5      "channelType": "custom",
6      "customIntegration": {
7        "customIntegrationType": "CustomChannelIntegration",
8        "integrationNamespace": "sdb6byo",
9        "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" },
10      "messageTypeCapabilities": [{
11        "messageType": "StaticContentMessage",
12        "formatTypeCapabilities": [{
13          "formatType": "Attachments",
14          "capabilityFieldRestriction": [{
15            "fieldJsonPath": "$.staticContent.attachments",
16            "restriction": {
17              "fieldRestrictionType": "DimensionRestriction",
18              "dimensionType": "PIXEL",
19              "x": 0.1,
20              "y": 0.1
21            }
22          }]
23        }]
24      }]
25    }]
26  }
27}

1{
2 "capabilities": {
3    "appType": "custom",
4    "channelCapabilities": [{
5      "channelType": "custom",
6      "customIntegration": {
7        "customIntegrationType": "CustomChannelIntegration",
8        "integrationNamespace": "sdb6byo",
9        "conversationChannelDefinitionDevName": "BYOCC_Channel_Definition" },
10      "messageTypeCapabilities": [{
11        "messageType": "StaticContentMessage",
12        "formatTypeCapabilities": [{
13          "formatType": "RichLink",
14          "capabilityFieldRestriction": [{
15            "fieldJsonPath": "$.staticContent.image",
16            "restriction": {
17              "fieldRestrictionType": "RequiredFieldRestriction",
18              "fieldRequired": false
19            }
20          }]
21        }]
22      }]
23    }]
24  }
25}

1{
2  "capabilities": {
3    "appType": "custom",
4    "channelCapabilities": [
5      {
6        "channelType": "custom",
7        "customIntegration": {
8          "customIntegrationType": "CustomChannelIntegration",
9          "integrationNamespace": "<orgId | developer namespace>",
10          "conversationChannelDefinitionDevName": "<ConversationChannelDefinition developer Name>"
11        },
12        "messageTypeCapabilities": [
13          {
14            "messageType": "StaticContentMessage",
15            "formatTypeCapabilities": [
16              {
17                "formatType": "Text",
18                "capabilityFieldRestriction": [
19                  {
20                    "fieldJsonPath": "$.staticContent.text",
21                    "restriction": {
22                      "fieldRestrictionType": "TypeRestriction",
23                      "type": "string"
24                    }
25                  },
26                  {
27                    "fieldJsonPath": "$.staticContent.metadata",
28                    "restriction": {
29                      "fieldRestrictionType": "TypeRestriction",
30                      "type": "object"
31                    }
32                  }
33                ]
34              },
35              {
36                "formatType": "Attachments",
37                "capabilityFieldRestriction": [
38                  {
39                    "fieldJsonPath": "$.staticContent.attachments",
40                    "restriction": {
41                      "fieldRestrictionType": "TypeRestriction",
42                      "type": "array"
43                    }
44                  }
45                ]
46              }
47            ]
48          },
49          {
50            "messageType": "FormMessage",
51            "formatTypeCapabilities": [
52              {
53                "formatType": "Inputs",
54                "capabilityFieldRestriction": [
55                  {
56                    "fieldJsonPath": "$.form.inputs",
57                    "restriction": {
58                      "fieldRestrictionType": "TypeRestriction",
59                      "type": "array"
60                    }
61                  }
62                ]
63              }
64            ]
65          }
66        ]
67      }
68    ]
69  }
70}

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.

1{
2  "capabilities": {
3    "appType": "custom",
4    "channelCapabilities": [
5      {
6        "channelType": "custom",
7        "customIntegration": {
8          "customIntegrationType": "CustomBotIntegration",
9          "integrationNamespace": "<orgId | developer namespace>",
10          "extConvParticipantIntegDefDevName": "<ExtConvParticipantIntegDef developer Name>"
11        },
12        "messageTypeCapabilities": [
13          {
14            "messageType": "StaticContentMessage",
15            "formatTypeCapabilities": [
16              {}
17            ]
18          },
19          {
20            "messageType": "ChoicesResponseMessage",
21            "formatTypeCapabilities": [
22              { "formatType": "Selections" }
23            ]
24          },
25          {
26            "messageType": "FormResponseMessage",
27            "formatTypeCapabilities": [
28              { "formatType": "Result" }
29            ]
30          }
31        ]
32      }
33    ]
34  }
35}

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!