Conversation
Provides API to manage a conversation.
Methods
addParticipants
addParticipants(participants: ): Promise<ConversationEventPayload>
Adds new participants to the conversation.
This operation is allowed only if:
- All participants act as users who use the Voximplant developer account or its child accounts
- The current user has permission to manage participants (ConversationParticipant.canManageParticipants is true)
- The conversation is either public or uber (Conversation.isDirect is false)
Duplicate users are ignored. Throws MessengerError if any specified user does not exist or is already a participant of the conversation.
You can use the MessengerEventType.onEditConversation event to notify the participants (online or logged-in) that a new participant has been added to the conversation.
Returns a promise that resolves to a ConversationEventPayload object containing the updated data.
Parameters
participants:
Array of participants to add. Should not be empty
Returns
type:
Promise<ConversationEventPayload>
Throws
edit
edit(options: ): Promise<ConversationEventPayload>
Sends changes made to the conversation to the cloud. Supported changes are: title, public join flag, and custom data.
The participant has to be the conversation owner for the update to succeed (ConversationParticipant.isOwner is true).
You can use the MessengerEventType.onEditConversation event to notify the participants (online or logged-in) that conversation title, custom data, or public join status have changed.
Returns a promise that resolves to a ConversationEventPayload object containing the updated conversation data.
Parameters
options:
Conversation changes
Returns
type:
Promise<ConversationEventPayload>
Throws
editParticipants
editParticipants(participants: ): Promise<ConversationEventPayload>
Edits the permissions of participants in the conversation.
This operation is allowed only if the current user has permission to manage participants (ConversationParticipant.canManageParticipants is true).
Duplicate participants are ignored. Throws MessengerError if any specified user does not exist or is not a participant.
You can use the MessengerEventType.onEditConversation event to notify the participants (online participants or logged in user clients) of permission changes in the conversation.
Returns a promise that resolves to a ConversationEventPayload object containing the updated data.
Parameters
participants:
Array of participants whose permissions to update. Should not be empty
Returns
type:
Promise<ConversationEventPayload>
Throws
markAsRead
markAsRead(sequence: number
): Promise<ConversationServiceEventPayload>
Marks the event with the specified sequence as read.
Calling this method with a sequence number updates ConversationParticipant.lastReadEventSequence to that value, allowing each participant to track their own read state of messages by retrieving event sequences independently.
If the sequence number is -1 or 0, all events are marked as unread for this participant, except the event with sequence number 1.
You can use the MessengerEventType.isRead event to notify the participants (online participants or logged in user clients) of the read status change for the messages in the conversation.
Returns a promise that resolves to a ConversationServiceEventPayload object containing the updated data.
Parameters
sequence:
number
The sequence number of the event to mark as read. Should not exceed the current maximum sequence
Returns
type:
Promise<ConversationServiceEventPayload>
Throws
removeParticipants
removeParticipants(participants: ): Promise<ConversationEventPayload>
Removes participants from the conversation.
This operation is allowed only if:
- The current user has permission to manage participants (ConversationParticipant.canManageParticipants is true)
- The conversation is either public or uber (Conversation.isDirect is false)
Duplicate participants are ignored.
Throws MessengerError if any specified user does not exist or is not a participant.
Note: You can also remove participants that are marked as deleted (User.isDeleted is true).
Removed users can later retrieve the UUID of this conversation's via the User.leaveConversationList method.
You can use the MessengerEventType.onEditConversation event to notify the participants (online participants or logged in user clients) that a participant has been removed from the conversation.
Returns a promise that resolves to a ConversationEventPayload object containing the updated data.
Parameters
participants:
Array of participants to remove. Should not be empty
Returns
type:
Promise<ConversationEventPayload>
Throws
retransmitEvents
retransmitEvents(eventsFrom: number
, eventsTo: number
): Promise<RetransmitEventPayload>
Requests a range of events to be retransmitted from the cloud to this client.
See RetransmittableEvents type for the events that can be retransmitted.
This method is used to retrieve message history or obtain missed events after a network failure. Use the last event sequence received from the cloud and the last sequence saved locally (if any) to set the appropriate event range.
The maximum number of events per request is 100. Requesting more than 100 events throws MessengerError.
If the current user has left an uber conversation (Conversation.isUber is true), messages sent in the conversation after their leave and before they re-join are not retransmitted.
Returns a promise that resolves to a RetransmitEventPayload object containing the requested events.
Parameters
eventsFrom:
number
The first event in the in the range (inclusive)
eventsTo:
number
The last event in the range (inclusive)
Returns
type:
Promise<RetransmitEventPayload>
Throws
retransmitEventsFrom
retransmitEventsFrom(eventsFrom: number
, count: number
): Promise<RetransmitEventPayload>
Requests a specified number of events starting from a given sequence to be retransmitted from the cloud to this client.
See RetransmittableEvents type for the events that can be retransmitted.
This method is used to retrieve message history or obtain missed events after a network failure. Use the last event sequence received from the cloud and the last sequence saved locally (if any) to set the first event in the range.
The maximum number of events per request is 100. Requesting more than 100 events throws MessengerError.
If the current user has left an uber conversation (Conversation.isUber is true), messages sent in the conversation after their leave or before they re-join are not retransmitted.
The result includes the maximum number of available events for the current user up to the requested count, even if fewer events are available.
Returns a promise that resolves to a RetransmitEventPayload object containing the requested events.
Parameters
eventsFrom:
number
The first event in the range (inclusive)
count:
number
The maximum number of events to retrieve (up to 100)
Returns
type:
Promise<RetransmitEventPayload>
Throws
retransmitEventsTo
retransmitEventsTo(eventsTo: number
, count: number
): Promise<RetransmitEventPayload>
Requests up to a specified number of events ending at a given number to be retransmitted from the cloud to this client.
See RetransmittableEvents type for the events that can be retransmitted.
See RetransmittableEvents type for the complete list of events that can be retransmitted.
This method is used to retrieve message history or obtain missed events after a network failure. For the clients, use this method to obtain all events based on the last event sequence received from the cloud and the last sequence saved locally (if any).
The maximum number of retransmitted events per method call is 100. Requesting more than 100 events causes MessengerError.
If the current user has left an uber conversation (Conversation.isUber is true), messages sent in the conversation after their leave or before they rejoin are not retransmitted. The result includes the maximum number of available events up to the requested count, even if fewer events are available.
Returns a promise that resolves to a RetransmitEventPayload object containing the requested events.
Parameters
eventsTo:
number
The last event sequence in the range (inclusive)
count:
number
The maximum number of events to retrieve (up to 100)
Returns
type:
Promise<RetransmitEventPayload>
Throws
sendMessage
sendMessage(options: ): Promise<ConversationMessageEventPayload>
Sends a message to the conversation.
This operation is allowed only if participants have write permission (ConversationParticipant.canWrite is true).
You can use the MessengerEventType.onSendMessage event to notify the participants (online participants or logged in user clients) of new messages sent to the conversation.
Returns a promise whose fulfillment handler receives ConversationMessageEventPayload object with the updated data.
Parameters
options:
Message content
Returns
type:
Promise<ConversationMessageEventPayload>
Throws
typing
typing(): Promise<null | ConversationServiceEventPayload>
Informs the cloud that the user is typing a message.
You can use the MessengerEventType.onTyping event to notify the participants (online participants or logged in user clients) of typing activity in the conversation.
Returns a promise that resolves to a ConversationServiceEventPayload object containing the updated data, or
null
if no update is needed.
Returns
type:
Promise<null | ConversationServiceEventPayload>
Throws
Props
createdTime
createdTime: number
UNIX timestamp (seconds) that specifies the creation time of the conversation.
customData
customData: null | UnknownObject
Custom data associated with the conversation (up to 5 KB).
isDirect
isDirect: boolean
Whether the conversation is direct or public.
A direct conversation is a private conversation established between exactly two users. This conversation is not shared with other users. Only one direct conversation can exist between the same two users. If one of the users attempts to create a new direct conversation with the same user (Messenger.createConversation), the method returns the UUID of the existing direct conversation. A direct conversation is always private and never is public or uber.
isPublicJoin
isPublicJoin: boolean
Whether the conversation is public.
In public conversations, any user can join the conversation by specifying the UUID of the conversation they join.
A public conversation cannot be direct.
isUber
isUber: boolean
Whether the conversation is uber.
In uber conversations, users cannot receive messages sent to the conversation after they leave.
An uber conversation cannot be direct.
lastSequence
lastSequence: number
Sequence of the last event in the conversation.
lastUpdateTime
lastUpdateTime: number
UNIX timestamp (seconds) indicating the last time when either of the following events has been triggered in the conversation:
participants
participants: Array of conversation participants, including their permissions.
title
title: string
The conversation title.
uuid
uuid: string
Universally unique identifier (UUID) of this conversation.