Relativity's short message format

Relativity has created a Viewer experience to help you review and produce short message data similar to a conventional document. Among the many file types you're able to ingest into your Relativity environment is Relativity's short message format (RSMF). An RSMF file is an RFC 5322 (Internet Message Format) standards compliant file that encapsulates normalized short message data. The data can come from text messages like SMS or Apple iMessage or it can come from instant messenger services such as Skype, Bloomberg, Slack, etc.

To begin viewing short message data in Relativity, you must create a Relativity's short message format file (RSMF) from the database export of the chat platform you are collecting from. Relativity does not automatically convert raw exports of databases to RSMF.

Currently, Relativity provides developer tools to complete RSMF file creation. You may find partners on the Relativity App Hub that also offer RSMF creation services. To learn more, visit Creating an RSMF File.

Once you have created the RSMF files, you will need to stage them to be processed into Relativity. RelativityOne users must use the Staging Explorer, while Server users can point to a local directory. To learn more, visit RelativityOne Staging Explorer.

Finally, you will need to either use Relativity Processing or import the attachments separately and overlay the relationship to ingest an RSMF file into Relativity in order for attachments to display in-line in our Short Message Viewer, and to ensure those attachments are associated with the correct messages. To learn more, visit Processing an RSMF file.

See these related pages:

New RSMF 2.0 functionality

Starting in Relativity 12.1.2, the Short Message Viewer and Short Message Image Viewer fully support updates made to the Relativity's short message format, also known as, RSMF 2.0. These updates are intended to continue to enrich the data captured within RSMF, as well as ensure that Relativity's short message format continues support for key features of many chat platforms. RSMF 2.0 and RSMF 1.0 are compatible with Relativity, though RSMF 2.0 is recommended because it offers superior functionality. The following features are available in RSMF 2.0:

Added support for read receipts.
Added support for the direction of each message sent.
Added support for history events, which in some chat platforms indicate if someone reviewed previous communication with the chat after a message was received.
Increased support for custom platform icons beyond what Relativity supports out of the box.
The Short Message Viewer and Short Message Image Viewer have also been updated to properly handle sparse data scenarios, particularly for mobile data.

Requirements for RSMF Head and Body

Note: The RSMF 2.0 headers, X-RSMF-Application, X-RSMF-Custodian, X-RSMF-Participants, X-RSMF-AttachmentCount, X-RSMF-EventCollectionID, are supported and extracted but they cannot be mapped to standalone fields in Server 2022 or Server 2023.

Relativity's short message format is essentially the RSMF.zip, which is wrapped in a traditional EML file, which includes a body and a header. The header has one required field and the others are optional.

Header	Required in RSMF 1.0	Required in RSMF 2.0	Description
X-RSMF-Version	Yes	Yes	The version of the RSMF specification that the file adheres to.
X-RSMF-Generator	No	No	Identifies the author of the RSMF file.
X-RSMF-BeginDate	No	No	The timestamp (ISO8601) of the earliest short message event within the file.
X-RSMF-EndDate	No	No	The timestamp (ISO8601) of the latest short message event within the file.
X-RSMF-EventCount	No	No	The number of short message events captured within the file.
X-RSMF-Application	Unavailable in RSMF 1.0	No	This is used to identify source of the data, which is intended to be ambiguous. For example, it could be the platform/app of the data contained in the RSMF file. The intent with this field is to allow for better sorting of messages in the document list via a long text field.
X-RSMF-Custodian	Unavailable in RSMF 1.0	No	This field is used to identify from whom the data was collected from. The intent with this field is to allow for better sorting of messages in the document list via a long text field.
X-RSMF-Participants	Unavailable in RSMF 1.0	No	This field can be used to identify a string of names that are present in the conversation in the RSMF file. The intent with this field is to allow for better sorting of messages in the document list via a long text field.
X-RSMF-AttachmentCount	Unavailable in RSMF 1.0	No	This field should be a number that is a sum of all of the attachments present in the RSMF. The intent with this field is to allow for better sorting of messages in the document list via a long text field.
X-RSMF-EventCollectionID	Unavailable in RSMF 1.0	No	This field should be a unique ID that is to be used to help keep many RSMFs from a single conversation together. The intent with this field is to allow for better sorting of RSMFs in a document list to group parent RSMFs to the same conversation, if conversations/RSMFs are broken up for review purposes prior to being put into Relativity.

