Send a Message Through a Chatbot

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)

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 

 
1-H $'Authorization: Bearer 00DSG000009SWby!...LN8XxeRIxGe' \
2-H "content-type: application/json" \
3-H "OrgId: 00DSG000009SWby" \
4-H "AuthorizationContext: ExtConvParticipantIntegDef" \
5-H "AuthorizationContextType: ExternalConversationParticipant" \
6-H "RequestId: a1b23c45-c06a-4784-c96c-cb95d3321bda" \

Parameters 
Property NameTypeDescriptionRequired
conversationIdentifierstringA unique identifier generated for the conversation.Yes
senderobjectAn object representing a messaging participant. The participant can be a rep or an end user.Yes
sender.appTypestringThe app type used for the conversation. Set this value to custom to represent a custom bot.Yes
sender.subjectstringThe Salesforce record ID of the external bot that you created as part of the setup.Yes
sender.rolestringThe role within the conversation. Set this value to chatbot.Yes
conversationEntriesobjectA 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.clientTimestamptimestampThis indicates the timestamp when the message was generated by the bot.Yes
conversationEntries.entryPayloadobjectThe content of the conversation entry.Yes
entryPayload.idstringA unique ID for the interaction. Maximum size is 36 characters. This value must match the entryPayload.abstractMessage.id value in this payload.Yes
entryPayload.entryTypestringThe type of conversation entry. Set to Message for content messages, or TypingStartedIndicator / TypingStoppedIndicator for typing indicators.Yes
entryPayload.messageReasonstringThe reason for the message.No
entryPayload.abstractMessageobjectThe message details. For more information on abstractMessage, see Abstract Message. Required when entryType is Message.Yes
abstractMessage.idstringA unique ID for the interaction. This value must match the entryPayload.id value in this payload.Yes
abstractMessage.messageTypestringThe message type for the interaction. Set this value to StaticContentMessage, ChoicesMessage, or FormMessage.Yes
abstractMessage.staticContentobjectThe 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.formatTypetextThe type of static content.Yes
staticContent.texttextThe message as part of the conversation. Required when formatType is Text.Yes
abstractMessage.inReplyToMessageIdstringThe ID of the message this message is in reply to.No
abstractMessage.customHandlingTypestringA custom handling type for the message.No
abstractMessage.referencesarrayA list of references (for example, records or assets) associated with the message. See the sample payloads for the structure.No
abstractMessage.contentCategorystringA category that classifies the content of the message.No

Bring Your Own Bot Examples 

Text Message Payload 

Request 
Sample Text Message Payload
1{
2  "conversationIdentifier": "452572de-6387-4117-85e0-453f49f6b220",
3  "sender": {
4    "subject": "1JZSG0000003s2H",
5    "role": "Chatbot",
6    "appType": "custom"
7  },
8  "conversationEntries": [
9    {
10      "clientTimestamp": 1741763707000,
11      "entryPayload": {
12        "id": "123456",
13        "entryType": "Message",
14        "abstractMessage": {
15          "id": "123456",
16          "messageType": "StaticContentMessage",
17          "staticContent": {
18            "formatType": "Text",
19            "text": "Hello, This message is from Chatbot."
20          }
21        }
22      }
23    }
24  ]
25}

Response 
202 Accepted
1{
2  "success": true
3}

Choices Message with Buttons Payload 

Request 
Sample Choices Message with Buttons Payload
1{
2  "conversationIdentifier": "452572de-6387-4117-85e0-453f49f6b220",
3  "sender": {
4    "subject": "1JZSG0000003s2H",
5    "role": "Chatbot",
6    "appType": "custom"
7  },
8  "conversationEntries": [
9    {
10      "clientTimestamp": 1741763707000,
11      "entryPayload": {
12        "id": "b2c88e0e-11af-pq54-9e9f-123b9319b3af",
13        "entryType": "Message",
14        "abstractMessage": {
15          "id": "b2c88e0e-11af-pq54-9e9f-123b9319b3af",
16          "messageType": "ChoicesMessage",
17          "choices": {
18            "formatType": "Buttons",
19            "optionItems": [
20              {
21                "optionIdentifier": "option1",
22                "itemType": "TitleOptionItem",
23                "titleItem": {
24                  "itemType": "TitleItem",
25                  "title": "Apple"
26                }
27              },
28              {
29                "optionIdentifier": "option2",
30                "itemType": "TitleOptionItem",
31                "titleItem": {
32                  "itemType": "TitleItem",
33                  "title": "Samsung"
34                }
35              }
36            ],
37            "text": "Mobile Brand Selection"
38          }
39        }
40      }
41    }
42  ]
43}

