Conversation
Class that represents a conversation. A Conversation instance is returned by the Messenger.createConversation and Messenger.createConversationFromCache methods. Provides methods to send messages, manage participants, receive conversation events history etc.
Methods
addParticipants
addParticipants(participants: ): Promise<EditConversationEvent>
Add new participants to the conversation. Duplicated users are ignored. Triggers the MessengerEvents.EditConversation event for all parties of the conversation (online participants and logged in clients). To get the result, use one of these options:
- Subscribe to the MessengerEvents.EditConversation event and provide a handler consuming an object with the EventHandlers.EditConversationEvent interface as a parameter. Remember that MessengerEvents.EditConversation may be triggered by another user and as a result of a number of other methods. So check 'messengerAction' and 'initiator' fields.
- Handle the returned promise. Though you still need to listen to MessengerEvents.EditConversation event to handle events from other parties. Rejects to a Messaging.MessengerError if
- at least one user does not exist or already belongs to the conversation,
- at least one participant is not a user of the main Voximplant developer account or its child accounts,
- the current user cannot manage other participants (see ConversationParticipant.canManageParticipants and ConversationParticipant.isOwner),
- the conversation is direct (see Conversation.direct).
Parameters
participants:
Returns
type:
Promise<EditConversationEvent>
editParticipants
editParticipants(participants: ): Promise<EditConversationEvent>
Change permissions for conversation participants. Duplicated users are ignored. This method does not add or remove participants. Use the Conversation.addParticipants and Conversation.removeParticipants methods instead. Triggers the MessengerEvents.EditConversation event for all parties of the conversation (online participants and logged in clients). To get the result, use one of these options:
- Subscribe to the MessengerEvents.EditConversation event and provide a handler consuming an object with the EventHandlers.EditConversationEvent interface as a parameter. Remember that MessengerEvents.EditConversation may be triggered by another user and as a result of a number of other methods. So check 'messengerAction' and 'initiator' fields.
- Handle the returned promise. Though you still need to listen to MessengerEvents.EditConversation event to handle events from other parties. Rejects to a Messaging.MessengerError if the current user cannot manage other participants (see ConversationParticipant.canManageParticipants).
Parameters
participants:
Returns
type:
Promise<EditConversationEvent>
markAsRead
markAsRead(seq: number
): Promise<ReadEvent>
Mark the event which has the specified sequence as read. This affects the current participant's ConversationParticipant.lastRead property and can be used to display unread messages. Triggers the MessengerEvents.Read event for all parties of the conversation (online participants and logged in clients). To get the result, use one of these options:
- Subscribe to the MessengerEvents.Read event and provide a handler consuming an object with the EventHandlers.ReadEvent interface as a parameter. Remember that MessengerEvents.Read may be triggered by another user, so check the 'initiator' field.
- Handle the returned promise. Though you still need to listen to MessengerEvents.Read event to handle events from other parties.
Parameters
seq:
number
Returns
type:
Promise<ReadEvent>
removeParticipants
removeParticipants(participants: ): Promise<EditConversationEvent>
Remove participants from the conversation. Duplicated users are ignored. Will fail if any user does not exist. Triggers the MessengerEvents.EditConversation event for all parties of the conversation (online participants and logged in clients). To get the result, use one of these options:
- Subscribe to the MessengerEvents.EditConversation event and provide a handler consuming an object with the EventHandlers.EditConversationEvent interface as a parameter. Remember that MessengerEvents.EditConversation may be triggered by another user and as a result of a number of other methods. So check 'messengerAction' and 'initiator' fields.
- Handle the returned promise. Though you still need to listen to MessengerEvents.EditConversation event to handle events from other parties. Rejects to a Messaging.MessengerError if:
- the current user cannot manage other participants (see ConversationParticipant.canManageParticipants),
- the conversation is direct (see Conversation.direct),
- at least one user does not exist or already removed to the conversation,
Parameters
participants:
Returns
type:
Promise<EditConversationEvent>
retransmitEvents
retransmitEvents(eventsFrom: number
, eventsTo: number
, count: number
): Promise<RetransmitEventsEvent>
Request events in the specified sequence range to be sent from the cloud to this client. Only MessengerEvents.CreateConversation, MessengerEvents.EditConversation, MessengerEvents.SendMessage and MessengerEvents.EditMessage events can be retransmitted; any other events cannot. The method is used to get history or missed events in case of network disconnect. Client should use this method to request all events based on the last conversation event sequence received from the cloud and last event sequence saved locally (if any). If the current user quits an uber conversation (see Conversation.uberConversation), messages that has been posted during the user's absence are not retransmitted later. The maximum number for requested events per method call is 100. Triggers multiple MessengerEvents.RetransmitEvents events (for each retransmitted event). To get the result, use one of these options:
- Subscribe to the MessengerEvents.RetransmitEvents event and provide a handler consuming an object with the EventHandlers.RetransmitEventsEvent interface as a parameter.
- Handle the returned promise (recommended). Rejects to a Messaging.MessengerError if more than 100 events are requested.
Parameters
eventsFrom:
number
First event in sequence range, inclusive
eventsTo:
number
Last event in sequence range, inclusive
count:
number
Optional
Returns
type:
Promise<RetransmitEventsEvent>
sendMessage
sendMessage(text: string
, payload: Object[]
): Promise<SendMessageEvent>
Send a message to the conversation. Triggers the MessengerEvents.SendMessage event for all parties of the conversation (online participants and logged in clients). To get the result, use one of these options:
- Subscribe to the MessengerEvents.SendMessage event and provide a handler consuming an object with the EventHandlers.SendMessageEvent interface as a parameter. Remember that MessengerEvents.SendMessage may be triggered by another user, so check the 'initiator' field.
- Handle the returned promise. Though you still need to listen to MessengerEvents.SendMessage event to handle events from other parties. Rejects to a Messaging.MessengerError if the current user does not have write permissions see ConversationParticipant.canWrite and ConversationParticipant.isOwner).
Parameters
text:
string
payload:
Object[]
OptionalCustom payload; can be an array of any objects, but not primitive types
Returns
type:
Promise<SendMessageEvent>
setCustomData
setCustomData(customData: any
): Promise<EditConversationEvent>
Set new custom data for the conversation. Triggers the MessengerEvents.EditConversation event. To get the result, use one of these options:
- Subscribe to the MessengerEvents.EditConversation event and provide a handler consuming an object with the EventHandlers.EditConversationEvent interface as a parameter. Remember that MessengerEvents.EditConversation may be triggered by another user and as a result of a number of other methods. So check 'messengerAction' and 'initiator' fields.
- Handle the returned promise. Though you still need to listen to MessengerEvents.EditConversation event to handle events from other parties. Rejects to a Messaging.MessengerError if the current user is not an owner of the conversation (see ConversationParticipant.isOwner)
Parameters
customData:
any
Returns
type:
Promise<EditConversationEvent>
setPublicJoin
setPublicJoin(publicJoin: boolean
): Promise<EditConversationEvent>
Set the public join flag and send changes to the server. Triggers the MessengerEvents.EditConversation event. To get the result, use one of these options:
- Subscribe to the MessengerEvents.EditConversation event and provide a handler consuming an object with the EventHandlers.EditConversationEvent interface as a parameter. Remember that MessengerEvents.EditConversation may be triggered by another user and as a result of a number of other methods. So check 'messengerAction' and 'initiator' fields.
- Handle the returned promise. Though you still need to listen to MessengerEvents.EditConversation event to handle events from other parties. Rejects to a Messaging.MessengerError if the current user is not an owner of the conversation (see ConversationParticipant.isOwner)
Parameters
publicJoin:
boolean
Returns
type:
Promise<EditConversationEvent>
setTitle
setTitle(title: string
): Promise<EditConversationEvent>
Set a new title for the current conversation. Triggers the MessengerEvents.EditConversation event. To get the result, use one of these options:
- Subscribe to the MessengerEvents.EditConversation event and provide a handler consuming an object with the EventHandlers.EditConversationEvent interface as a parameter. Remember that MessengerEvents.EditConversation may be triggered by another user and as a result of a number of other methods. So check 'messengerAction' and 'initiator' fields.
- Handle the returned promise. Though you still need to listen to MessengerEvents.EditConversation event to handle events from other parties. Rejects to a Messaging.MessengerError if the current user is not an owner of the conversation (see ConversationParticipant.isOwner)
Parameters
title:
string
Returns
type:
Promise<EditConversationEvent>
toCache
toCache():
Serialize the conversation so it can be stored (e.g. in IndexedDB) and restored later via the Messenger.createConversationFromCache method.
Returns
typing
typing(): Promise<TypingEvent,false>
Inform the cloud that the user is typing some text. The minimum interval between the two method calls should be 10 seconds. Triggers the MessengerEvents.Typing event for all parties of the conversation (online participants and logged in clients). To get the result, use one of these options:
- Subscribe to the MessengerEvents.Typing event and provide a handler consuming an object with the EventHandlers.TypingEvent interface as a parameter. Remember that MessengerEvents.Typing may be triggered by another user, so check the 'initiator' field.
- Handle the returned promise. Though you still need to listen to MessengerEvents.Typing event to handle events from other parties. Rejects to a Messaging.MessengerError if the method is called within 10s since the last call. Calls within 10s interval from the last call are discarded.
Returns
type:
Promise<TypingEvent,false>
update
update(): Promise<EditConversationEvent>
Send changes made via modifying conversation properties (Conversation.title, Conversation.publicJoin and Conversation.customData) to the cloud. Triggers the MessengerEvents.EditConversation event. To get the result, use one of these options:
- Subscribe to the MessengerEvents.EditConversation event and provide a handler consuming an object with the EventHandlers.EditConversationEvent interface as a parameter. Remember that MessengerEvents.EditConversation may be triggered by another user and as a result of a number of other methods. So check 'messengerAction' and 'initiator' fields.
- Handle the returned promise. Though you still need to listen to MessengerEvents.EditConversation event to handle events from other parties. Rejects to a Messaging.MessengerError if the current user is not an owner of the conversation (see ConversationParticipant.isOwner)
Returns
type:
Promise<EditConversationEvent>
Props
createdAt
createdAt: number
UNIX timestamp (seconds) that specifies the time the conversation has been created.
customData
customData: any
Any JavaScript structure with custom data, up to 5Kb. Note that setting this property does not send changes to the cloud. Use the Conversation.update method to send all changes at once or Conversation.setCustomData to update just the custom data.
direct
direct: boolean
A direct conversation includes only 2 participants. There cannot be more than 1 direct conversation between the same 2 users. If one of these users tries to create a new direct conversation with the same participant via Messenger.createConversation, the method returns the existing direct conversation. A direct conversation cannot be uber and/or public.
lastSeq
lastSeq: any
The sequence of the last event in the conversation.
lastUpdate
lastUpdate: any
UNIX timestamp (seconds) that specifies the time of the last event in the conversation.
participants
participants:
The list of conversation participants alongside with their rights. The default permissions for all participants are: write / edit / remove their own messages (see ConversationParticipant.canWrite, ConversationParticipant.canEdit and ConversationParticipant.canRemove). The creator of the conversation is an owner by default. An owner of the conversation (see ConversationParticipant.isOwner):
- can write messages
- can edit and remove own and other participants' messages
- can manage conversation participants
publicJoin
publicJoin: boolean
If true, anyone can join the conversation by UUID. A public conversation cannot be direct. Note that setting this property does not send changes to the cloud. Use the Conversation.update method to send all changes at once or Conversation.setPublicJoin to update only the public join property.
title
title: string
The conversation title. Note that setting this property does not send changes to the server. Use the Conversation.update method to send all the changes at once or Conversation.setTitle to update only the title.
uberConversation
uberConversation: boolean
Users in a uber conversation are not able to retrieve messages that have been posted to the conversation after they quit or before they joined. A uber conversation cannot be direct.
uuid
uuid: string
The universally unique identifier (UUID) of the conversation.