jDID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!
Let us know so we can improve!
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 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
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
1{
2 "success": true
3}Choices Message with Buttons Payload
Request
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
1{
2 "success": true
3}Choices Message with Carousel Payload
Request
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
1{
2 "success": true
3}Form Message Payload
Request
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
1{
2 "success": true
3}Typing Started Indicator
Request
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
1{
2 "success": true
3}Typing Stopped Indicator
Request
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
1{
2 "success": true
3}See Also
j