The EML body can contain any text. This text will display in the Extracted Text Viewer. Any message text should be added here. Other events in the Extracted Text Viewer (that are not messages), such as conversations, names of attachments, etc. can be added here as well. The Extracted Text Viewer does not automatically populate with text or variables from the Native Viewer.

Requirements for rsmf.zip

The rsmf.zip attachment is where the detailed short message data resides. It must contain at least a single manifest file named rsmf_manifest.json at the root level, but it may also contain any number of additional files which may be referenced from within the manifest file. Additional files, such as attachments and avatars, are required to be at the root level as well.

Note: If a container file or files are included in the rsmf.zip file, you cannot open or interact with them in the Short Message Viewer. To see a list of container files, visit Supported file types for processing.

The rsmf.zip file must be a ZIP attachment that uses DEFLATE compression and must not leverage ZIP encryption.

Example RSMF file

The following code sample shows an RSMF file that includes all information required before it is ingested using Processing.

X-RSMF-Version: 2.0.0
X-RSMF-Generator: Relativity
X-RSMF-BeginDate: 2010-02-18T10:05:11.0000000Z
X-RSMF-EndDate: 2011-01-26T13:33:20.0000000Z
X-RSMF-EventCount: 4662
To: Keith Kaminski, Karl Knoernschild, Jim Witte
Content-Type: multipart/mixed; boundary="_RSMF_Boundary_Delimiter_"
MIME-Version: 1.0
 
 
--_RSMF_Boundary_Delimiter_
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
 
You there?
Yeah.
 
 
 
--_RSMF_Boundary_Delimiter_
Content-Type: application/zip; name="rsmf.zip"
Content-Disposition: attachment; filename="rsmf.zip"
Content-Transfer-Encoding: base64
 
                   BASE64 encoded RSMF.ZIP goes here
 
 
--_RSMF_Boundary_Delimiter_--

rsmf_manifest.json file

The rsmf_manifest.json file is a JSON file that describes short message activity. The root of a manifest file has a version, a list of participants, a list of conversations, and a list of events.

{  
   "version":"2.0.0",
   "participants":"...",
   "conversations":"...",
   "events":"..."
}

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Description
version	Yes	Yes	string	The version of the RSMF specification that the file adheres to.
participants	Yes	Yes	array	An array of participants. A participant is someone who has participated in at least one of the conversations described in the manifest. See Participants for more details.
conversations	Yes	Yes	array	An array of conversations. A conversation is a time-bound set of short message events that occur on a specific platform, such as Slack, Bloomberg, or SMS. See Conversations for more details.
events	Yes	Yes	array	An array of events. An event is any discrete activity that can happen within the confines a conversation. See Events for more details.
eventcollectionid	Unavailable in RSMF 1.0	No	string	This field should be a unique ID that is used to help keep many RSMFs from a single conversation together. The intent with this field is to allow for better sorting of RSMFs in a document list to group parent RSMFs to the same conversation, if conversations/RSMFs are broken up for review purposes prior to being put into Relativity.

Participants

A participant is someone who has participated in at least one of the conversations described in the manifest file. At least one participant is required for an RSMF file to be valid.

[  
   {  
      "id":"P1",
      "display":"Keith Kaminski",
      "avatar":"kk.png",
      "email":"keith.kaminski@relativity.com",
      "custom":[  
         {  
            "name":"Employer",
            "value":"Relativity"
         },
         {  
            "name":"Department",
            "value":"Engineering"
         }
      ]
   }
]

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Description
id	Yes	Yes	string	Uniquely identifies a participant within the manifest file.
display	Yes	No	string	Display value for the participant.
avatar	No	No	string	The name of a file within the rsmf.zip, including any extension that contains an image to display for the avatar for the participant.
email	No	No	string	The primary email address of the participant.
account_id	Unavailable in RSMF 1.0	No	string	The primary ID that distinguishes the participant in that application. For example, this could be a phone number for texts or handles for social media.
custom	No	No	object	An array of optional name/value objects that can be used to store additional metadata about the participant.

