IConversation
Interface that may be used to manage a conversation.
Methods
addParticipants
void
addParticipants(List<ConversationParticipant>
participants, handler)
Add new participants to the conversation.
It's possible only on the following conditions:
- the participants are users of the main Voximplant developer account or its child accounts
- the current user can manage other participants (ConversationParticipant.canManageParticipants() is true)
- the conversation is not a direct one (IConversation.isDirect() is false)
Duplicated users are ignored. Will cause IErrorEvent if at least one user does not exist or already belongs to the conversation.
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IConversationEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onEditConversation(IConversationEvent) and IMessengerListener.onError(IErrorEvent) events.
Other parties of the conversation (online participants and logged in clients) can be informed about adding participants via the IMessengerListener.onEditConversation(IConversationEvent) event.
Parameters
participants:
List<ConversationParticipant>
List of ConversationParticipant to be added to the conversation. Shouldn't contain null(s), be null or empty list.
Completion handler to get the result or null
Returns
type:
void
editParticipants
void
editParticipants(List<ConversationParticipant>
participants, handler)
Edit participants' permissions. It's possible only if the current user can manage other participants (ConversationParticipant.canManageParticipants() is true).
Duplicated users are ignored. Will cause IErrorEvent if at least one user does not exist or belong to the conversation.
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IConversationEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onEditConversation(IConversationEvent) and IMessengerListener.onError(IErrorEvent) events.
Other parties of the conversation (online participants and logged in clients) can be informed about editing participants via the IMessengerListener.onEditConversation(IConversationEvent) event.
Parameters
participants:
List<ConversationParticipant>
List of ConversationParticipant to be edited in the conversation. Shouldn't contain null(s), be null or empty list.
Completion handler to get the result or null
Returns
type:
void
getCreatedTime
long
getCreatedTime()
Get the UNIX timestamp (seconds) that specifies the time of the conversation creation.
Returns
type:
long
getCustomData
Map<String, Object>
getCustomData()
Get a custom data, up to 5kb.
Returns
type:
Map<String, Object>
getLastSequence
long
getLastSequence()
Returns the sequence of the last event in the conversation.
Returns
type:
long
getLastUpdateTime
long
getLastUpdateTime()
Get the UNIX timestamp (seconds) that specifies the time when one of IConversationEvent or IMessageEvent was the last provoked event in this conversation.
Returns
type:
long
getParticipants
List<ConversationParticipant>
getParticipants()
Get the list of participants alongside with their permissions.
Returns
type:
List<ConversationParticipant>
getTitle
String
getTitle()
Get the current conversation title.
Returns
type:
String
getUUID
String
getUUID()
Get the universally unique identifier (UUID) of this conversation.
Returns
type:
String
isDirect
boolean
isDirect()
Check if the conversation is direct.
A direct conversation can't be uber and/or public.
There can be only 2 participants in a direct conversation which is unique and the only one for these participants. There can't be more than 1 direct conversation for the same 2 users.
If one of these users tries to create a new direct conversation with the same participant via IMessenger.createConversation(ConversationConfig, IMessengerCompletionHandler), the method will return the UUID of the already existing direct conversation.
Returns
type:
boolean
isPublicJoin
boolean
isPublicJoin()
Check if a conversation is public or not. If true, anyone can join the conversation by UUID.
A public conversation can't be direct.
Returns
type:
boolean
isUber
boolean
isUber()
Check if the conversation is uber or not.
A uber conversation can't be direct.
Users in a uber conversation will not be able to retrieve messages that were posted to the conversation after they quit.
Returns
type:
boolean
markAsRead
void
markAsRead(long
sequence, handler)
Mark the event with the specified sequence as read.
A method call with the specified sequence makes the ConversationParticipant.getLastReadEventSequence() method return this sequence, i.e., such sequences can be get for each participant separately.
If the sequence parameter specified less than 1, the method will mark all the events as unread (for this participant) except the event with the sequence equals to '1'.
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IConversationServiceEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.isRead(IConversationServiceEvent) and IMessengerListener.onError(IErrorEvent) events.
Other parties of the conversation (online participants and logged in clients) can be informed about marking events as read via the IMessengerListener.isRead(IConversationServiceEvent) event.
Parameters
sequence:
long
Sequence number of the event in the conversation to be marked as read. Shouldn't be greater than currently possible.
Completion handler to get the result or null
Returns
type:
void
removeParticipants
void
removeParticipants(List<ConversationParticipant>
participants, handler)
Remove participants from the conversation.
It's possible only on two conditions:
- the current user can manage other participants (ConversationParticipant.canManageParticipants() is true).
- the conversation is not a direct one (IConversation.isDirect() is false)
Duplicated users are ignored. Will cause IErrorEvent if at least one user:
- does not exist
- is already removed
Note that you can remove participants that are marked as deleted (IUser.isDeleted() is true).
The removed users can later get this conversation's UUID via the IUser.getLeaveConversationList() method.
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IConversationEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onEditConversation(IConversationEvent) and IMessengerListener.onError(IErrorEvent) events.
Other parties of the conversation (online participants and logged in clients) can be informed about removing participants via the IMessengerListener.onEditConversation(IConversationEvent) event.
Parameters
participants:
List<ConversationParticipant>
List of ConversationParticipant to be removed from the conversation. Shouldn't contain null(s), be null or empty list.
Completion handler to get the result or null
Returns
type:
void
retransmitEvents
void
retransmitEvents(long
eventsFrom, long
eventsTo, handler)
Request events in the specified sequence range to be sent from the cloud to this client.
Only IConversationEvent and IMessageEvent events can be retransmitted; any other events can't be retransmitted.
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 event sequence received from the cloud and last event sequence saved locally (if any).
The maximum amount of retransmitted events per method call is 100. Requesting more than 100 events will cause IErrorEvent.
If the current user quits a IConversation.isUber() conversation, messages that are posted during the user's absence will not be retransmitted later.
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IRetransmitEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onRetransmitEvents(IRetransmitEvent) and IMessengerListener.onError(IErrorEvent) events.
Parameters
eventsFrom:
long
First event in sequence range, inclusive
eventsTo:
long
Last event in sequence range, inclusive
Completion handler to get the result or null
Returns
type:
void
retransmitEventsFrom
void
retransmitEventsFrom(long
eventsFrom, int
count, handler)
Request a number of events starting with the specified sequence to be sent from the cloud to this client.
Only IConversationEvent and IMessageEvent events can be retransmitted; any other events can't be retransmitted.
The method is used to get history or get missed events in case of network disconnect. Client should use this method to request all events based on the last event sequence received from the cloud and last event sequence saved locally (if any).
The maximum amount of retransmitted events per method call is 100. Requesting more than 100 events will cause an IErrorEvent.
If the current user quits a IConversation.isUber() conversation, messages that are posted during the user's absence will not be retransmitted later.
The result contains maximum available events for the current user even if it's less than the specified count value. To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IRetransmitEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onRetransmitEvents(IRetransmitEvent) and IMessengerListener.onError(IErrorEvent) events.
Parameters
eventsFrom:
long
First event in sequence range, inclusive
count:
int
Number of events
Completion handler to get the result or null
Returns
type:
void
retransmitEventsTo
void
retransmitEventsTo(long
eventsTo, int
count, handler)
Request a number of events up to the specified sequence to be sent from the cloud to this client.
Only IConversationEvent and IMessageEvent events can be retransmitted; any other events can't be retransmitted.
The method is used to get history or get missed events in case of network disconnect. Client should use this method to request all events based on the last event sequence received from the cloud and last event sequence saved locally (if any).
The maximum amount of retransmitted events per method call is 100. Requesting more than 100 events will cause IErrorEvent.
If the current user quits a IConversation.isUber() conversation, messages that are posted during the user's absence will not be retransmitted later.
The result contains maximum available events for the current user even if it's less than the specified count value. To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IRetransmitEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onRetransmitEvents(IRetransmitEvent) and IMessengerListener.onError(IErrorEvent) events.
Parameters
eventsTo:
long
Last event in sequence range, inclusive
count:
int
Number of events
Completion handler to get the result or null
Returns
type:
void
sendMessage
void
sendMessage(String
text, List<Map<String, Object>>
payload, handler)
Send a message to the conversation.
Sending messages is available only for participants that have write permissions (ConversationParticipant.canWrite() is true).
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IMessageEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onSendMessage(IMessageEvent) and IMessengerListener.onError(IErrorEvent) events.
Other parties of the conversation (online participants and logged in clients) can be informed about sending messages to the conversation via the IMessengerListener.onSendMessage(IMessageEvent) event.
To be informed about sending messages while being offline, participants can subscribe to the MessengerNotification.ON_SEND_MESSAGE messenger push notification.
Parameters
text:
String
Message text, maximum 5000 characters
payload:
List<Map<String, Object>>
Message payload
handler:
Completion handler to get the result or null
Returns
type:
void
setCustomData
void
setCustomData(Map<String, Object>
customData)
Set a new custom data for the conversation.
Note that calling this method does not send changes to the cloud. Use IConversation.update(IMessengerCompletionHandler)} to send all changes at once.
Parameters
customData:
Map<String, Object>
Custom data of the conversation
Returns
type:
void
setPublicJoin
void
setPublicJoin(boolean
publicJoin)
Enable/disable public join in the conversation.
A public conversation can't be direct.
Note that calling this method does not send changes to the cloud. Use IConversation.update(IMessengerCompletionHandler) to send all changes at once
Parameters
publicJoin:
boolean
If true, anyone can join conversation by UUID
Returns
type:
void
setTitle
void
setTitle(String
title)
Set a new title for the current conversation.
Note that calling this method does not send changes to the cloud. Use IConversation.update(IMessengerCompletionHandler) to send all changes at once.
Parameters
title:
String
New conversation title
Returns
type:
void
typing
void
typing( handler)
Inform the cloud that the user is typing some text.
The method calls within 10s interval from the last call cause IErrorEvent.
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IConversationServiceEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onTyping(IConversationServiceEvent) and IMessengerListener.onError(IErrorEvent) events.
Other parties of the conversation (online participants and logged in clients) can be informed about typing via the IMessengerListener.onTyping(IConversationServiceEvent) event.
Parameters
Completion handler to get the result or null
Returns
type:
void
update
void
update( handler)
Send conversation changes to the cloud. The sent changes are: title, public join flag and custom data.
Successful update will happen if a participant is the owner (ConversationParticipant.isOwner() is true).
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with IConversationEvent or IErrorEvent in case of success/error accordingly.
- Implement the IMessengerListener.onEditConversation(IConversationEvent) and IMessengerListener.onError(IErrorEvent) events.
Other parties of the conversation (online participants and logged in clients) can be informed about changing the title or custom data and enabling/disabling public join via the IMessengerListener.onEditConversation(IConversationEvent) event.
Parameters
Completion handler to get the result or null
Returns
type:
void