Create Message

Posts a message to an existing stream.

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

multipart/form-data

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

/v4/stream/{sid}/message/create

HTTPcURLJavaScriptPython

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,
              "recipientTenantIds": [
                1
              ]
            },
            "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,
            "recipientTenantIds": [
              1
            ]
          },
          "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,
          "recipientTenantIds": [
            1
          ]
        },
        "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,
        "recipientTenantIds": [
          1
        ]
      },
      "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,
      "recipientTenantIds": [
        1
      ]
    },
    "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,
    "recipientTenantIds": [
      1
    ]
  },
  "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
}

• 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 as part of the message, and use Apache FreeMarker templates 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, use the OBO User Authenticate 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. <messageML><cash tag="*122450"/></messageML> For more information, refer to Message Format - 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 under the section Messages Size Limits.

Sending messages with Symphony Elements

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 format. For more information and examples, refer to 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 endpoint supports using Apache FreeMarker templates with Structured Objects.

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.

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

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 PresentationML representation of the message.

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 '[email protected]' \
  -F '[email protected]'

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

Message MessageML Message ID Message Format - MessageML PresentationML Message Format - ExtensionML Colors Symphony Elements