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

Import Message

Last updated 4 months ago

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.

Request Examples

curl -X POST \
https://acme.symphony.com/agent/v4/message/import \
-H "sessionToken: SESSION_TOKEN" \
-H "keyManagerToken: KEY_MANAGER_TOKEN" \
-H "Content-Type: application/json" \
-d '[
    {
        "message": "<messageML>Imported message</messageML>",
        "format": "MESSAGEML",
        "intendedMessageTimestamp": 1433045622000,
        "intendedMessageFromUserId": 7215545057281,
        "originatingSystemId": "fooChat",
        "streamId": "Z3oQRAZGTCNl5KjiUH2G1n___qr9lLT8dA",
        "attachments": [
          {
            "filename": "symphonyLogo.png",
            "content": "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"
          },
          {
            "filename": "attachment.txt",
            "content": "VGhpcyBpcyBhbiBhdHRhY2htZW50Lg=="
          }
        ],
        "previews": [
          {
            "filename": "symphonyPreview.png",
            "content": "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"
          },
          {
            "filename": "attachment.txt",
            "content": "VGhpcyBpcyBhbiBhdHRhY2htZW50Lg=="
          }
        ]
    }
]'
curl -X POST \
https://acme.symphony.com/agent/v4/message/import \
-H "sessionToken: SESSION_TOKEN" \
-H "keyManagerToken: KEY_MANAGER_TOKEN" \
-H "Content-Type: application/json" \
-d '[
    {
        "message": "<messageML>Imported message</messageML>",
        "format": "MESSAGEML",
        "intendedMessageTimestamp": 1433045622000,
        "intendedMessageFromUserId": 7215545057281,
        "originatingSystemId": "fooChat",
        "streamId": "Z3oQRAZGTCNl5KjiUH2G1n___qr9lLT8dA"
    }
]'

Prerequisites

  • 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.

📘 Service User Accounts

A service account is a type of account used for bots or applications, rather than for real end-users.

🚧 Importing Messages

The 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.

v4ImportedMessage Format

You must specify each message to import as an object with the following fields:

Field
Type
Required
Description

message

string

  • 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

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.

V4ImportResponse

Field
Type
Description

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.

Content Export of Imported Messages

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.

Correct and Reimport Failed Messages

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.

Steps to Import a Message

  1. Ensure users involved with the message are provisioned.

  2. Ensure all streams have been created .

  3. Import the message.

  4. (Optional) User and Stream Membership and Deactivation.

User Provisioning

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 Account

Accounts 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.

Stream Creation

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.

📘 Changing Chatroom Ownership

If 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.

🚧 Admin IM Creation

Message Import

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 Times

You 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 Limitations

It 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).

User and Stream Membership and Deactivation

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.

Admin Impact

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

Your pod must be configured for Symphony's REST API, and you must have the , the component used for handling encryption and decryption of messages and content, set up.

You must have a X.509 identity certificate for your import service user for REST API , where the common name on the certificate matches your service user's username.

See for a list of roles and associated privileges.

Messages can be sent either in plain text or , Symphony’s message format which allows for basic formatting and entities.

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 for details. It is possible to deactivate the room (or user in the case of an IM) after import.

Chatrooms can be created and managed via Symphony's REST API. Refer to the endpoint.

IMs can be created using the endpoint.

The User Provisioning role is required to call the endpoint.

You must use this endpoint rather than the endpoint, so that the calling service user is not included as a participant of the chat.

Agent
authentication
Bot Permissions
Create Room v3
Create IM (admin)
Create IM (admin)
Create IM
Message
MessageML
Message ID
Message Format - MessageML
PresentationML
Message Format - ExtensionML
Colors
Symphony Elements
MessageML
Conversation ID
  • POSTImport messages from other systems into Symphony.
  • Request Examples
  • Prerequisites
  • v4ImportedMessage Format
  • V4ImportResponse
  • Content Export of Imported Messages
  • Correct and Reimport Failed Messages
  • Steps to Import a Message
  • User Provisioning
  • Stream Creation
  • Message Import
  • User and Stream Membership and Deactivation
  • Admin Impact

Import messages from other systems into Symphony.

post

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.

Header parameters
sessionTokenstringRequired

Session authentication token.

keyManagerTokenstringRequired

Key Manager authentication token.

Body

An ordered list of historic messages to be imported. A list of import responses will be returned in the same order.

messagestring · MessageMLRequired

Message text in MessageMLV2

datastring · JSONOptional

Entity data in EntityJSON

intendedMessageTimestampinteger · int64Required

The timestamp representing the time when the message was sent in the original system in milliseconds since Jan 1st 1970.

intendedMessageFromUserIdinteger · int64Required

The long integer userid of the Symphony user who you intend to show sent the message.

originatingSystemIdstringRequired

The ID of the system through which the message was originally sent.

originalMessageIdstringOptional

The ID of the message in the original system.

streamIdstringRequired
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
500
Server error, see response body for further details.
application/json
post
POST /agent/v4/message/import HTTP/1.1
Host: youragentURL.symphony.com
sessionToken: text
keyManagerToken: text
Content-Type: application/json
Accept: */*
Content-Length: 5695

[
  {
    "message": "<messageML>Imported message</messageML>",
    "format": "MESSAGEML",
    "intendedMessageTimestamp": 1433045622000,
    "intendedMessageFromUserId": 7215545057281,
    "originatingSystemId": "fooChat",
    "streamId": "Z3oQRAZGTCNl5KjiUH2G1n___qr9lLT8dA",
    "attachments": [
      {
        "filename": "symphonyLogo.png",
        "content": "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"
      },
      {
        "filename": "attachment.txt",
        "content": "VGhpcyBpcyBhbiBhdHRhY2htZW50Lg=="
      }
    ],
    "previews": [
      {
        "filename": "symphonyPreview.png",
        "content": "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"
      },
      {
        "filename": "attachment.txt",
        "content": "VGhpcyBpcyBhbiBhdHRhY2htZW50Lg=="
      }
    ]
  }
]
[
  {
    "messageId": "FjSY1y3L...",
    "originatingSystemId": "AGENT_SDK",
    "originalMessageId": "M2"
  },
  {
    "originatingSystemId": "AGENT_SDK",
    "originalMessageId": "M1",
    "diagnostic": "500 : {\"status\":\"INTERNAL_SERVER_ERROR\"}"
  }
]