1. References
  2. Android SDK v3 (Beta)
  3. com.voximplant.android.sdk.messaging
  4. Conversation
Rate this page:

Conversation

This API is in beta and subject to change.

Interface that manages a conversation.

Methods

update

Copy URL
fun update(callback: 
MessengerCallback<ConversationEvent>?
): 
Unit

This API is in beta and subject to change.

Sends the conversation changes to the cloud. The changes are: title, public join flag and custom data.

Successful update happens if a participant is the owner (ConversationParticipant.isOwner is true).

To get the method call result use one of the following options:

  1. Specify the callback parameter to consume the results with ConversationEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onEditConversation and MessengerListener.onError 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 MessengerListener.onEditConversation event.

Parameters

Returns

  • type:

    Unit

addParticipants

Copy URL
fun addParticipants(participants: 
List<ConversationParticipant>
, callback: 
MessengerCallback<ConversationEvent>?
): 
Unit

This API is in beta and subject to change.

Adds new participants to the conversation.

It is possible only on the following conditions:

Duplicated users are ignored. Causes ErrorEvent 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:

  1. Specify the callback parameter to consume the results with ConversationEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onEditConversation and MessengerListener.onError events.

Other parties of the conversation (online participants and logged in clients) can be informed about adding participants via the MessengerListener.onEditConversation event.

Parameters

Returns

  • type:

    Unit

removeParticipants

Copy URL
fun removeParticipants(participants: 
List<ConversationParticipant>
, callback: 
MessengerCallback<ConversationEvent>?
): 
Unit

This API is in beta and subject to change.

Removes participants from the conversation.

It is possible only on two conditions:

Duplicated users are ignored. Causes ErrorEvent if at least one user:

  • does not exist
  • is already removed

Note that you can remove participants that are marked as deleted (User.isDeleted is true).

The removed users can later get this conversation's UUID via the User.leaveConversationUuidList method.

To get the method call result use one of the following options:

  1. Specify the callback parameter to consume the results with ConversationEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onEditConversation and MessengerListener.onError events.

Other parties of the conversation (online participants and logged in clients) can be informed about removing participants via the MessengerListener.onEditConversation event.

Parameters

Returns

  • type:

    Unit

editParticipants

Copy URL
fun editParticipants(participants: 
List<ConversationParticipant>
, callback: 
MessengerCallback<ConversationEvent>?
): 
Unit

This API is in beta and subject to change.

Edits participants' permissions. It is possible only if the current user can manage other participants (ConversationParticipant.canManageParticipants is true).

Duplicated users are ignored. Causes ErrorEvent 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:

  1. Specify the callback parameter to consume the results with ConversationEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onEditConversation and MessengerListener.onError events.

Other parties of the conversation (online participants and logged in clients) can be informed about editing participants via the MessengerListener.onEditConversation event.

Parameters

Returns

  • type:

    Unit

sendMessage

Copy URL
fun sendMessage(text: 
String?
, payload: 
List<Map<String, Any>>?
, callback: 
MessengerCallback<MessageEvent>?
): 
Unit

This API is in beta and subject to change.

Sends 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:

  1. Specify the callback parameter to consume the results with MessageEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onSendMessage and MessengerListener.onError events.

Other parties of the conversation (online participants and logged in clients) can be informed about sending messages to the conversation via the MessengerListener.onSendMessage event.

To be informed about sending messages while being offline, participants can subscribe to the MessengerNotification.OnSendMessage messenger push notification.

TODO(Oleg) Update documentation to use text or payload as non-null for at least one of the parameters

Parameters

  • text:

    String?

    Optional

    Message text, maximum 5000 characters

  • payload:

    List<Map<String, Any>>?

    Optional

    Message payload

  • callback:

    MessengerCallback<MessageEvent>?

    Optional

    Callback to be called when the function completes

Returns

  • type:

    Unit

retransmitEvents

Copy URL
fun retransmitEvents(eventsFrom: 
Long
, eventsTo: 
Long
, callback: 
MessengerCallback<RetransmitEvent>?
): 
Unit

This API is in beta and subject to change.

Requests events in the specified sequence range to be sent from the cloud to this client.

Only ConversationEvent and MessageEvent events can be retransmitted; any other events cannot be retransmitted.

Use this method 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 number of retransmitted events per method call is 100. Requesting more than 100 events causes ErrorEvent.

If the current user quits a Conversation.isUber conversation, messages that are posted during the user's absence are not retransmitted later.

To get the method call result use one of the following options:

  1. Specify the callback parameter to consume the results with RetransmitEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onRetransmitEvents and MessengerListener.onError events.

Parameters

  • eventsFrom:

    Long

    First event in sequence range, inclusive

  • eventsTo:

    Long

    Last event in sequence range, inclusive

  • callback:

    MessengerCallback<RetransmitEvent>?

    Optional

    Callback to be called when the function completes

Returns

  • type:

    Unit

retransmitEventsFrom

Copy URL
fun retransmitEventsFrom(eventsFrom: 
Long
, count: 
Int
, callback: 
MessengerCallback<RetransmitEvent>?
): 
Unit

This API is in beta and subject to change.

Requests a number of events starting with the specified sequence to be sent from the cloud to this client.

Only ConversationEvent and MessageEvent events can be retransmitted; any other events cannot be retransmitted.

Use this method 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 number of retransmitted events per method call is 100. Requesting more than 100 events cause an ErrorEvent.

