Capturing sent messages in conversations
All the events that occur in a conversation, including messages sent by users, are represented in the API as conversationEvents.
When making a request to the API, use the “Message” eventType to archive this type of data.
For one-to-one conversations or group chats with messages sent to all participants, you must specify the user, time, and contents of the sent message:
{
"conversationEvents": [
{
"eventTime": 1621851918000,
"eventType": "Message",
"participants": [
{
"displayName": "Jordan Davies",
"corporateEmail": "jordan.davies@greenvaultcapital.com",
"userType": "initiator"
}
],
"content": {
"message": "Good morning!"
}
}
]
}This shows only a subset of information you can send in such a request. For example, you can also include data for other fields, e.g. accountId and companyName, for participants. For more information, see the API Reference.
In this case, you do not need to specify the recipients of the message, because it is assumed that all ConversationOverview.initialParticipants received the message. For more information, see Identifying conversation participants.
Replying to a specific message
If a user replies to a specific message, creating a separate thread outside the main conversation, you should represent this in the API payload with nested child events. The child event should be the message the user is replying to, and the parent event is the reply itself.
Each reply to the same message should be represented as a separate ConversationEvent. The original message uses the “Message” eventType, and the reply uses “Context_reply”.
For example, if Lisa replies to Jordan’s message, i.e. “Good morning!”, with a message, i.e. “Hi, Jordan”, send the following payload:
{
"conversationEvents": [
{
"eventTime": 1621852216000,
"eventType": "Context_reply",
"participants": [
{
"displayName": "Lisa Holmes",
"corporateEmail": "lisa.holmes@greenvaultcapital.com",
"userType": "initiator"
}
],
"content": {
"message": "Hi, Jordan"
},
"childEvents": [
{
"eventTime": 1621851918000,
"eventType": "Message",
"participants": [
{
"displayName": "Jordan Davies",
"corporateEmail": "jordan.davies@greenvaultcapital.com",
"userType": "initiator"
}
],
"content": {
"message": "Good morning!"
}
}
]
}
]
}
The Conversation Archiving API supports up to 3 levels of nested replies. However, we recommend submitting each reply as a single event – i.e. the reply itself and the message being replied to – to improve the discovery of these events in the Archive.
Reacting to messages
If users react to a message, you can send the “Reaction” eventType with systemText to describe the reaction. You determine how to describe each reaction, so it makes sense to reviewers viewing conversations in the Archive.
Similar to replying to a specific message, you must create a childEvent for the message being reacted to:
{
"conversationEvents": [
{
"eventTime": 1621852216000,
"eventType": "Reaction",
"systemText": "Liked the message",
"participants": [
{
"displayName": "Raj Patel",
"corporateEmail": "raj.patel@greenvaultcapital.com",
"userType": "initiator"
}
],
"childEvents": [
{
"eventTime": 1621851918000,
"eventType": "Message",
"participants": [
{
"displayName": "Jordan Davies",
"corporateEmail": "jordan.davies@greenvaultcapital.com",
"userType": "initiator"
}
],
"content": {
"message": "Good morning!"
}
}
]
}
]
}
Editing sent messages
If your messaging platform supports editing already sent messages, you can use the “Message_edited” eventType.
The new, edited message is sent as the parent event, while the original message is sent as a childEvent:
{
"conversationEvents": [
{
"eventTime": 1621852216000,
"eventType": "Message_edited",
"participants": [
{
"displayName": "Lisa Holmes",
"corporateEmail": "lisa.holmes@greenvaultcapital.com",
"userType": "initiator"
}
],
"content": {
"message": "Good morning!"
},
"childEvents": [
{
"eventTime": 1621851918000,
"eventType": "Message",
"participants": [
{
"displayName": "Lisa Holmes",
"corporateEmail": "lisa.holmes@greenvaultcapital.com",
"userType": "initiator"
}
],
"content": {
"message": "good moring!"
}
}
]
}
]
}
