Conversation actors

Identifying who created the conversation

Depending on the type of conversation, you can populate its creator in the createdBy field as follows:

Conversation scenario	Creator
One-to-one private conversation	The user who sent the first message, or leave blank
Multi-party conversation	The user or system that created the conversation
Private group/channel conversation	The user or system that created the group/channel

The optional createdBy value can be populated with any string identifier, which displays in the conversation’s summary table in the Archive.

For example:

“jordan.davies@greenvaultcapital.com”

“Jordan Davies (jordan.davies@greenvaultcapital.com)”

“Jordan Davies (Green Vault Capital)”

Identifying who initiated the conversation

You can identify the initiator in the values you use for initiatorName and initiatorEmail, which are used to populate the From field of the message in the Archive.

The initiator of a conversation can be either:

• The group or channel name/identifier.
• The participant who initiated the first event in the current conversation, e.g. sent a message, uploaded a file, etc.

Using the group or channel name/identifier as initiator

For example, on the messaging platform ‘YourChat’, in a group named ‘All Staff’ initially created by Jordan, where Lisa sends a message to start the conversation, you could send:

{
  "conversationOverview": {
    "createdBy": "jordan.davies@greenvaultcapital.com",
    "createdAt": 1621851918000,
    "initiatorEmail": "n/a",
    "initiatorName": "YourChat:GROUP:All Staff"
  }
}

Lisa would be included in the ConversationOverview.initialParticipants alongside all other members of the group.

In the Archive, the initiatorName you choose will be used to populate the “From” field, and Lisa will be listed as a participant.

Using the participant who initiated the first event as initiator

Alternatively, you could identify Lisa, the conversation starter, as the initiator, and send:

{
   "conversationOverview":{
      "createdBy":"jordan.davies@greenvaultcapital.com",
      "createdAt":1621851918000,
      "initiatorEmail":"lisa.holmes@greenvaultcapital.com",
      "initiatorName":"Lisa Holmes"
   }
}

In the Archive, Lisa will be listed in the “From” field.

Identifying conversation participants

Populate the ConversationOverview.initialParticipants object to indicate all users who could see messages in the conversation when it started, including the initiator.

Users who join after the conversation has started are captured through the relevant conversationEvent. For more information, see Changing participants in a conversation.

{
   "conversationOverview":{
      "initiatorEmail":"jordan.davies@greenvaultcapital.net",
      "initiatorName":"Jordan Davies",
      "initialParticipants":[
         {
            "displayName":"Jordan Davies",
            "corporateEmail":"jordan.davies@greenvaultcapital.net"
         },
         {
            "displayName":"Lisa Holmes",
            "corporateEmail":"lisa.holmes@greenvaultcapital.net"
         }
      ]
   }
}

For example, if Jordan starts a one-to-one conversation with Lisa, both users are included in the initialParticipants:

For a multi-party conversation, follow the same rule and include all the active conversation recipients as initialParticipants, identifying the first message sender as the “initiator”.

When viewing conversations in the Archive, the participants list, which also includes all users who join in a subsequent conversationEvent, indicates all the users who received any messages sent in the conversation.

Glossary of actors

Participant

Any user directly or indirectly involved in a conversation, either as a recipient or the initiator of a conversation event. Participants can also be identified in a conversation in relation to a conversationEvent indicated with a userType of “initiator” or “affectedUser” in the event.

initialParticipants are those who were able to receive messages and/or other events in the conversation when it started. It’s possible a user was not mentioned in the list of initialParticipants, but is later added through a subsequent conversationEvent, such as joining the group after the conversation started.

Initiator

There are two types of initiators in a conversation:

• In the context of the ConversationOverview, this is the user who created the conversation and is used to populate the From field for the Archive message. The initiator can also be the name/identifier of the group/channel itself.
• In the context of a specific conversationEvent, this is the user who initiated the event, e.g. sent a message, joined a conversation, etc.

Admin

For applicable conversation types, this is the administrator of the conversation, who has an elevated set of privileges such as being able to add/remove users.

Owner

For conversations with participants from multiple companies, the owner refers to the company, e.g. Lautner Wealth, the conversation initiator belongs to.

Creator

This is the user or system that first created the group or channel in which the conversation takes place.