Import Message
Last updated
Was this helpful?
Last updated
Was this helpful?
Organizations can import messages to Symphony from another system using Symphony’s REST API. Typically message import is performed before an organization begins using Symphony, so that users' previous content and context are available from day one within Symphony.
This endpoint Imports a message into Symphony from another system. Imported messages will be displayed in Symphony clients with the original system's content, sender, and timestamp.
This endpoint takes as input a list of messages to be imported and outputs a status for each message. If a message is successfully imported, the messageId of the message created in Symphony is returned. If import fails on a given message, the rest of the operation will continue. It will be possible to detect any failures only after the entire operation is completed.
Your pod must be configured for Symphony's REST API, and you must have the Agent, the component used for handling encryption and decryption of messages and content, set up.
You must have a Service User with the Content Management roles. This user can be set up in the Admin Portal. In most cases, you will also want this user to have the User Provisioning role as well. This user will be used to import messages.
You must have a X.509 identity certificate for your import service user for REST API authentication, where the common name on the certificate matches your service user's username.
📘 Service User AccountsA service account is a type of account used for bots or applications, rather than for real end-users.
🚧 Importing MessagesThe Content Management role is required to call the Import Message endpoint.
Please note that the service user account needs to be part of the room where it imports messages.
See Bot Permissions for a list of roles and associated privileges.
You must specify each message to import as an object with the following fields:
message
string
Messages can be sent either in plain text or MessageML, Symphony’s message format which allows for basic formatting and entities.
It is not possible to import file attachments.
data
string
Entity data in EntityJSON
intendedMessageTimestamp
integer
The timestamp representing the time when the message was sent in the original system in milliseconds since January 1 1970 00:00:00 UTC.
Displays in Symphony clients as the timestamp of when the message was sent.
For example, if the message was originally sent in another system on January 1, 2016 and was imported on February 1, 2016, the Symphony conversation UI would show the message as being sent on January 1, 2016.
Must be a valid time in the past; a timestamp in the future returns an error.
intendedMessageFromUserId
long integer
The userId (long integer) of the Symphony user who sent the message. This user must:
Be a member of the streamId that the message is being imported into.
Be an active user at the time of import.
Importing messages from users who are inactive or not stream members results in an error.
You can deactivate this user after importing the message.
Note that the import service user does not need to be a member of the stream into which the message is imported.
originatingSystemId
string
An identifier for the original system through which the message was initially sent.
originalMessageId
string
The ID of the message in the originating system is used to prevent duplicate imports. During message import, the original messages IDs are compared to previously imported entries; in case of an exact match, the matching messages are ignored in the import.
streamId
string
The ID of the stream (IM or chatroom) into which the message is imported. Must be an active stream. Importing a message into an inactive stream results in an error. See Conversation ID for details. It is possible to deactivate the room (or user in the case of an IM) after import.
attachments
array of objects
One or more files to be sent along with the message. The limit is set to 30Mb total size; also, it is recommended not to exceed 25 files.
Each attachment object is made up of the two following required field:
filename including the extension (i.e. img.png, test.txt)
content as Base64 encoded string
previews
array of objects
Optional attachment preview.
Each preview object is made up of the two following required field:
filename including the extension (i.e. img.png, test.txt)
content as Base64 encoded string
When using previews, make sure to declare the same number of previews as the attachments declared.
messageId
string
Contains the Symphony message ID if the message is successfully created.
originatingSystemId
string
See the description in v4ImportedMessage format.
originalMessageId
string
See the description in v4ImportedMessage format.
diagnostic
string
Contains an error message if the message import fails.
Unread Status and Notifications
Imported messages do not generate unread message count badge notifications in the user's left navigation menu.
Imported messages are not highlighted as unread in conversations.
Read Receipts
Read receipts cannot be imported from another system to Symphony.
Read receipts will be generated if a user views an imported message. This will be reflected in the Message Status table, displayed when clicking on the timestamp of a message.
Special Entities
Imported messages which contain an at-mentions will appear in Social Activity under Recently Mentioned You; however, they do not generate unread message count badge notifications.
Imported messages which contain hashtags and cashtags will not appear in Signals.
Imported messages are reflected in content export based on their intendedMessageTimestamp. This means that when the import occurs, content export:
Excludes historical messages with an intendedMessageTimestamp outside of the content export range.
Includes include historical messages with an intendedMessageTimestamp within the content export range.
For ad-hoc content export, the content export range is specified by the user. For example, for an ad-hoc content export set with a start date of Jan 3 and an end date of Jan 5:
Messages with an intendedMessageTimestamp prior to Jan 3 at 00:00:00 UTC **are not **exported.
Messages with an intendedMessageTimestamp between to Jan 3 at 00:00:00 UTC and Jan 5 at 23:59:59 UTC are exported.
Messages with an intendedMessageTimestamp after to Jan 5 at 23:59:59 UTC are not exported.
For recurring content export, the content export range is defined as the period until the next scheduled content export, with a duration of the content export frequency. For example, for a frequency of 24 hrs running at 01:00:00 UTC on Feb 10:
Messages with an intendedMessageTimestamp prior to Feb 9 at 01:00:00 UTC **are not ** exported.
Messages with an intendedMessageTimestamp between to Feb 9 at 01:00:00 UTC and Feb 10 at 01:00:00 UTC are exported.
If a message import fails, use the information reported in the diagnostic field to correct the error and call this endpoint again. Symphony ignores any message with the same originalMessageId value as an existing message, and imports only those messages with uniqueoriginalMessageId values.
Ensure users involved with the message are provisioned.
Ensure all streams have been created .
Import the message.
(Optional) User and Stream Membership and Deactivation.
When you migrate messages from another system to Symphony, you will need to ensure that the accounts of all users involved (all original senders and recipients) are created.
If all these users exist, you can skip this step.
User accounts can be provisioned via Symphony's REST API.
📘 User Provisioning Service User AccountAccounts are provisioned by a Service User account which must be assigned the User Provisioning role. This user can be set up in the Admin Portal.
It is possible to use the same service user account for both message import and account provisioning provided it has been assigned both the Content Management and User Provisioning roles.
In some cases, you will want to import messages where the original sender is no longer a member of the room or the firm. In this case, you should create the user, import any messages sent by that user, and either remove the user from the room or deactivate the user after the import has been performed.
You will also need to ensure that all the streams (IMs or chatrooms) have been created.
If all of these streams exist, you can skip this step.
Chatrooms can be created and managed via Symphony's REST API. Refer to the Create Room v3 endpoint.
📘 Changing Chatroom OwnershipIf the import service user account is used to create chatrooms, the import service user will be the owner of those chatrooms.
To change this, you can promote a member of the room to an owner and remove the import service user from the room.
In some cases, you may wish to import conversations into chats between two or more users - IMs or MIMs. Please note that MIMs are deprecated and shouldn't be used anymore.
IMs can be created using the Create IM (admin) endpoint.
🚧 Admin IM CreationThe User Provisioning role is required to call the Create IM (admin) endpoint.
You must use this endpoint rather than the Create IM endpoint, so that the calling service user is not included as a participant of the chat.
Messages are imported using the Import Message endpoint described above.
🚧 Message Import Limits
We recommend importing in batches of no more than 5,000 messages at a time. Importing more than this number may result in slowness.
We recommend to be very precautious when using attachments with this endpoint as it will increase the payload hence the network usage between the Bot and the Agent.
🚧 Migration TimesYou should plan for a migration period, length dependent on the volume of messages to import and network latency.
In our experience, an organization can import about 200K messages / hour.
❗️ Import LimitationsIt is only possible to import messages from another system into Symphony. It is not possible to import read receipts or chatroom events (ex. membership changes).
Once you have imported all your messages, you may wish to remove certain users from rooms or deactivate certain users or rooms.
For example, if you used the import service user for room creation, you may want to transfer ownership of the room and remove this user from the room.
For example, you may want to deactivate the Symphony user that was created to represent a user who sent messages in the old system, but has since left the firm.
Content Export The following are some notes that may be of interest to admins regarding aspects of imported messages:
Imported messages are exported in Content Export based on the original timestamp (intendedMessageTimestamp).
After messages are imported, Content Export will not include imported messages where the original timestamp is outside of the Content Export range and will include messages where the original timestamp is within the Content Export range.
In ad-hoc content export, the range is specified by the admin user.
For example, for an ad-hoc content export with a start date of January 1 and end date of January 5:
Messages with an original timestamp before January 1, 00:00:00 UTC would not be exported.
Messages with an original timestamp between January 1, 00:00:00 UTC and January 5, 23:59:59 UTC would be exported.
Messages with an original timestamp after January 5, 23:59:59 would not be exported.
In recurring content export, the range is defined as the period until the next scheduled content export, with a duration of the content export frequency specified by the admin user.
For example, for a recurring content export with a frequency of 24 hours running on February 2, 00:00:00 UTC:
Messages with an original timestamp before February 1, 00:00:00 UTC would not be exported.
Messages with an original timestamp between February 1, 00:00:00 UTC and January 2, 00:00:00 UTC would be exported.
Room Monitor
Imported messages will be displayed in the Room Monitor as they are displayed to room members - with the original sender and original timestamp.
📘 See also
Message MessageML Message ID Message Format - MessageML PresentationML Message Format - ExtensionML Colors Symphony Elements
Sends a message to be imported into the system. Allows you to override the timestamp and author of the message with your desired values. The requesting user must have the Content Management role. The user that the message is intended to have come from must also be present in the conversation. The intended message timestamp must be a valid time from the past. It cannot be a future timestamp. Optionally the original message ID can be specified to identify the imported message for the purpose of repeat imports.
Session authentication token.
Key Manager authentication token.
An ordered list of historic messages to be imported. A list of import responses will be returned in the same order.
Message text in MessageMLV2
Entity data in EntityJSON
The timestamp representing the time when the message was sent in the original system in milliseconds since Jan 1st 1970.
The long integer userid of the Symphony user who you intend to show sent the message.
The ID of the system through which the message was originally sent.
The ID of the message in the original system.