Conversations

A conversation is a time-bound set of short message events that occur on a specific platform, such as Slack, Bloomberg, or SMS. Conversations either have a fixed set of participants for their entire duration, such as with SMS messages, or can change over time, such as with a Slack channel or Bloomberg room. At least one conversation is required for an RSMF file to be valid.

[  
   {  
      "id":"C1",
      "display":"Keith and Karl",
      "platform":"SMS",
      "type":"direct",
      "participants":[  
         "P1",
         "P2"
      ],
      "custom":[  
         {  
            "name":"Source",
            "value":"Keith's iPhone"
         }
      ]
   }
]

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Description
id	Yes	Yes	string	Uniquely identifies a conversation within the manifest file.
display	Yes	No	string	Display value for the conversation.
platform	Yes	Yes	string	The name of the messaging platform from which the conversation originated.
type	Yes	Yes	string	The type of the conversation. Valid values are: "direct" "channel" "direct": Indicates the participants are fixed for the duration of the conversation. "channel": Indicates that participants may enter and leave the conversation at various points in time.
participants	Yes	No	array	The participants included in the conversation. Each participant must map back to the id of a participant defined in the root of the manifest. The participant list has different meanings depending the type of the conversation: When the type is "direct", this indicates all of the participants that took part in the conversation. When the type is "channel", this indicates only the participants who were in the conversation at the time of the earliest event for that conversation within the manifest file.
custodian	Unavailable in RSMF 1.0	No	string	The id of a participant who was the source of the conversation. This must map back to one of the participants in the conversation.
custom	No	No	object	An array of optional name/value objects that can be used to store additional metadata about the conversation.
icon	Unavailable in RSMF 1.0	No	string	The name of a file within the rsmf.zip, including any extension, that contains an image to display for the icon for the conversation. We expect this icon to be the logo for the platform the data was pulled from. The recommended image size for an icon is no larger than 28 by 28 pixels, and it should be either a PNG or JPEG file. Note: Custom icons are not currently supported in the Short Message Viewer.

Events

An event is a discrete activity that can happen within the confines a conversation, such as a message or a join/leave notification. At least one event is required for an RSMF file to be valid.

[
   {
      "id":"m2",
      "type":"message",
      "parent":"m1",
      "body":"Looks good!",
      "participant":"P1",
      "conversation":"C1",
      "deleted":false,
      "importance":"normal",
      "timestamp":"2018-09-11T09:55:00Z",
      "reactions":[
         {
            "value":"thumbs up",
            "count":2,
            "participants":[
               "P1",
               "P2"
            ]
         }
      ],
      "attachments":[
         {
            "id":"partyon.png",
            "display":"partyon.png",
            "size":4254
         }
      ],
      "edits":[
         {
            "participant":"P1",
            "timestamp":"2018-09-12T12:53:00Z"
         }
      ],
      "custom":[
         {
            "name":"GPS",
            "value":"41 24.2028, 2 10.4418"
         }
      ]
   }
]

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Description
id	No	No	string	Uniquely identifies an event within the conversation. An event only needs to have an identifier if it is part of a thread.
type	Yes	Yes	string	Defines the type of event. Valid values are: "message" "disclaimer" "join" "leave"
parent	No	No	string	Identifies the parent event of the event. This needs to be set if the event is a message which is a part of a thread. Parent must map back to the id of another event.
body	No	No	string	Content associated with the event. Not all event types require a body. For a message type, this would be the text of the message. If not included, the default value is assumed to be an empty string.
participant	Yes	No	string	The participant that is the source of the event. This must map to the id of a participant defined in the root of the manifest.
timestamp	Yes	No	string	The timestamp (ISO8601) of when the event occurred.
conversation	Yes	No	string	Identifies the conversation in which the event occurred. This must map back to the id of a conversation.
deleted	No	No	bool	Identifies whether a message has been deleted. If not included, the default value is assumed to be false.
importance	No	No	string	Sets an importance value for the message. Valid values are: "normal" "high" If not included, the default value is assumed to be "normal".
reactions	No	No	array	An array of reactions associated with the event. See the Reaction section for more information.
attachments	No	No	array	An array of attachments associated with the event. See the Attachment section for more information.
edits	No	No	array	An array of edits that have been made to the event. See the Edits section for more information.
custom	No	No	object	An array of optional name/value objects that can be used to store additional metadata about the event.
direction	Unavailable in RSMF 1.0	No	string	Valid strings of 'incoming' and 'outgoing', which helps reviewers understand whose device this information was collected from, relative to the custodian.
read_receipts	Unavailable in RSMF 1.0	No	array	An array of read receipts associated with the event. See the Read_receipts section below for more details.

