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

-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

Message Types

Format Types

This table lists all supported message types and their possible format types.

Field Restriction Types

For sample field restriction payloads, see Register a Capability with a Field Restriction.

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.

{
  "capabilities": {
    "appType": "Custom",
    "channelCapabilities": [
      {
        "channelType": "Custom",
        "customIntegration": {
          "customIntegrationType": "CustomChannelIntegration",
          "integrationNamespace": "<OrgId/NameSpace>",
          "conversationChannelDefinitionDevName": "<CCD_DevName1>"
        },
        "messageTypeCapabilities": [
          {
            "messageType": "StaticContentMessage",
            "formatTypeCapabilities": [
              {
                "formatType": "Text"
              }
            ]
          }
        ]
      },
      {
        "channelType": "Custom",
        "customIntegration": {
          "customIntegrationType": "CustomChannelIntegration",
          "integrationNamespace": "<OrgId/NameSpace>",
          "conversationChannelDefinitionDevName": "<CCD_DevName2>"
        },
        "messageTypeCapabilities": [
          {
            "messageType": "StaticContentMessage",
            "formatTypeCapabilities": [
              {
                "formatType": "Text"
              }
            ]
          }
        ]
      }
    ]
  }
}

Register Multiple Message Types

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

{
  "capabilities": {
    "appType": "Custom",
    "channelCapabilities": [
      {
        "channelType": "Custom",
        "customIntegration": {
          "customIntegrationType": "CustomChannelIntegration",
          "integrationNamespace": "<OrgId/NameSpace>",
          "conversationChannelDefinitionDevName": "<CCD_DevName>"
        },
        "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.

{
  "capabilities": {
    "appType": "Custom",
    "channelCapabilities": [
      {
        "channelType": "Custom",
        "customIntegration": {
          "customIntegrationType": "CustomChannelIntegration",
          "integrationNamespace": "<OrgId/NameSpace>",
          "conversationChannelDefinitionDevName": "<CCD_DevName>"
        },
        "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.

{
  "capabilities": {
    "appType": "Custom",
    "channelCapabilities": [
      {
        "channelType": "Custom",
        "customIntegration": {
          "customIntegrationType": "CustomChannelIntegration",
          "integrationNamespace": "<OrgId/NameSpace>",
          "conversationChannelDefinitionDevName": "<CCD_DevName>"
        },
        "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.

{
 "capabilities": {
   "appType" : "Custom",
   "channelCapabilities" : [{
     "channelType" : "Custom",
     "customIntegration": {
       "customIntegrationType": "CustomChannelIntegration",
       "integrationNamespace": "<OrgId/NameSpace>",
       "conversationChannelDefinitionDevName": "<CCD_DevName>"
   },
     "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.

{
  "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
            }
          }]
        }]
      }]
    }]
  }
}

{
 "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
              }
            }]
          }]
       }]
    }]
  }
}

{
 "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"
            }
         }]
       }]
     }]
  }]
 }
}

{
 "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
            }
         }]
       }]
     }]
   }]
 }
}

{
 "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
            }
          }]
        }]
      }]
    }]
  }
}

{
 "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
            }
          }]
        }]
      }]
    }]
  }
}

{
  "capabilities": {
    "appType": "custom",
    "channelCapabilities": [
      {
        "channelType": "custom",
        "customIntegration": {
          "customIntegrationType": "CustomChannelIntegration",
          "integrationNamespace": "<orgId | developer namespace>",
          "conversationChannelDefinitionDevName": "<ConversationChannelDefinition developer Name>"
        },
        "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.

{
  "capabilities": {
    "appType": "custom",
    "channelCapabilities": [
      {
        "channelType": "custom",
        "customIntegration": {
          "customIntegrationType": "CustomBotIntegration",
          "integrationNamespace": "<orgId | developer namespace>",
          "extConvParticipantIntegDefDevName": "<ExtConvParticipantIntegDef developer Name>"
        },
        "messageTypeCapabilities": [
          {
            "messageType": "StaticContentMessage",
            "formatTypeCapabilities": [
              {}
            ]
          },
          {
            "messageType": "ChoicesResponseMessage",
            "formatTypeCapabilities": [
              { "formatType": "Selections" }
            ]
          },
          {
            "messageType": "FormResponseMessage",
            "formatTypeCapabilities": [
              { "formatType": "Result" }
            ]
          }
        ]
      }
    ]
  }
}