Conversation archiving fundamentals

Conversations

In the context of this API, a ‘conversation’ is a time-bounded series of events that occur on a specific messaging platform, e.g. Global Relay App, for capture in the Archive.

The most common scenario is the sending of text-based messages between users. However, a ‘conversation’ can also be captured when a user creates a messaging channel or invites new users to a conversation, even if no messages are sent between participants.

Understanding the key resources

There are 3 key resources in the Conversation payload you send in an API request:

Conversation Overview

This consists of metadata about the conversation:

• conversationType: Provided to you during enrolment by your Global Relay Implementation engineer, this identifies the data type being archived.
• initiator: User who created the conversation.
• initialParticipants: Initial participants who were able to receive messages from the start of the conversation. For more details about conversation initiators, see the Glossary.
• title, description (optional): Provides a description of the conversation.
• Other conversation properties, e.g. the conversation administrators, whether the conversation was public or private, and your own custom metadata if required.

Conversation Events

These represent the messages sent and events conducted by users in the conversation, such as file sharing or participant changes. Each conversation must have at least one event.

Each conversationEvent must include:

• eventTime: When it happened
• participants: Who was involved
• eventType: The type of event

A subset of these event types, e.g. file transfers and messages, support additional information, such as message content, files, reactions, etc.

Request Info

In the Request Info object, provide a unique ID (UUID), which you can use for tracking purposes.

For more information about the Conversation payload, refer to the API reference.

Time-bounding the conversation

You can decide the frequency with which you capture your conversations for archiving. 

There are a few factors to consider when making this decision in your application:

• Every request you send will be archived as a separate Archive message.
• To link separate, related Archive messages to a single conversation, use the conversationId field in all applicable requests. This groups all applicable Archive messages to the full conversation, saving time for Archive users when searching.
• Each request you send should contain events which span a timeframe no longer than 24 hours.

Therefore, we suggest adopting one of the following approaches:

Approach	Logic	Result
Activity-based	Decide a time value for inactivity, e.g. 30 minutes, 1 hour, which indicates the ‘end’ of a conversation. After conversation events have occurred and the inactive period is reached, send an API request with all the preceding conversation events since the last call was sent.	In the Archive, your data accurately represents the start and end of conversations based on user activity.
Fixed-time window	Collect all the conversation events in a fixed period, e.g. 4 hours, but no longer than 24 hours, and send them in a single API request at the end of that period. If there are no events, do not send an API request.	The logic for your application is simpler.

Grouping conversations across API requests

If needed, you can reuse the same conversationId in subsequent API requests, so your data displays as a single, sequential conversation in the Archive.

Ultimately, when a conversation starts and ends should be based on your compliance and eDiscovery requirements.

For example, this is the first payload you send for a conversation:

"requestInfo": {
    "requestId": "2c8d4927-433c-4e9a-bf02-ead2f17d1ef2"
 }
"conversationOverview": {
    //
   "conversationId": "1fbbfbe2-aaaa-bbbb-cccc-2c7bf053fb23"
    //
}

If you determine that the conversation continued after the first API request was sent, you should send another request with a different requestId, but the same conversationId:

"requestInfo": {
    "requestId": "f8bd53a8-3b72-11ee-be56-0242ac120002"
 }
"conversationOverview": {
    //
   "conversationId": "1fbbfbe2-aaaa-bbbb-cccc-2c7bf053fb23"
    //
}

Tracking your requests

When sending a request to the POST /conversations endpoint, you must include a UUID in the requestId field, which identifies this specific API request. The requestId is visible in the Archive when viewing the related conversation data, and we log it for data reconciliation purposes, so you should send a unique value in each request.

"requestInfo": {
    "requestId": "2c8d4927-433c-4e9a-bf02-ead2f17d1ef2"
 }

Refer to RFC 4122 for information on the UUID standard.

For all successful API requests, you receive a randomly-generated reconciliationId in the response, which is mapped to the requestId in Global Relay’s system.

Describing your conversations

You can populate your conversation title and description fields, which display in a summary table for your conversation in the Archive.

For group chats, you can leverage the name and description of the group from the originating messaging platform, e.g. Global Relay App. For one-to-one conversations, titles and descriptions are less applicable.

Identifying conversation visibility to users

To indicate the visibility and scope of a conversation, you can include the following Boolean-value fields in the conversationOverview object:

• isExternal: The conversation included participants from other companies.
• isPrivate: Only participants who were invited could join the conversation; otherwise, the conversation content is hidden.

Including additional metadata for your conversations

You can use the conversationProperties key/value pair object to capture any additional metadata about a conversation.

This is useful if you need to capture information which isn’t otherwise represented in the conversation payload. For example, you might want to capture geographical data, the timezone of the conversation participants, or the devices being used.

You can view and search for the data included in this object on messages in the Archive.

Understanding conversation size limits

For the /conversations endpoint, the maximum volume of data you can send in a single request is 3.5MB – this does not include file attachments, which are sent to the /files endpoint. For a typical conversation payload, 3.5MB equals approximately 7,000 messages, so it’s unlikely you’ll reach the limit.

If you exceed 3.5MB, the API returns a 413 error.

When Global Relay receives your data, it is transformed into our Archive message format for optimal indexing. In the rare instance the combined size of the conversation text, metadata, and file attachments exceeds 2GB, the conversation is split into multiple Archive messages. For more information on archiving attachments, see Archiving file attachments.

To locate all the Archive messages for a conversation in the Archive, conduct an Archive header search using the conversationId you provided in the payload.