Reaction

[
			{
			"reactions":[
			{
			"value":"",
			"count":2,
			"participants":[
			"P1",
			"P2"
			]
			}
			],
		]

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Descriptions
value	Yes	Yes	string	Identifies the reaction. The maximum length for a reaction is 30 characters. To render the reaction in the Viewer, use either short code or unicode values to represent the reaction.
count	Yes	No	whole number	The number of times this reaction was added to the event.
participants	Yes	No	array	Identifies the participants that used the reaction. Each participant must map back to the id of a participant defined in the root of the manifest.

Attachment

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Descriptions
id	Yes	Yes	string	Identifies the attachment. The value should correspond to the name of a file within the rsmf.zip, including any extension.
display	Yes	No	string	Display value for the attachment. Relativity renders attachments based on the extension of the display value of an attachment.
size	Yes	No	whole number	The size of the file in bytes.

Edits

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Description
participant	Yes	Yes	string	The participant that made the edit. This must map to the id of a participant defined in the root of the manifest.
timestamp	Yes	No	string	The timestamp (ISO8601) of when the edit occurred.
previous	Unavailable in RSMF 1.0	No	string	The value of the previous body that was changed due to the edit.
new	Unavailable in RSMF 1.0	No	string	The value of the new body once the edit was made.

Read_receipts

Name	Required in RSMF 1.0	Required in RSMF 2.0	Type	Description
participant	Unavailable in RSMF 1.0	Yes	string	The participant that made the action. This must map to the id of a participant defined in the root of the manifest.
timestamp	Unavailable in RSMF 1.0	No	string	The timestamp (ISO8601) of when the edit occurred.
action	Unavailable in RSMF 1.0	No	string	If the recipient was delivered the message, and/or read the message. Valid values include "read", "delivered". If participant is seen twice but has different "action" strings, we'll display the 'read' icon, but that contains details when it was delivered to them. For example, in Whatsapp and FB Messenger, there is data to denote that a message was delivered to the recipient, and when it was read by the recipient. Because the message being ‘read’ is more significant, in the Short Message Viewer we would only show the recipient’s read status.

Name

Required in RSMF 1.0

Required in RSMF 2.0

Type

Description

participant

Unavailable in RSMF 1.0

Yes

string

The participant that made the action. This must map to the id of a participant defined in the root of the manifest.

timestamp

Unavailable in RSMF 1.0

string

The timestamp (ISO8601) of when the edit occurred.

action

Unavailable in RSMF 1.0

string

If the recipient was delivered the message, and/or read the message.

Valid values include "read", "delivered".

If participant is seen twice but has different "action" strings, we'll display the 'read' icon, but that contains details when it was delivered to them.

For example, in Whatsapp and FB Messenger, there is data to denote that a message was delivered to the recipient, and when it was read by the recipient. Because the message being ‘read’ is more significant, in the Short Message Viewer we would only show the recipient’s read status.