Symphony Messaging REST APIs
  • Symphony Messaging API Reference documentation
  • Endpoints Reference
    • Bots Authentication
      • Session Authenticate
      • Key Manager Authenticate
      • Session Authenticate (Cert)
      • Key Manager Authenticate (Cert)
      • Session Logout
      • Key Manager Logout
    • Apps Authentication
      • Authenticate App
      • Pod Certificate
    • Apps On Behalf Of (OBO)
      • API Endpoints for Apps
      • App Authentication
      • User Authentication by User ID
      • User Authentication by User Name
    • Info - Health Check
      • Health Check
      • Health Check Extended
      • Session User
      • Agent Info
      • Echo
    • Messages
      • Get Messages
      • Create Message
      • Blast Message
      • Attachment
      • Import Message
      • Update Message
      • Suppress Message
      • Message Search
      • Message Search
      • Message Status
      • Attachment Types
      • Get Message
      • List Attachments
      • List Message Receipts
      • Message Metadata
    • Datafeed - Real Time Events
      • Create Datafeed
      • Read Datafeed
      • List Datafeed
      • Delete Datafeed
    • Datahose - Pod Real Time Events
      • Datahose - Read Events
    • Streams - Conversations
      • Related to IMs
        • Create IM
        • Create IM non-inclusive
        • Update IM
        • IM Info
      • Related to Rooms
        • Room Attributes
        • Create Room
        • Update Room
        • Room Info
        • De/Re-activate Room
        • Room Members
        • Add Member
        • Remove Member
        • Promote Owner
        • Demote Owner
        • Search Rooms
      • All streams
        • Share Content
        • List User Streams
        • List User Streams (Admin)
        • Stream Info
        • List Streams for Enterprise
        • Stream Members
    • Signals
      • List Signals
      • Get Signal
      • Create Signal
      • Update Signal
      • Delete Signal
      • Subscribe Signal
      • Unsubscribe Signal
      • Suscribers
      • Signal Object
    • Connections
      • Get Connection
      • List Connection
      • Create Connection
      • Accept Connection
      • Reject Connection
      • Remove Connection
    • Presence
      • Get Presence
      • Get All Presence
      • Get User Presence
      • External Presence Interest
      • Set Presence
      • Set Other User's Presence - Admin
    • Users
      • Users Lookup
      • Search Users
      • Follow User
      • Unfollow User
      • List User Followers
      • List Users Followed
    • User Management
      • User Attributes Object
      • Password Object
      • Roles Object
      • UserKeyRequest Object
      • Get User
      • List Users
      • Create User
      • Update User
      • User Avatar
      • Update User Avatar
      • User Status
      • Update User Status
      • List Features
      • User Features
      • Update User Features
      • Find Users
      • List Roles
      • Add Role
      • Remove Role
      • List Audit Trail
      • Suspend User Account
      • Get Bot Manifest
      • Update Bot Manifest
    • User Sessions
      • List Sessions
      • Logout Session
      • Logout All Sessions
    • Groups - Distribution Lists
      • OAuth2 Authenticate
      • Add a new user to an existing group
      • Insert a new group
      • Retrieve a group
      • Update a group
      • List all groups of specified type
      • Update the group avatar
    • URI Protocols
      • Create Protocol
      • List Protocols
      • Delete Protocol
    • Manage Apps
      • Create App
      • Update App
      • Delete App
      • Get App
    • Apps Entitlements
      • List Apps
      • Update App Entitlements
      • List User Apps
      • Update User Apps
      • Update All User Apps
    • Disclaimers
      • Disclaimer
      • List Disclaimers
      • List Disclaimer Users
      • User Disclaimer
      • Update User Disclaimer
      • Unassign User Disclaimer
    • Delegates
      • User Delegates
      • Update User Delegates
    • Information Barrier Groups
      • List IB Groups
      • List IB Group Members
      • Add IB Group Members
      • Remove IB Group Members
      • List Policies
    • Certificates
      • Public (Signing) Certificate
      • List Company Certificates
      • Create Company Certificate
      • Delete Company Certificate
      • Company Certificate Details
      • List Verified Certificates
      • List Trusted Certificates
      • List Certificate Types
      • Update Company Certificate
    • Malware Scanner
      • Malware Scanner APIs
        • File Malware Scanner State
        • Update File Malware Scanner State
      • Customer Malware Scanner APIs
        • Malware Scanner Health
        • File Malware Scanner
    • DLP Dictionary & Policy Management
      • Overview
      • Dictionary Management endpoints
        • Create Dictionary
        • All Dictionaries
        • Specific Dictionary
        • Update Dictionary
        • Upload Dictionary Content
        • Download Dictionary Content
        • Delete Dictionary
      • V3 Policy Management endpoints
        • V3 Policy structure for Create/Update
        • V3 Create Policy
        • V3 All Policies
        • V3 Get Policy
        • V3 Update Policy
        • V3 Enable Policy
        • V3 Disable Policy
        • V3 Delete Policy
      • V3 Violations endpoints
        • V3 Violations - Sample Responses
        • V3 Violations - Special Scenarios of Attachments
        • V3 Message Violations
        • V3 Signal Violations
        • V3 Stream Violations
        • V3 Violation Attachment Download
    • Audit Trail 2
      • OAuth2 Authenticate
      • Get Audit trails
      • Get distinct values of a list of filters
      • Get Audit Trail Stream
      • Get categories permissions
    • Compliance Barrier Groups
      • Compliance Group Types
      • Compliance User Groups
        • List Compliance User Groups
        • Get a Compliance User Group
        • Create a Compliance User Group
        • Update a Compliance User Group
      • Compliance Group Assignments
        • List Assignments
        • List Compliance Group Assignments
        • Update a Compliance Group
      • Compliance Group Memberships
        • List Memberships
        • List Compliance Group Memberships
        • Add Compliance Group Membership
        • Update a User Membership
  • Deprecated Endpoints
    • DLP Dictionary and Policy management
      • V2 Policy Management endpoints
        • V2 Create Policy
        • V2 All Policies
        • V2 Get Policy
        • V2 Update Policy
        • V2 Enable Policy
        • V2 Disable Policy
        • V2 Delete Policy
      • V2 Violations endpoints
        • V2 Signal Violations
        • V2 Message Violations
        • V2 Stream Violations
    • Create Presence Feed
    • Read Presence Feed
    • Delete Presence Feed
    • Get Message IDs by Timestamp
    • Health Check v2
    • Datafeed 1
      • Create Datafeed 1
      • Read Datafeed 1
