# Create Message ## Post a message to one existing stream. > Post a new message to the given stream. The stream can be a chatroom,,an IM or a multiparty IM.\ > \ > You may include an attachment on the message.\ > \ > The message can be provided as MessageMLV2 or PresentationML. Both formats support Freemarker templates.\ > \ > The optional parameter "data" can be used to provide a JSON payload containing entity data.\ > If the message contains explicit references to entity data (in "data-entity-id" element attributes),\ > this parameter is required.\ > \ > If the message is in MessageML and fails schema validation a client error will be returned.\ > \ > If the message is sent then 200 is returned.\ > \ > Regarding authentication, you must either use the sessionToken which was created for delegated app access\ > or both the sessionToken and keyManagerToken together.
```json {"openapi":"3.0.1","info":{"title":"Agent API","version":"25.8.1"},"servers":[{"url":"youragentURL.symphony.com/agent"}],"paths":{"/v4/stream/{sid}/message/create":{"post":{"tags":["Messages"],"summary":"Post a message to one existing stream.","description":"Post a new message to the given stream. The stream can be a chatroom,,an IM or a multiparty IM.\n\nYou may include an attachment on the message.\n\nThe message can be provided as MessageMLV2 or PresentationML. Both formats support Freemarker templates.\n\nThe optional parameter \"data\" can be used to provide a JSON payload containing entity data.\nIf the message contains explicit references to entity data (in \"data-entity-id\" element attributes),\nthis parameter is required.\n\nIf the message is in MessageML and fails schema validation a client error will be returned.\n\nIf the message is sent then 200 is returned.\n\nRegarding authentication, you must either use the sessionToken which was created for delegated app access\nor both the sessionToken and keyManagerToken together.\n","parameters":[{"name":"sid","in":"path","description":"Stream ID","required":true,"schema":{"type":"string"}},{"name":"sessionToken","in":"header","description":"Authorization token used to make delegated calls.","required":true,"schema":{"type":"string"}},{"name":"keyManagerToken","in":"header","description":"Key Manager authentication token.","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"message":{"type":"string","description":"The message payload in MessageML."},"data":{"type":"string","description":"Optional message data in EntityJSON."},"version":{"type":"string","description":"Optional message version in the format \"major.minor\". If empty, defaults to the latest supported version.\n"},"attachment":{"type":"string","description":"Optional file attachment.","format":"binary"},"preview":{"type":"string","description":"Optional attachment preview.","format":"binary"}}}}}},"responses":{"200":{"description":"Message sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V4Message"}}}},"400":{"description":"Client error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"401":{"description":"Unauthorized: Session tokens invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"403":{"description":"Forbidden: Caller lacks necessary entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"451":{"description":"Compliance Issues found in message or file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"500":{"description":"Server error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}}}}}},"components":{"schemas":{"V4Message":{"type":"object","properties":{"messageId":{"type":"string","description":"Id of the message"},"parentMessageId":{"type":"string","description":"Id of the parent message, set when the message is a reply to another message or a forwarded message. Since Agent 20.14."},"timestamp":{"type":"integer","description":"Timestamp of the message in milliseconds since Jan 1 1970","format":"int64"},"message":{"type":"string","description":"Message content in MessageMLV2","format":"MessageMLV2"},"sharedMessage":{"$ref":"#/components/schemas/V4Message"},"data":{"type":"string","description":"Message data in EntityJSON","format":"JSON"},"attachments":{"type":"array","default":[],"description":"Message attachments","items":{"$ref":"#/components/schemas/V4AttachmentInfo"}},"user":{"$ref":"#/components/schemas/V4User"},"stream":{"$ref":"#/components/schemas/V4Stream"},"externalRecipients":{"type":"boolean","description":"Indicates if the message have external recipients. Only present on real time messaging."},"diagnostic":{"type":"string","description":"Details if event failed to parse for any reason. The contents of this field may not be useful,\ndepending on the nature of the error. Only present when error occurs.\n"},"userAgent":{"type":"string","description":"User agent string for client that sent the message. Allows callers to identify which client sent the\norigin message (e.g. API Agent, SFE Client, mobile, etc)\n"},"originalFormat":{"type":"string","description":"Indicates the format in which the message was originally sent. This could have been either:\n- com.symphony.markdown - Markdown OR Message ML V1\n- com.symphony.messageml.v2 - Message ML V2\n"},"disclaimer":{"type":"string","description":"Message that may be sent along with a regular message if configured for the POD,\nusually the first message sent in a room that day.\n"},"sid":{"type":"string","description":"Unique session identifier from where the message was created.\n"},"replacing":{"type":"string","description":"Id of the message that the current message is replacing (present only if set)"},"replacedBy":{"type":"string","description":"Id of the message that the current message is being replaced with (present only if set)"},"initialTimestamp":{"type":"integer","description":"Timestamp of when the initial message has been created in milliseconds since \nJan 1 1970 (present only if set)\n","format":"int64"},"initialMessageId":{"type":"string","description":"Id the the initial message that has been updated (present only if set)"},"silent":{"type":"boolean","description":"When false the user/s will receive the message update as unread (true by default)"}},"description":"A representation of a message sent by a user of Symphony"},"V4AttachmentInfo":{"required":["id","name","size","images"],"type":"object","properties":{"id":{"type":"string","description":"The attachment ID."},"name":{"type":"string","description":"The file name."},"size":{"type":"integer","description":"Size in bytes.","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/V4ThumbnailInfo"}}}},"V4ThumbnailInfo":{"type":"object","properties":{"id":{"type":"string","description":"The thumbnail ID."},"dimension":{"type":"string","description":"The thumbnail pixel size."}}},"V4User":{"type":"object","properties":{"userId":{"type":"integer","description":"Id of user","format":"int64"},"firstName":{"type":"string","description":"First name of user"},"lastName":{"type":"string","description":"Last name of user"},"displayName":{"type":"string","description":"User display name"},"email":{"type":"string","description":"Email of user"},"username":{"type":"string","description":"Applicable only to internal users"}}},"V4Stream":{"type":"object","properties":{"streamId":{"type":"string","description":"Id of stream"},"streamType":{"type":"string","description":"Stream type, possible values are:\n - IM\n - MIM\n - ROOM\n - POST\n"},"roomName":{"type":"string","description":"Applicable only to rooms"},"members":{"type":"array","description":"Applicable only to IM Created","items":{"$ref":"#/components/schemas/V4User"}},"external":{"type":"boolean"},"crossPod":{"type":"boolean"},"recipientTenantIds":{"type":"array","description":"List of tenant identifiers (aka pod identifiers) involved in the conversation. It contains more than one\nitem if the conversation is external. Field is only present for real time messaging.\n","items":{"type":"integer","format":"int32"}}}},"V2Error":{"required":["code","message"],"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"object"}}}}}} ``` * You can specify one or more attachments to the message. The attachment file can be uploaded along with the message using this endpoint. * You can also specify [Structured Objects](https://docs.developers.symphony.com/building-bots-on-symphony/messages/structured-objects) as part of the message, and use [Apache FreeMarker templates](http://freemarker.org/) with these objects. See **Use Apache FreeMarker Templates** section below. * Interactive Elements can be sent with your messages. See **Sending messages with Symphony Elements** section below. * For authentication, you must either use the `sessionToken` that was created for delegated application access, or both the `sessionToken` and `keyManagerToken` together. * When calling this as an [OBO-Enabled Endpoints](https://rest-api.symphony.com/apps-on-behalf-of-obo/obo-enabled-endpoints#api-endpoints-enabled-for-obo), use the [OBO User Authenticate](https://rest-api.symphony.com/main/apps-on-behalf-of-obo/obo-rsa-user-authentication-by-user-id) token for `sessionToken`. > #### ๐Ÿšง Known Limitations > > * You canโ€™t send a message that contains only an attachment without any message content. `message` must contain a least one space. > * DLP (Expression Filters) only works with 1.53 version onwards. > * Symphony Elements only works with 1.55.3 version onwards. > * To send messages to not public rooms, the caller needs to be part of the stream. > * To send numeric cashtags as signals, add a `*` before the number such as `$*122450`.\ > E.g. ``\ > For more information, refer to [Message Format - MessageML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-messageml). > * Attachments: The limit is set to 30Mb total size; also, it is recommended not to exceed 25 files. > * For more information on the size limits of messages, please refer to [Messages](https://docs.developers.symphony.com/building-bots-on-symphony/messages#message-size-limits) under the section Messages Size Limits. ### Sending messages with Symphony Elements [Symphony Elements](https://docs.developers.symphony.com/building-bots-on-symphony/symphony-elements) is a collection of interactive elements that can be sent within messages to facilitate communication with Symphony users. Through the use of the elements, bots can send messages that contain forms with text fields, dropdown menus, person selectors, buttons and more! To use the Elements, you just need to call the `/agent/v4/stream/:sid/message/create` API using the [MessageML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-messageml) format. For more information and examples, refer to [Symphony Elements](https://docs.developers.symphony.com/building-bots-on-symphony/symphony-elements). *Sending Symphony Elements is only supported for `SYSTEM` users (Service Accounts).* ### Use Apache FreeMarker Templates The `message` and `data` parameters of the [Create Message v4](https://rest-api.symphony.com/main/messages/create-message-v4) endpoint supports using [Apache FreeMarker templates](http://freemarker.org/) with [Structured Objects](https://docs.developers.symphony.com/building-bots-on-symphony/messages/structured-objects). **Important!** To support the use of Freemarker variables, the top-level variable name in the `div` or `span` tag in `` must be `$entity` or `$data`. Using the [Freemarker](https://freemarker.apache.org/) template, you can also create tables that contain a special column with `checkboxes` or `buttons` on it, allowing users to select one or more rows of the table. For more information, refer to [Symphony Elements - Table Select](https://docs.developers.symphony.com/building-bots-on-symphony/symphony-elements/available-elements/table-select). The first and second examples show the FreeMarker template content enclosed in `` for the `message` parameter and the associated data model for the `data` parameter. The third example shows the resulting [PresentationML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-presentationml) representation of the message. See also **cURL - Message + Data** in the examples below. ```xml
Messages for user ${data["messageList"].user.userName}:
<#list data["messageList"].messages as msg>
${msg.timestamp} ${msg.text}
``` ```json { "messageList": { "version": "1.0", "user": { "id": 123456, "userName": "bot.user01" }, "messages": [ { "timestamp": "1504736061894", "text": "Ping" }, { "timestamp": "1504736023993", "text": "Pong" } ] } } ``` ```xml
Messages for user bot.user01:
1504736061894 Ping
1504736023993 Pong
``` ### Other request examples ```bash curl -X POST \ https://acme.symphony.com/agent/v4/stream/xFfPil_o26qXzGwWvcw5RH___qQr0W7EdA/message/create \ -H 'Content-Type: multipart/form-data' \ -H 'sessionToken: SESSION_TOKEN' \ -H 'keyManagerToken: KEY_MANAGER_TOKEN' \ --form-string 'message=Hello world!' ``` ```bash curl -X POST \ https://acme.symphony.com:443/agent/v4/stream/xFfPil_o26qXzGwWvcw5RH___qQr0W7EdA/message/create \ -H 'content-type: multipart/form-data' \ -H 'keyManagerToken: KEY_MANAGER_TOKEN' \ -H 'sessionToken: SESSION_TOKEN' \ --form-string 'message=Hello world!' \ -F 'attachment=@image1.png' \ -F 'attachment=@image2.png' ``` ```bash curl -X POST \ https://acme.symphony.com:443/agent/v4/stream/xFfPil_o26qXzGwWvcw5RH___qQr0W7EdA/message/create \ -H 'Content-Type: multipart/form-data' \ -H 'keyManagerToken: KEY_MANAGER_TOKEN' \ -H 'sessionToken: SESSION_TOKEN' \ --form-string 'message=This is an
important
message.' \ -F 'data={ "object001": { "type": "org.symphonyoss.taxonomy", "version": "0.1", "id": [ { "type": "org.symphonyoss.taxonomy.keyword", "value": "important" } ] } }' ``` ```bash curl -X POST \ https://acme.symphony.com:443/agent/v4/stream/xFfPil_o26qXzGwWvcw5RH___qQr0W7EdA/message/create \ -H "sessionToken: SESSION_TOKEN" \ -H "keyManagerToken: KEY_MANAGER_TOKEN" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "message='Hello world'&data='{'foo':'bar'}'" ``` ```bash curl -X POST \ https://acme.symphony.com:443/agent/v4/stream/xFfPil_o26qXzGwWvcw5RH___qQr0W7EdA/message/create \ -H "sessionToken: SESSION_TOKEN" \ -H "keyManagerToken: KEY_MANAGER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Hello world", "data": "{\"foo\":\"bar\"}" }' ``` > ๐Ÿ“˜ See also > > [Message](https://docs.developers.symphony.com/building-bots-on-symphony/messages)\ > [MessageML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-messageml)\ > [Message ID
](https://docs.developers.symphony.com/bots/messages#message-identifiers)\ > [Message Format - MessageML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-messageml)\ > [PresentationML](https://docs.developers.symphony.com/building-bots-on-symphony/messages/overview-of-presentationml)\ > [Message Format - ExtensionML](https://docs.developers.symphony.com/building-extension-applications-on-symphony/overview-of-extension-api/extension-api-services/entity-service/message-format-extensionml)\ > [Colors](https://docs.developers.symphony.com/developer-tools/developer-tools/ui-style-guide/colors)\ > [Symphony Elements](https://docs.developers.symphony.com/building-bots-on-symphony/symphony-elements)