Enables you to send messages in a conversation through the third-party chatbot, including StaticContentMessage, ChoiceMessage, FormMessage, and typing indicators.
This API applies to the following product:
- Bring Your Own Bot (BYOB)
note: Support for a message type or format type in Bring Your Own Bot doesn't guarantee that a given channel supports it. A message is delivered only if the channel it's sent over also supports that message type or format type. For example, if a channel doesn't support carousels, a ChoicesMessage with the Carousel format type doesn't send on that channel. Check your channel's capabilities and messaging component formats before you send rich message types.
For authentication details, see Generate an Access Token.
Sample payloads are provided for text messages, choice messages with buttons, choice messages with a carousel, messages in a form, typing started indicator, and typing stopped indicator.
URI
v1/conversationEntry
HTTP Method
POST
Headers
Authorization
Format: Bearer <Salesforce Access Token>
String. Standard header. The authorization token, where <token> is the JSON Web Token (JWT). Required.
Content-Type
Format: application/json
String. Standard header. The format of the request body. Valid format is application/json. Required.
OrgId
Format: <Salesforce Org ID>
String. Standard header. The 15-character Org ID of the Salesforce org. Required.
AuthorizationContext
Format: <External Conversation Participant Integration Definition developer name>
String. Standard header. The ExtConvParticipantIntegDef developer name in the format {prefix}_{ExtConvParticipantIntegDef}. The prefix must match the developer name prefix of the corresponding ExternalClientApp. For example, Partnerapp_ExtConvParticipantIntegDef. Required.
AuthorizationContextType
Format: ExternalConversationParticipant
String. Standard header. Set this value to ExternalConversationParticipant. Required.
RequestId
Format: <GUID>
String. Standard header. A globally unique ID (GUID). Required.
Sample Header
-H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \
-H "content-type: application/json" \
-H "OrgId: 00DSG000009SWby" \
-H "AuthorizationContext: ExtConvParticipantIntegDef" \
-H "AuthorizationContextType: ExternalConversationParticipant" \
-H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \
Parameters
| Property Name | Type | Description | Required |
|---|---|---|---|
| conversationIdentifier | string | A unique identifier generated for the conversation. | Yes |
| sender | object | An object representing a messaging participant. The participant can be a rep or an end user. | Yes |
| sender.appType | string | The app type used for the conversation. Set this value to custom to represent a custom bot. | Yes |
| sender.subject | string | The Salesforce record ID of the external bot that you created as part of the setup. | Yes |
| sender.role | string | The role within the conversation. Set this value to chatbot. | Yes |
| conversationEntries | object | A list of conversation entries sent via a bot to Conversation. Each conversation entry is a message with the text format type. Currently, send exactly one entry per request (min: 1, max: 1). |
Yes |
| conversationEntries.clientTimestamp | timestamp | This indicates the timestamp when the message was generated by the bot. | Yes |
| conversationEntries.entryPayload | object | The content of the conversation entry. | Yes |
| entryPayload.id | string | A unique ID for the interaction. Maximum size is 36 characters. This value must match the entryPayload.abstractMessage.id value in this payload. |
Yes |
| entryPayload.entryType | string | The type of conversation entry. Set to Message for content messages, or TypingStartedIndicator / TypingStoppedIndicator for typing indicators. | Yes |
| entryPayload.messageReason | string | The reason for the message. | No |
| entryPayload.abstractMessage | object | The message details. For more information on abstractMessage, see Abstract Message. Required when entryType is Message. |
Yes |
| abstractMessage.id | string | A unique ID for the interaction. This value must match the entryPayload.id value in this payload. |
Yes |
| abstractMessage.messageType | string | The message type for the interaction. Set this value to StaticContentMessage, ChoicesMessage, or FormMessage. | Yes |
| abstractMessage.staticContent | object | The details for the static content. For messages, set formatType to Text, and set text to the message content. Required when messageType is StaticContentMessage. |
Yes |
| staticContent.formatType | text | The type of static content. | Yes |
| staticContent.text | text | The message as part of the conversation. Required when formatType is Text. |
Yes |
| abstractMessage.inReplyToMessageId | string | The ID of the message this message is in reply to. | No |
| abstractMessage.customHandlingType | string | A custom handling type for the message. | No |
| abstractMessage.references | array | A list of references (for example, records or assets) associated with the message. See the sample payloads for the structure. | No |
| abstractMessage.contentCategory | string | A category that classifies the content of the message. | No |
Bring Your Own Bot Examples
Text Message Payload
Request
{
"conversationIdentifier": "452572de-6387-4117-85e0-453f49f6b220",
"sender": {
"subject": "1JZSG0000003s2H",
"role": "Chatbot",
"appType": "custom"
},
"conversationEntries": [
{
"clientTimestamp": 1741763707000,
"entryPayload": {
"id": "123456",
"entryType": "Message",
"abstractMessage": {
"id": "123456",
"messageType": "StaticContentMessage",
"staticContent": {
"formatType": "Text",
"text": "Hello, This message is from Chatbot."
}
}
}
}
]
}
Response
{
"success": true
}
Choices Message with Buttons Payload
Request
{
"conversationIdentifier": "452572de-6387-4117-85e0-453f49f6b220",
"sender": {
"subject": "1JZSG0000003s2H",
"role": "Chatbot",
"appType": "custom"
},
"conversationEntries": [
{
"clientTimestamp": 1741763707000,
"entryPayload": {
"id": "b2c88e0e-11af-pq54-9e9f-123b9319b3af",
"entryType": "Message",
"abstractMessage": {
"id": "b2c88e0e-11af-pq54-9e9f-123b9319b3af",
"messageType": "ChoicesMessage",
"choices": {
"formatType": "Buttons",
"optionItems": [
{
"optionIdentifier": "option1",
"itemType": "TitleOptionItem",
"titleItem": {
"itemType": "TitleItem",
"title": "Apple"
}
},
{
"optionIdentifier": "option2",
"itemType": "TitleOptionItem",
"titleItem": {
"itemType": "TitleItem",
"title": "Samsung"
}
}
],
"text": "Mobile Brand Selection"
}
}
}
}
]
}
Response
{
"success": true
}
Choices Message with Carousel Payload
Request
{
"conversationIdentifier": "3f5e2d4e-e41c-424a-90db-df70c8153a67",
"sender": {
"subject": "ChatbotId",
"role": "Chatbot",
"appType": "custom"
},
"conversationEntries": [
{
"clientTimestamp": 1741763707000,
"entryPayload": {
"entryType": "Message",
"id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
"abstractMessage": {
"messageType": "ChoicesMessage",
"inReplyToMessageId": null,
"id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
"references": [
{ "recordId": "03SSB0000003syL", "id": "7ee9e8ae-ba1d-4234-8678-74a772e18e8b" },
{ "recordId": "03SSB0000003t1Z", "id": "d12b7209-dc50-4d9e-9a37-dd08bf0f1851" },
{ "recordId": "03SSB0000003szx", "id": "1842daf0-c7cf-472c-9886-e9256e35ffd4" }
],
"choices": {
"formatType": "Carousel",
"items": [
{
"titleItem": {
"itemType": "TitleImageItem",
"secondarySubTitle": null,
"title": "What is your choice?",
"subTitle": "LG TV",
"tertiarySubTitle": null,
"referenceId": null,
"imageSubTitle": null,
"imageId": "185f220d-900e-459d-9a59-e3c3cbc219d0"
},
"interactionItems": [
{
"itemType": "TitleOptionItem",
"titleItem": {
"itemType": "TitleItem",
"secondarySubTitle": null,
"title": "$Constants.Options.ListItem.SubTitle",
"subTitle": null,
"tertiarySubTitle": null,
"referenceId": null
},
"optionIdentifier": "9dde2976-1f19-a290-6bce-a70ff7c31b5f",
"optionId": null
}
]
},
{
"titleItem": {
"itemType": "TitleImageItem",
"secondarySubTitle": null,
"title": "What is your choice?",
"subTitle": "Sony",
"tertiarySubTitle": null,
"referenceId": null,
"imageSubTitle": null,
"imageId": "d07c5a88-1e7c-43f2-b12b-cd8a30f85ba7"
},
"interactionItems": [
{
"itemType": "TitleOptionItem",
"titleItem": {
"itemType": "TitleItem",
"secondarySubTitle": null,
"title": "$Constants.Options.ListItem.SubTitle",
"subTitle": null,
"tertiarySubTitle": null,
"referenceId": null
},
"optionIdentifier": "3fb75da3-cfe9-d203-d6f4-d8c370391daa",
"optionId": null
}
]
},
{
"titleItem": {
"itemType": "TitleImageItem",
"secondarySubTitle": null,
"title": "What is your choice?",
"subTitle": "Apple",
"tertiarySubTitle": null,
"referenceId": null,
"imageSubTitle": null,
"imageId": "fc9cb6dc-c933-4def-8ac3-69786b9cacf9"
},
"interactionItems": [
{
"itemType": "TitleOptionItem",
"titleItem": {
"itemType": "TitleItem",
"secondarySubTitle": null,
"title": "$Constants.Options.ListItem.SubTitle",
"subTitle": null,
"tertiarySubTitle": null,
"referenceId": null
},
"optionIdentifier": "2d8cb27f-c8cf-4f82-7f5a-743cc6c7acc6",
"optionId": null
}
]
}
],
"images": [
{
"assetType": "ImageAsset",
"description": null,
"id": "d07c5a88-1e7c-43f2-b12b-cd8a30f85ba7",
"mimeType": "image/png",
"assetUrl": "https://inapporg3.test1.file.pc-rnd.force.com/file-asset-public/Screenshot_20230412_at_113759_AM?oid=00DSB0000003a8b&v=1",
"referenceId": "1842daf0-c7cf-472c-9886-e9256e35ffd4"
},
{
"assetType": "ImageAsset",
"description": null,
"id": "fc9cb6dc-c933-4def-8ac3-69786b9cacf9",
"mimeType": "image/png",
"assetUrl": "https://inapporg3.test1.file.pc-rnd.force.com/file-asset-public/Screenshot_20230413_at_121009_PM?oid=00DSB0000003a8b&v=1",
"referenceId": "d12b7209-dc50-4d9e-9a37-dd08bf0f1851"
},
{
"assetType": "ImageAsset",
"description": null,
"id": "185f220d-900e-459d-9a59-e3c3cbc219d0",
"mimeType": "image/png",
"assetUrl": "https://inapporg3.test1.file.pc-rnd.force.com/file-asset-public/Screenshot_20230412_at_32544_PM?oid=00DSB0000003a8b&v=1",
"referenceId": "7ee9e8ae-ba1d-4234-8678-74a772e18e8b"
}
]
}
},
"messageReason": null
}
}
]
}
Response
{
"success": true
}
Form Message Payload
Request
{
"conversationIdentifier": "3ce68680-5484-4e18-83e4-f23ae931910c",
"sender": {
"subject": "1JZSG0000003s2H",
"role": "Chatbot",
"appType": "custom"
},
"conversationEntries": [
{
"clientTimestamp": 1741763707000,
"entryPayload": {
"id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
"entryType": "Message",
"abstractMessage": {
"messageType": "FormMessage",
"inReplyToMessageId": null,
"id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
"references": null,
"form": {
"formatType": "MessageDefinition",
"parameters": null,
"messageDefinitionNameOrId": "1mdSG000000Zex3YAC",
"targetLocale": null
}
}
}
}
]
}
Response
{
"success": true
}
Typing Started Indicator
Request
{
"conversationIdentifier": "7d3e1c2a-9b8a-4e10-9f4d-2b6c1a7e3f59",
"sender": {
"appType": "custom",
"subject": "1JZSG0000003s2H",
"role": "Chatbot"
},
"conversationEntries": [
{
"clientTimestamp": 1766050470000,
"entryPayload": {
"entryType": "TypingStartedIndicator",
"id": "f7904eb6-5352-4c5e-adf6-5f100572cf6d",
"timestamp": 1766050470000
}
}
]
}
Response
{
"success": true
}
Typing Stopped Indicator
Request
{
"conversationIdentifier": "7d3e1c2a-9b8a-4e10-9f4d-2b6c1a7e3f59",
"sender": {
"appType": "custom",
"subject": "1JZSG0000003s2H",
"role": "Chatbot"
},
"conversationEntries": [
{
"clientTimestamp": 1766050470000,
"entryPayload": {
"entryType": "TypingStoppedIndicator",
"id": "f7904eb6-5352-4c5e-adf6-5f100572cf6d",
"timestamp": 1766050470000
}
}
]
}
Response
{
"success": true
}