If the current user quits a Conversation.isUber conversation, messages that are posted during the user's absence are not retransmitted later.

The result contains maximum available events for the current user even if It is less than the specified count value. To get the method call result use one of the following options:

  1. Specify the callback parameter to consume the results with RetransmitEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onRetransmitEvents and MessengerListener.onError events.

Parameters

  • eventsFrom:

    Long

    First event in sequence range, inclusive

  • count:

    Int

    Number of events

  • callback:

    MessengerCallback<RetransmitEvent>?

    Optional

    Callback to be called when the function completes

Returns

  • type:

    Unit

retransmitEventsTo

Copy URL
fun retransmitEventsTo(eventsTo: 
Long
, count: 
Int
, callback: 
MessengerCallback<RetransmitEvent>?
): 
Unit

This API is in beta and subject to change.

Requests a number of events up to the specified sequence to be sent from the cloud to this client.

Only ConversationEvent and MessageEvent events can be retransmitted; any other events cannot be retransmitted.

Use this method 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 number of retransmitted events per method call is 100. Requesting more than 100 events cause ErrorEvent.

If the current user quits a Conversation.isUber conversation, messages that are posted during the user's absence are not retransmitted later.

The result contains maximum available events for the current user even if It is less than the specified count value. To get the method call result use one of the following options:

  1. Specify the callback parameter to consume the results with RetransmitEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onRetransmitEvents and MessengerListener.onError events.

Parameters

  • eventsTo:

    Long

    Last event in sequence range, inclusive

  • count:

    Int

    Number of events

  • callback:

    MessengerCallback<RetransmitEvent>?

    Optional

    Callback to be called when the function completes

Returns

  • type:

    Unit

typing

Copy URL
fun typing(callback: 
MessengerCallback<ConversationServiceEvent>?
): 
Unit

This API is in beta and subject to change.

Informs the cloud that the user is typing some text.

The method calls within 10s interval from the last call cause ErrorEvent.

To get the method call result use one of the following options:

  1. Specify the callback parameter to consume the results with ConversationServiceEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.onTyping and MessengerListener.onError events.

Other parties of the conversation (online participants and logged in clients) can be informed about typing via the MessengerListener.onTyping event.

Parameters

Returns

  • type:

    Unit

markAsRead

Copy URL
fun markAsRead(sequence: 
Long
, callback: 
MessengerCallback<ConversationServiceEvent>?
): 
Unit

This API is in beta and subject to change.

Marks the event with the specified sequence as read.

A method call with the specified sequence makes the ConversationParticipant.lastReadEventSequence 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 marks 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:

  1. Specify the callback parameter to consume the results with ConversationServiceEvent or ErrorEvent in case of success/error accordingly.
  2. Implement the MessengerListener.isRead and MessengerListener.onError events.

Other parties of the conversation (online participants and logged in clients) can be informed about marking events as read via the MessengerListener.isRead event.

Parameters

  • sequence:

    Long

    Sequence number of the event in the conversation to be marked as read. Should not be greater than currently possible

  • callback:

    MessengerCallback<ConversationServiceEvent>?

    Optional

    Callback to be called when the function completes

Returns

  • type:

    Unit

Props

createdTime

Copy URL
val createdTime: 
Long

This API is in beta and subject to change.

The UNIX timestamp (seconds) that specifies the time of the conversation creation.

Returns

  • type:

    Long

customData

Copy URL
var customData: 
Map<String, Any>?

This API is in beta and subject to change.

The custom data of the conversation, up to 5kb.

Note that changing this property does not send changes to the cloud. Use Conversation.update to send all changes at once.

Returns

  • type:

    Map<String, Any>?

isDirect

Copy URL
val isDirect: 
Boolean

This API is in beta and subject to change.

Whether the conversation is direct.

A direct conversation cannot 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 cannot 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 Messenger.createConversation, the method returns the UUID of the already existing direct conversation.

Returns

  • type:

    Boolean

participants

Copy URL
val participants: 
List<ConversationParticipant>

This API is in beta and subject to change.

The list of participants with their permissions.

Returns

isPublicJoin

Copy URL
var isPublicJoin: 
Boolean

This API is in beta and subject to change.

Whether a conversation is public or not. If true, anyone can join the conversation by UUID.

A public conversation cannot be direct.

Note that changing this property does not send changes to the cloud. Use Conversation.update to send all changes at once

Returns

  • type:

    Boolean

title

Copy URL
var title: 
String

This API is in beta and subject to change.

The title of the current conversation.

Note that changing this property does not send changes to the cloud. Use Conversation.update to send all changes at once.

Returns

  • type:

    String

uuid

Copy URL
val uuid: 
String

This API is in beta and subject to change.

The universally unique identifier (UUID) of this conversation.

Returns

  • type:

    String

lastUpdateTime

Copy URL
val lastUpdateTime: 
Long

This API is in beta and subject to change.

The UNIX timestamp (seconds) that specifies the time when one of ConversationEvent or MessageEvent has been last provoked event in this conversation.

Returns

  • type:

    Long

lastSequence

Copy URL
val lastSequence: 
Long

This API is in beta and subject to change.

The sequence of the last event in the conversation.

Returns

  • type:

    Long

isUber

Copy URL
val isUber: 
Boolean

This API is in beta and subject to change.

Whether the conversation is uber.

An uber conversation cannot be direct.

Users in a uber conversation are not able to retrieve messages that are posted to the conversation after they quit.

Returns

  • type:

    Boolean