Changes to participants in a conversation

Inviting new users to a conversation

Certain chat platforms require users to accept an invitation to a group chat before they can participate. As a result, the act of joining is a separate conversationEvent from the invitation itself. The Conversation Archiving API supports this with 2 eventTypes: “Invitation” and “User_joined”.

For an “Invitation” Event, identify the following participants with the relevant value in the userType field:

• Invitation recipients: “affectedUser”
• Invitation sender: “initiator”

In this example, Lisa has invited Jordan and Raj to the conversation:

{
  "conversationEvents": [
    {
      "eventTime": 1621851918000,
      "eventType": "Invitation",
      "participants": [
        {
          "displayName": "Lisa Holmes",
          "corporateEmail": "lisa.holmes@greenvaultcapital.com",
          "userType": "initiator"
        },
        {
          "displayName": "Jordan Davies",
          "corporateEmail": "jordan.davies@greenvaultcapital.com",
          "userType": "affectedUser"
        },
        {
          "displayName": "Raj Patel",
          "corporateEmail": "raj.patel@greenvaultcapital.com",
          "userType": "affectedUser"
        }
      ]
    }
  ]
}

Requesting to join a conversation

If your messaging platform allows users to request to join conversations, use the “User_event” value for the conversationEvent, and provide the specifics of the request using the systemText and content.message fields.

• For systemText, send a descriptive value to represent the action, e.g. “requested to join” or “asked to join”.
• For content.message, you can optionally include accompanying text the user sent when making the request.

For example, if Jordan requests to join a conversation by saying, “Hey, I think you forgot me?”, you can send the following:

{
  "conversationEvents": [
    {
      "eventTime": 1621851918000,
      "eventType": "User_event",
      "participants": [
        {
          "displayName": "Jordan Davies",
          "corporateEmail": "jordan.davies@greenvaultcapital.com",
          "userType": "initiator",
          "systemText": "Requested to join",
          "content": {
            "textType": "html",
            "message": "Hey, I think you forgot me?"
          }
        }
      ]
    }
  ]
}

Joining a conversation

When a user accepts an invitation to join a conversation or their request to join is accepted by the admins – and they can now see messages in that conversation – send the “User_joined” conversationEvent, where the user who joined is the initiator of that event.

One or multiple users can join at the same time, in the same conversationEvent.

{
  "conversationEvents": [
    {
      "eventTime": 1621851918000,
      "eventType": "User_joined",
      "participants": [
        {
          "displayName": "Lisa Holmes",
          "corporateEmail": "lisa.holmes@greenvaultcapital.com",
          "userType": "initiator"
        }
      ]
    }
  ]
}

Leaving a conversation

If a user voluntarily leaves a conversation, send the “User_left” eventType, where the user who left is the “initiator” of the event:

{
  "conversationEvents": [
    {
      "eventTime": 1621851918000,
      "eventType": "User_left",
      "participants": [
        {
          "displayName": "Lisa Holmes",
          "corporateEmail": "lisa.holmes@greenvaultcapital.com",
          "userType": "initiator"
        }
      ]
    }
  ]
}

Removing users from a conversation

When a user is removed from a conversation, send the “User_removed” conversationEvent, where the user, if known, who triggers the removal is the “initiator” and the removed user is the “affectedUser”:

{
  "conversationEvents": [
    {
      "eventTime": 1621851918000,
      "eventType": "User_removed",
      "participants": [
        {
          "displayName": "Lisa Holmes",
          "corporateEmail": "lisa.holmes@greenvaultcapital.com",
          "userType": "initiator"
        },
        {
          "displayName": "Lily Lee",
          "corporateEmail": "lily.lee@greenvaultcapital.com",
          "userType": "affectedUser"
        }
      ]
    }
  ]
}

Accompanying events with system text

For all Conversation Events, you can include accompanying text, which was shown to the participants of the conversation, by populating the systemText field.

For example, if users were shown text when Lily was removed from the previous conversation, send the following data:

{
  "conversationEvents": [
    {
      "eventTime": 1621851918000,
      "eventType": "User_removed",
      "systemText": "User was removed from the conversation."
      "participants": [
        {
          "displayName": "Lisa Holmes",
          "corporateEmail": "lisa.holmes@greenvaultcapital.com",
          "userType": "initiator"
        },
        {
          "displayName": "Lily Lee",
          "corporateEmail": "lily.lee@greenvaultcapital.com",
          "userType": "affectedUser"
        }
      ]
    }
  ]
}

The systemText will be visible to users viewing the conversation in Global Relay Archive.