--- schema_version: "1" id: a4d67b9d4a2539f9a5b10cb278712996550382134de0e36752c9304b5b3b1439 title: Send a Message Through a Chatbot collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/service-cloud/interaction-service-api/references/api-conversationEntry-post.md canonical_url: https://developer.salesforce.com/docs/service/messaging-byob/references/byob-reference/api-conversationEntry-post.html source_site: developer.salesforce.com content_type: documentation content_hash: 16802849b1b559be550a35385342a15cfaa215ca3ad20bc20abfeadee2db6e71 products: - Bring Your Own Bot for Messaging - Service Cloud Developer Content --- # 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) **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](https://help.salesforce.com/s/articleView?id=service.livemessage_managed_package_lex_differences.htm&type=5) and [messaging component formats](https://help.salesforce.com/s/articleView?id=service.messaging_component_formats.htm&type=5) before you send rich message types. For authentication details, see [Generate an Access Token](https://developer.salesforce.com/docs/service/interaction-service-api/guide/authorization.html). Sample payloads are provided for [text messages](#text-message-payload), [choice messages with buttons](#choices-message-with-buttons-payload), [choice messages with a carousel](#choices-message-with-carousel-payload), [messages in a form](#form-message-payload), [typing started indicator](#typing-started-indicator), and [typing stopped indicator](#typing-stopped-indicator). ## URI `v1/conversationEntry` ## HTTP Method POST ## Headers ### Authorization **Format:** `Bearer ` String. Standard header. The authorization token, where `` 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:** `` String. Standard header. The 15-character Org ID of the Salesforce org. Required. ### AuthorizationContext **Format:** `` 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:** `` 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](https://developer.salesforce.com/docs/service/messaging-byob/references/byob-reference/abstract-message.md). 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 ```json { "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 ```json { "success": true } ``` ### Choices Message with Buttons Payload #### Request ```json { "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 ```json { "success": true } ``` ### Choices Message with Carousel Payload #### Request ```json { "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 ```json { "success": true } ``` ### Form Message Payload #### Request ```json { "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 ```json { "success": true } ``` ### Typing Started Indicator #### Request ```json { "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 ```json { "success": true } ``` ### Typing Stopped Indicator #### Request ```json { "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 ```json { "success": true } ``` ## See Also - [Abstract Message](https://developer.salesforce.com/docs/service/messaging-byob/references/byob-reference/abstract-message.md) - [Message Types and Message Format Types](https://developer.salesforce.com/docs/service/messaging-byob/references/byob-reference/message-types-format-types.md)