Powered by GitBook
On this page

Was this helpful?

  1. Endpoints Reference
  2. Messages

Create Message

Posts a message to an existing stream.

Last updated 8 months ago

Was this helpful?

  • 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 as part of the message, and use 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 , use the 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.

  • Attachments: The limit is set to 30Mb total size; also, it is recommended not to exceed 25 files.

Sending messages with Symphony Elements

Sending Symphony Elements is only supported for SYSTEM users (Service Accounts).

Use Apache FreeMarker Templates

Important! To support the use of Freemarker variables, the top-level variable name in the div or span tag in <messageML> must be $entity or $data.

See also cURL - Message + Data in the examples below.

<messageML>
	<div>Messages for user <b>${data["messageList"].user.userName}</b>:</div>
	<table>
		<#list data["messageList"].messages as msg>
		<tr>
			<td>${msg.timestamp}</td>
			<td>${msg.text}</td>
		</tr>
		</#list>
	</table>
</messageML>
{
  "messageList": {
    "version": "1.0",
    "user": {
      "id": 123456,
      "userName": "bot.user01"
    },
    "messages": [
      {
        "timestamp": "1504736061894",
        "text": "Ping"
      },
      {
        "timestamp": "1504736023993",
        "text": "Pong"
      }
    ]
  }
}
<div data-format="PresentationML" data-version="2.0">
   <div>Messages for user <b>bot.user01</b>:</div>
   <table>
      <tr>
         <td>1504736061894</td>
         <td>Ping</td>
      </tr>
      <tr>
         <td>1504736023993</td>
         <td>Pong</td>
      </tr>
   </table>
</div>

Other request examples

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=<messageML>Hello world!</messageML>'
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=<messageML>Hello world!</messageML>' \
  -F 'attachment=@image1.png' \
  -F 'attachment=@image2.png'
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=<messageML>This is an <div class="entity" data-entity-id="object001"><b>important</b></div> message.</messageML>' \
  -F 'data={
    "object001":
    {
        "type":     "org.symphonyoss.taxonomy",
        "version":  "0.1",
        "id":
        [
            {
                "type":     "org.symphonyoss.taxonomy.keyword",
                "value":    "important"
            }
        ]
    }
}'
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='<messageML>Hello world</messageML>'&data='{'foo':'bar'}'"
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": "<messageML>Hello world</messageML>",
        "data": "{\"foo\":\"bar\"}"
    }'