Response 
202 Accepted
1{
2  "success": true
3}

Choices Message with Carousel Payload 

Request 
Sample Choices Message with Carousel Payload
1{
2  "conversationIdentifier": "3f5e2d4e-e41c-424a-90db-df70c8153a67",
3  "sender": {
4    "subject": "ChatbotId",
5    "role": "Chatbot",
6    "appType": "custom"
7  },
8  "conversationEntries": [
9    {
10      "clientTimestamp": 1741763707000,
11      "entryPayload": {
12        "entryType": "Message",
13        "id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
14        "abstractMessage": {
15          "messageType": "ChoicesMessage",
16          "inReplyToMessageId": null,
17          "id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
18          "references": [
19            { "recordId": "03SSB0000003syL", "id": "7ee9e8ae-ba1d-4234-8678-74a772e18e8b" },
20            { "recordId": "03SSB0000003t1Z", "id": "d12b7209-dc50-4d9e-9a37-dd08bf0f1851" },
21            { "recordId": "03SSB0000003szx", "id": "1842daf0-c7cf-472c-9886-e9256e35ffd4" }
22          ],
23          "choices": {
24            "formatType": "Carousel",
25            "items": [
26              {
27                "titleItem": {
28                  "itemType": "TitleImageItem",
29                  "secondarySubTitle": null,
30                  "title": "What is your choice?",
31                  "subTitle": "LG TV",
32                  "tertiarySubTitle": null,
33                  "referenceId": null,
34                  "imageSubTitle": null,
35                  "imageId": "185f220d-900e-459d-9a59-e3c3cbc219d0"
36                },
37                "interactionItems": [
38                  {
39                    "itemType": "TitleOptionItem",
40                    "titleItem": {
41                      "itemType": "TitleItem",
42                      "secondarySubTitle": null,
43                      "title": "$Constants.Options.ListItem.SubTitle",
44                      "subTitle": null,
45                      "tertiarySubTitle": null,
46                      "referenceId": null
47                    },
48                    "optionIdentifier": "9dde2976-1f19-a290-6bce-a70ff7c31b5f",
49                    "optionId": null
50                  }
51                ]
52              },
53              {
54                "titleItem": {
55                  "itemType": "TitleImageItem",
56                  "secondarySubTitle": null,
57                  "title": "What is your choice?",
58                  "subTitle": "Sony",
59                  "tertiarySubTitle": null,
60                  "referenceId": null,
61                  "imageSubTitle": null,
62                  "imageId": "d07c5a88-1e7c-43f2-b12b-cd8a30f85ba7"
63                },
64                "interactionItems": [
65                  {
66                    "itemType": "TitleOptionItem",
67                    "titleItem": {
68                      "itemType": "TitleItem",
69                      "secondarySubTitle": null,
70                      "title": "$Constants.Options.ListItem.SubTitle",
71                      "subTitle": null,
72                      "tertiarySubTitle": null,
73                      "referenceId": null
74                    },
75                    "optionIdentifier": "3fb75da3-cfe9-d203-d6f4-d8c370391daa",
76                    "optionId": null
77                  }
78                ]
79              },
80              {
81                "titleItem": {
82                  "itemType": "TitleImageItem",
83                  "secondarySubTitle": null,
84                  "title": "What is your choice?",
85                  "subTitle": "Apple",
86                  "tertiarySubTitle": null,
87                  "referenceId": null,
88                  "imageSubTitle": null,
89                  "imageId": "fc9cb6dc-c933-4def-8ac3-69786b9cacf9"
90                },
91                "interactionItems": [
92                  {
93                    "itemType": "TitleOptionItem",
94                    "titleItem": {
95                      "itemType": "TitleItem",
96                      "secondarySubTitle": null,
97                      "title": "$Constants.Options.ListItem.SubTitle",
98                      "subTitle": null,
99                      "tertiarySubTitle": null,
100                      "referenceId": null
101                    },
102                    "optionIdentifier": "2d8cb27f-c8cf-4f82-7f5a-743cc6c7acc6",
103                    "optionId": null
104                  }
105                ]
106              }
107            ],
108            "images": [
109              {
110                "assetType": "ImageAsset",
111                "description": null,
112                "id": "d07c5a88-1e7c-43f2-b12b-cd8a30f85ba7",
113                "mimeType": "image/png",
114                "assetUrl": "https://inapporg3.test1.file.pc-rnd.force.com/file-asset-public/Screenshot_20230412_at_113759_AM?oid=00DSB0000003a8b&v=1",
115                "referenceId": "1842daf0-c7cf-472c-9886-e9256e35ffd4"
116              },
117              {
118                "assetType": "ImageAsset",
119                "description": null,
120                "id": "fc9cb6dc-c933-4def-8ac3-69786b9cacf9",
121                "mimeType": "image/png",
122                "assetUrl": "https://inapporg3.test1.file.pc-rnd.force.com/file-asset-public/Screenshot_20230413_at_121009_PM?oid=00DSB0000003a8b&v=1",
123                "referenceId": "d12b7209-dc50-4d9e-9a37-dd08bf0f1851"
124              },
125              {
126                "assetType": "ImageAsset",
127                "description": null,
128                "id": "185f220d-900e-459d-9a59-e3c3cbc219d0",
129                "mimeType": "image/png",
130                "assetUrl": "https://inapporg3.test1.file.pc-rnd.force.com/file-asset-public/Screenshot_20230412_at_32544_PM?oid=00DSB0000003a8b&v=1",
131                "referenceId": "7ee9e8ae-ba1d-4234-8678-74a772e18e8b"
132              }
133            ]
134          }
135        },
136        "messageReason": null
137      }
138    }
139  ]
140}

Response 
202 Accepted
1{
2  "success": true
3}

Form Message Payload 

Request 
Sample Form Message Payload
1{
2  "conversationIdentifier": "3ce68680-5484-4e18-83e4-f23ae931910c",
3  "sender": {
4    "subject": "1JZSG0000003s2H",
5    "role": "Chatbot",
6    "appType": "custom"
7  },
8  "conversationEntries": [
9    {
10      "clientTimestamp": 1741763707000,
11      "entryPayload": {
12        "id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
13        "entryType": "Message",
14        "abstractMessage": {
15          "messageType": "FormMessage",
16          "inReplyToMessageId": null,
17          "id": "0f0a7d26-c353-4894-947d-8e5b2172700f",
18          "references": null,
19          "form": {
20            "formatType": "MessageDefinition",
21            "parameters": null,
22            "messageDefinitionNameOrId": "1mdSG000000Zex3YAC",
23            "targetLocale": null
24          }
25        }
26      }
27    }
28  ]
29}

Response 
202 Accepted
1{
2  "success": true
3}

Typing Started Indicator 

Request 
Sample Typing Started Indicator Payload
1{
2  "conversationIdentifier": "7d3e1c2a-9b8a-4e10-9f4d-2b6c1a7e3f59",
3  "sender": {
4    "appType": "custom",
5    "subject": "1JZSG0000003s2H",
6    "role": "Chatbot"
7  },
8  "conversationEntries": [
9    {
10      "clientTimestamp": 1766050470000,
11      "entryPayload": {
12        "entryType": "TypingStartedIndicator",
13        "id": "f7904eb6-5352-4c5e-adf6-5f100572cf6d",
14        "timestamp": 1766050470000
15      }
16    }
17  ]
18}

Response 
202 Accepted
1{
2  "success": true
3}

Typing Stopped Indicator 

Request 
Sample Typing Stopped Indicator Payload
1{
2  "conversationIdentifier": "7d3e1c2a-9b8a-4e10-9f4d-2b6c1a7e3f59",
3  "sender": {
4    "appType": "custom",
5    "subject": "1JZSG0000003s2H",
6    "role": "Chatbot"
7  },
8  "conversationEntries": [
9    {
10      "clientTimestamp": 1766050470000,
11      "entryPayload": {
12        "entryType": "TypingStoppedIndicator",
13        "id": "f7904eb6-5352-4c5e-adf6-5f100572cf6d",
14        "timestamp": 1766050470000
15      }
16    }
17  ]
18}

Response 
202 Accepted
1{
2  "success": true
3}

See Also 

Interaction Service API Reference
Send Inbound Message Interactions
Establish Conversation
Send Historical Conversation Entries
Route Conversation
Create AgentWork Record
Update an AgentWork Record
Remove a Participant
Track Routing Status of a Conversation
Update Consent Status for a Conversation
Send Delivery Acknowledgments or Read Receipts
End or Inactivate a Messaging Session
Clear Routing
Register Capabilities
Bring Your Own Bot
Send a Message Through a Chatbot
Retrieve Conversation Entries
Abstract Message
Message Types and Message Format Types

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