📘 See also

To send numeric cashtags as signals, add a * before the number such as $*122450. E.g. <messageML><cash tag="*122450"/></messageML> For more information, refer to .

For more information on the size limits of messages, please refer to under the section Messages Size Limits.

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 format. For more information and examples, refer to .

The message and data parameters of the endpoint supports using with .

Using the 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 .

The first and second examples show the FreeMarker template content enclosed in <messageML> for the message parameter and the associated data model for the data parameter. The third example shows the resulting representation of the message.

Message Format - MessageML
Messages
Symphony Elements
MessageML
Symphony Elements
Create Message v4
Apache FreeMarker templates
Structured Objects
Freemarker
Symphony Elements - Table Select
PresentationML
Message
MessageML
Message ID
Message Format - MessageML
PresentationML
Message Format - ExtensionML
Colors
Symphony Elements
Structured Objects
Apache FreeMarker templates
OBO User Authenticate
OBO-Enabled Endpoints
  • POSTPost a message to one existing stream.
  • Sending messages with Symphony Elements
  • Use Apache FreeMarker Templates
  • Other request examples

Post a message to one existing stream.

post

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.

Path parameters
sidstringRequired

Stream ID

Header parameters
sessionTokenstringRequired

Authorization token used to make delegated calls.

keyManagerTokenstringOptional

Key Manager authentication token.

Body
messagestringOptional

The message payload in MessageML.

datastringOptional

Optional message data in EntityJSON.

versionstringOptional

Optional message version in the format "major.minor". If empty, defaults to the latest supported version.

attachmentstring · binaryOptional

Optional file attachment.

previewstring · binaryOptional

Optional attachment preview.

Responses
200
Message sent.
application/json
400
Client error, see response body for further details.
application/json
401
Unauthorized: Session tokens invalid.
application/json
403
Forbidden: Caller lacks necessary entitlement.
application/json
451
Compliance Issues found in message or file
application/json
500
Server error, see response body for further details.
application/json
post
POST /agent/v4/stream/{sid}/message/create HTTP/1.1
Host: youragentURL.symphony.com
sessionToken: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 90

{
  "message": "text",
  "data": "text",
  "version": "text",
  "attachment": "binary",
  "preview": "binary"
}
{
  "messageId": "text",
  "parentMessageId": "text",
  "timestamp": 1,
  "message": "text",
  "sharedMessage": {
    "messageId": "text",
    "parentMessageId": "text",
    "timestamp": 1,
    "message": "text",
    "sharedMessage": {
      "messageId": "text",
      "parentMessageId": "text",
      "timestamp": 1,
      "message": "text",
      "sharedMessage": {
        "messageId": "text",
        "parentMessageId": "text",
        "timestamp": 1,
        "message": "text",
        "sharedMessage": {
          "messageId": "text",
          "parentMessageId": "text",
          "timestamp": 1,
          "message": "text",
          "sharedMessage": {
            "messageId": "text",
            "parentMessageId": "text",
            "timestamp": 1,
            "message": "text",
            "sharedMessage": "[Circular Reference]",
            "data": "text",
            "attachments": [
              {
                "id": "text",
                "name": "text",
                "size": 1,
                "images": [
                  {
                    "id": "text",
                    "dimension": "text"
                  }
                ]
              }
            ],
            "user": {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            },
            "stream": {
              "streamId": "text",
              "streamType": "text",
              "roomName": "text",
              "members": [
                {
                  "userId": 1,
                  "firstName": "text",
                  "lastName": "text",
                  "displayName": "text",
                  "email": "text",
                  "username": "text"
                }
              ],
              "external": true,
              "crossPod": true
            },
            "externalRecipients": true,
            "diagnostic": "text",
            "userAgent": "text",
            "originalFormat": "text",
            "disclaimer": "text",
            "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
            "replacing": "text",
            "replacedBy": "text",
            "initialTimestamp": 1,
            "initialMessageId": "text",
            "silent": true
          },
          "data": "text",
          "attachments": [
            {
              "id": "text",
              "name": "text",
              "size": 1,
              "images": [
                {
                  "id": "text",
                  "dimension": "text"
                }
              ]
            }
          ],
          "user": {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          },
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true
          },
          "externalRecipients": true,
          "diagnostic": "text",
          "userAgent": "text",
          "originalFormat": "text",
          "disclaimer": "text",
          "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
          "replacing": "text",
          "replacedBy": "text",
          "initialTimestamp": 1,
          "initialMessageId": "text",
          "silent": true
        },
        "data": "text",
        "attachments": [
          {
            "id": "text",
            "name": "text",
            "size": 1,
            "images": [
              {
                "id": "text",
                "dimension": "text"
              }
            ]
          }
        ],
        "user": {
          "userId": 1,
          "firstName": "text",
          "lastName": "text",
          "displayName": "text",
          "email": "text",
          "username": "text"
        },
        "stream": {
          "streamId": "text",
          "streamType": "text",
          "roomName": "text",
          "members": [
            {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            }
          ],
          "external": true,
          "crossPod": true
        },
        "externalRecipients": true,
        "diagnostic": "text",
        "userAgent": "text",
        "originalFormat": "text",
        "disclaimer": "text",
        "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
        "replacing": "text",
        "replacedBy": "text",
        "initialTimestamp": 1,
        "initialMessageId": "text",
        "silent": true
      },
      "data": "text",
      "attachments": [
        {
          "id": "text",
          "name": "text",
          "size": 1,
          "images": [
            {
              "id": "text",
              "dimension": "text"
            }
          ]
        }
      ],
      "user": {
        "userId": 1,
        "firstName": "text",
        "lastName": "text",
        "displayName": "text",
        "email": "text",
        "username": "text"
      },
      "stream": {
        "streamId": "text",
        "streamType": "text",
        "roomName": "text",
        "members": [
          {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          }
        ],
        "external": true,
        "crossPod": true
      },
      "externalRecipients": true,
      "diagnostic": "text",
      "userAgent": "text",
      "originalFormat": "text",
      "disclaimer": "text",
      "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
      "replacing": "text",
      "replacedBy": "text",
      "initialTimestamp": 1,
      "initialMessageId": "text",
      "silent": true
    },
    "data": "text",
    "attachments": [
      {
        "id": "text",
        "name": "text",
        "size": 1,
        "images": [
          {
            "id": "text",
            "dimension": "text"
          }
        ]
      }
    ],
    "user": {
      "userId": 1,
      "firstName": "text",
      "lastName": "text",
      "displayName": "text",
      "email": "text",
      "username": "text"
    },
    "stream": {
      "streamId": "text",
      "streamType": "text",
      "roomName": "text",
      "members": [
        {
          "userId": 1,
          "firstName": "text",
          "lastName": "text",
          "displayName": "text",
          "email": "text",
          "username": "text"
        }
      ],
      "external": true,
      "crossPod": true
    },
    "externalRecipients": true,
    "diagnostic": "text",
    "userAgent": "text",
    "originalFormat": "text",
    "disclaimer": "text",
    "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
    "replacing": "text",
    "replacedBy": "text",
    "initialTimestamp": 1,
    "initialMessageId": "text",
    "silent": true
  },
  "data": "text",
  "attachments": [
    {
      "id": "text",
      "name": "text",
      "size": 1,
      "images": [
        {
          "id": "text",
          "dimension": "text"
        }
      ]
    }
  ],
  "user": {
    "userId": 1,
    "firstName": "text",
    "lastName": "text",
    "displayName": "text",
    "email": "text",
    "username": "text"
  },
  "stream": {
    "streamId": "text",
    "streamType": "text",
    "roomName": "text",
    "members": [
      {
        "userId": 1,
        "firstName": "text",
        "lastName": "text",
        "displayName": "text",
        "email": "text",
        "username": "text"
      }
    ],
    "external": true,
    "crossPod": true
  },
  "externalRecipients": true,
  "diagnostic": "text",
  "userAgent": "text",
  "originalFormat": "text",
  "disclaimer": "text",
  "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
  "replacing": "text",
  "replacedBy": "text",
  "initialTimestamp": 1,
  "initialMessageId": "text",
  "silent": true
}