Container for conversation object. More...

Classes
enum	ConversationState
	Represents the various states of the conversation. More...

enum	ConversationStatus
	Represents the various statuses of the user with respect to the conversation. More...

enum	NotificationLevel
	User's notification level on a conversation. More...

enum	SynchronizationStatus
	Indicates synchronization status for conversation. More...

enum	UpdateReason
	Indicates reason for conversation update. More...

Public Member Functions
Getters
String	getSid ()
	Get unique identifier for this conversation. More...

String	getFriendlyName ()
	Get friendly name of the conversation. More...

NotificationLevel	getNotificationLevel ()
	The current user's notification level on this conversation. More...

Attributes	getAttributes ()
	Get custom attributes associated with the Conversation. More...

ConversationStatus	getStatus ()
	Get the current user's participation status on this conversation. More...

ConversationState	getState ()

Date	getStateDateUpdatedAsDate ()
	Get update date of the ConversationState. More...

SynchronizationStatus	getSynchronizationStatus ()
	Get the current synchronization status for conversation. More...

String	getDateCreated ()
	Get creation date of the conversation as an ISO 8601 string. More...

Date	getDateCreatedAsDate ()
	Get creation date of the conversation. More...

String	getCreatedBy ()
	Get creator of the conversation. More...

String	getDateUpdated ()
	Get update date of the conversation as an ISO 8601 string. More...

Date	getDateUpdatedAsDate ()
	Get update date of the conversation. More...

Date	getLastMessageDate ()
	Get last message date in the conversation. More...

Long	getLastMessageIndex ()
	Get last message's index in the conversation. More...

Setters
void	setFriendlyName (String friendlyName, StatusListener listener)
	Update the friendly name for this conversation. More...

void	setNotificationLevel (NotificationLevel notificationLevel, StatusListener listener)
	Set the user's notification level for the conversation. More...

String	getUniqueName ()
	Get unique name of the conversation. More...

void	setUniqueName (String uniqueName, StatusListener listener)
	Update the unique name for this conversation. More...

void	setAttributes (Attributes attributes, StatusListener listener)
	Set attributes associated with this conversation. More...

Listeners
void	addListener (ConversationListener listener)
	Add a new ConversationListener for this Conversation. More...

void	removeListener (ConversationListener listener)
	Remove ConversationListener for this Conversation. More...

void	removeAllListeners ()
	Remove all ConversationListeners for this Conversation. More...

Actions
void	join (StatusListener listener)
	Join the current user to this conversation. More...

void	leave (StatusListener listener)
	Leave this conversation. More...

void	destroy (StatusListener listener)
	Destroy the current conversation. More...

void	typing ()
	Indicate that Participant is typing in this conversation. More...

void	addParticipantByIdentity (String identity, Attributes attributes, StatusListener listener)
	Add specified username to this conversation. More...

void	addParticipantByAddress (String address, String proxyAddress, Attributes attributes, StatusListener listener)
	Add specified non chat participant to this conversation, i.e. More...

void	removeParticipant (Participant participant, StatusListener listener)
	Remove specified participant from this conversation. More...

void	removeParticipantByIdentity (String identity, StatusListener listener)
	Remove specified username from this conversation. More...

Counts
void	getMessagesCount (CallbackListener< Long > listener)
	Get total number of messages in the conversation. More...

void	getUnreadMessagesCount (CallbackListener< Long > listener)
	Get number of unread messages in the conversation. More...

void	getParticipantsCount (CallbackListener< Long > listener)
	Get total number of participants in the conversation roster. More...

Messages
void	sendMessage (Message.Options options, CallbackListener< Message > listener)
	Sends a message to the conversation. More...

void	removeMessage (Message message, StatusListener listener)
	Removes a message from the conversation. More...

Long	getLastReadMessageIndex ()
	Return user last read message index for the conversation. More...

void	setLastReadMessageIndex (long lastReadMessageIndex, CallbackListener< Long > listener)
	Set user last read message index for the conversation. More...

void	advanceLastReadMessageIndex (long lastReadMessageIndex, CallbackListener< Long > listener)
	Increase user last read message index for the conversation. More...

void	setAllMessagesRead (CallbackListener< Long > listener)
	Mark all messages in conversation as read. More...

void	setAllMessagesUnread (CallbackListener< Long > listener)
	Mark all messages in conversation as unread. More...

void	getMessagesBefore (long index, int count,@NonNull CallbackListener< List< Message >> listener)
	Fetch at most count messages including and prior to the specified index. More...

void	getMessagesAfter (long index, int count,@NonNull CallbackListener< List< Message >> listener)
	Fetch at most count messages including and subsequent to the specified index. More...

void	getLastMessages (int count,@NonNull CallbackListener< List< Message >> listener)
	Load last messages in conversation. More...

void	getMessageByIndex (long index,@NonNull CallbackListener< Message > listener)
	Get message object by known index. More...

Participants
List< Participant >	getParticipantsList ()
	Obtain an array of participants of this conversation. More...

Participant	getParticipantByIdentity (String identity)
	Get a conversation participant by identity. More...

Participant	getParticipantBySid (String sid)
	Get a conversation participant by sid. More...

Detailed Description

Container for conversation object.

To obtain a Conversation call ConversationsClient#createConversation, ConversationsClient#getConversation or get it from collections returned by ConversationsClient#getMyConversations.

Conversation is a relatively heavy-weight object. It receives state updates from the back-end in real time.

Member Function Documentation

void com.twilio.conversations.Conversation.addListener ( ConversationListener listener )

Add a new ConversationListener for this Conversation.

Conversation listeners receive real time updates about changes in the conversation state, messages and participants.

This listener will be called on the originating thread if it has a Looper, otherwise on the main UI thread.

Parameters

listener A conversation listener.

See also: removeListener; removeAllListeners

void com.twilio.conversations.Conversation.addParticipantByAddress	(	String	address,
		String	proxyAddress,
		Attributes	attributes,
		StatusListener	listener
	)

Add specified non chat participant to this conversation, i.e.

sms, whatsapp participants etc. If the participant is already present in the conversation roster an error will be returned.

Parameters

address	The participant address to add to this conversation (phone number for sms and whatsapp participants)
proxyAddress	Proxy address (Twilio phone number for sms and whatsapp participants). See conversations quickstart for more info: https://www.twilio.com/docs/conversations/quickstart
attributes	The developer-provided Attributes for participant or null to use default empty attributes.
listener	StatusListener to report status of the action.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.addParticipantByIdentity	(	String	identity,
		Attributes	attributes,
		StatusListener	listener
	)

Add specified username to this conversation.

If the participant is already present in the conversation roster an error will be returned.

Parameters

identity	The username to add to this conversation.
attributes	The developer-provided Attributes for participant or null to use default empty attributes.
listener	StatusListener to report status of the action.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.advanceLastReadMessageIndex	(	long	lastReadMessageIndex,
		CallbackListener< Long >	listener
	)

Increase user last read message index for the conversation.

Index is ignored if it is smaller than user current index.

Parameters

lastReadMessageIndex	read message index
listener	Status listener to report result of the operation that receives current number of unread messages.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.destroy ( StatusListener listener )

Destroy the current conversation.

Note: this will delete the Conversation and all associated metadata from the service instance. Participants in the conversation and all conversation messages, including posted media will be lost.

There is no undo for this operation!

Parameters

listener Listener that will receive callback with the result.

See also: #dispose

Attributes com.twilio.conversations.Conversation.getAttributes ( )

Get custom attributes associated with the Conversation.

Attributes are stored as a JSON format object, of arbitrary internal structure. Conversation attributes are limited in size to 32Kb.

Returns: Attributes object with attributes.

See also: setAttributes

String com.twilio.conversations.Conversation.getCreatedBy ( )

Get creator of the conversation.

Returns: Identity of the conversation's creator.

String com.twilio.conversations.Conversation.getDateCreated ( )

Get creation date of the conversation as an ISO 8601 string.

Returns: Date when conversation was created as a string in ISO 8601 format.

Date com.twilio.conversations.Conversation.getDateCreatedAsDate ( )

Get creation date of the conversation.

Returns: Date when conversation was created or null if date string could not be parsed.

String com.twilio.conversations.Conversation.getDateUpdated ( )

Get update date of the conversation as an ISO 8601 string.

Update date changes when conversation attributes, friendly name or unique name are modified. It will not change in response to messages posted or participants added or removed.

Returns: Date when conversation was last updated as a string in ISO 8601 format.

Date com.twilio.conversations.Conversation.getDateUpdatedAsDate ( )

Get update date of the conversation.

Update date changes when conversation attributes, friendly name or unique name are modified. It will not change in response to messages posted or participants added or removed.

Returns: Date when conversation was last updated or null if date string could not be parsed.

String com.twilio.conversations.Conversation.getFriendlyName ( )

Get friendly name of the conversation.

Friendly name is a free-form text string, it is not unique and could be used for user-friendly conversation name display in the UI.

Returns: Conversation friendly name.

See also: setFriendlyName

Date com.twilio.conversations.Conversation.getLastMessageDate ( )

Get last message date in the conversation.

See also: UpdateReason::LAST_MESSAGE status update

Returns: Date of last message in the conversation or null if no last message or no access to conversation.

Long com.twilio.conversations.Conversation.getLastMessageIndex ( )

Get last message's index in the conversation.

See also: UpdateReason::LAST_MESSAGE status update

Returns: Index of last message in the conversation or null if no last message or no access to conversation.

void com.twilio.conversations.Conversation.getLastMessages	(	int	count,
		@NonNull CallbackListener< List< Message >>	listener
	)

Load last messages in conversation.

Parameters

count	count of messages to load
listener	operation callback listener

Exceptions

IllegalStateException If conversation isn't synchronized properly.

Long com.twilio.conversations.Conversation.getLastReadMessageIndex ( )

Return user last read message index for the conversation.

Returns: read message index. Null if not set

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.getMessageByIndex	(	long	index,
		@NonNull CallbackListener< Message >	listener
	)

Get message object by known index.

Parameters

index	Message index.
listener	Listener for Message object at index.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.getMessagesAfter	(	long	index,
		int	count,
		@NonNull CallbackListener< List< Message >>	listener
	)

Fetch at most count messages including and subsequent to the specified index.

Parameters

index	start index
count	count of messages to load
listener	operation callback listener

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.getMessagesBefore	(	long	index,
		int	count,
		@NonNull CallbackListener< List< Message >>	listener
	)

Fetch at most count messages including and prior to the specified index.

Parameters

index	start index
count	count of messages to load
listener	operation callback listener

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.getMessagesCount ( CallbackListener< Long > listener )

Get total number of messages in the conversation.

This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversations system does not provide real time events for counter values changes.

So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time.

This function performs an async call to service to obtain up-to-date message count. The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.

Parameters

listener Listener to receive results of the query.

See also: getUnreadMessagesCount

NotificationLevel com.twilio.conversations.Conversation.getNotificationLevel ( )

The current user's notification level on this conversation.

This property reflects whether the user will receive push notifications for activity on this conversation.

Returns: Current notification level.

See also: setNotificationLevel; NotificationLevel

Participant com.twilio.conversations.Conversation.getParticipantByIdentity ( String identity )

Get a conversation participant by identity.

Parameters

identity The identity of the participant to look up.

Returns: Participant object in current conversation, or null if not found.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

Participant com.twilio.conversations.Conversation.getParticipantBySid ( String sid )

Get a conversation participant by sid.

Parameters

sid	The sid of the participant to look up.

Returns: Participant object in current conversation, or null if not found.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.getParticipantsCount ( CallbackListener< Long > listener )

Get total number of participants in the conversation roster.

This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversations system does not provide real time events for counter values changes.

So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time.

This function performs an async call to service to obtain up-to-date participant count. The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.

Parameters

listener Listener to receive results of the query.

List<Participant> com.twilio.conversations.Conversation.getParticipantsList ( )

Obtain an array of participants of this conversation.

Returns: An array of Participant objects representing the membership of the conversation.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

String com.twilio.conversations.Conversation.getSid ( )

Get unique identifier for this conversation.

This identifier can be used to get this Conversation again using ConversationsClient#getConversation.

The conversation SID is persistent and globally unique.

Returns: Conversation SID.

ConversationState com.twilio.conversations.Conversation.getState ( )

Returns: The current ConversationState for this conversation.

Date com.twilio.conversations.Conversation.getStateDateUpdatedAsDate ( )

Get update date of the ConversationState.

Returns: Date when ConversationState was last updated.

ConversationStatus com.twilio.conversations.Conversation.getStatus ( )

Get the current user's participation status on this conversation.

Returns: Conversation participation status.

SynchronizationStatus com.twilio.conversations.Conversation.getSynchronizationStatus ( )

Get the current synchronization status for conversation.

Returns: current synchronization status for the conversation

String com.twilio.conversations.Conversation.getUniqueName ( )

Get unique name of the conversation.

Unique name is similar to SID but can be specified by the user.

Returns: Conversation unique name or null if it was not set.

See also: setUniqueName

void com.twilio.conversations.Conversation.getUnreadMessagesCount ( CallbackListener< Long > listener )

Get number of unread messages in the conversation.

Note: if the last read index has not been yet set for current user as the participant of this conversation then unread messages count is considered uninitialized. In this case null is returned. See setLastReadMessageIndex.

This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversations system does not provide real time events for counter values changes.

So this is quite useful for any “unread messages count” badges, but is not recommended to build any core application logic based on these counters being accurate in real time.

This function performs an async call to service to obtain up-to-date message count. The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.

Use this method to obtain number of unread messages together with setLastReadMessageIndex instead of relying on Message indices which may have gaps. See Message#getMessageIndex for details.

Parameters

listener Listener to receive results of the query.

See also: getMessagesCount

void com.twilio.conversations.Conversation.join ( StatusListener listener )

Join the current user to this conversation.

Joining the conversation is a prerequisite for sending and receiving messages in the conversation. You can join the conversation or you could be added to it by another conversation participant.

Parameters

listener Listener that will receive callback with the result.

See also: leave

void com.twilio.conversations.Conversation.leave ( StatusListener listener )

Leave this conversation.

Parameters

listener Listener that will receive callback with the result.

See also: join

void com.twilio.conversations.Conversation.removeAllListeners ( )

Remove all ConversationListeners for this Conversation.

See also: addListener; removeListener

void com.twilio.conversations.Conversation.removeListener ( ConversationListener listener )

Remove ConversationListener for this Conversation.

Parameters

listener Listener to remove.

See also: addListener; removeAllListeners

void com.twilio.conversations.Conversation.removeMessage	(	Message	message,
		StatusListener	listener
	)

Removes a message from the conversation.

Parameters

message	The message to remove.
listener	Status listener to report result of the operation.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.removeParticipant	(	Participant	participant,
		StatusListener	listener
	)

Remove specified participant from this conversation.

Parameters

participant	The participant to remove from this conversation.
listener	StatusListener to report status.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.removeParticipantByIdentity	(	String	identity,
		StatusListener	listener
	)

Remove specified username from this conversation.

Parameters

identity	The identity of the participant to remove from this conversation.
listener	StatusListener to report status.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.sendMessage	(	Message.Options	options,
		CallbackListener< Message >	listener
	)

Sends a message to the conversation.

Parameters

options	The message construction options.
listener	Status listener to report result of the operation that receives sent Message object.

Exceptions

IllegalArgumentException	If passed in options object is null.
IllegalStateException	If conversation isn't synchronized properly.

Example

sendMessage(
    Message.options()
        .withMedia(new FileInputStream("/path/to/Somefile.txt"), "text/plain")
        .withMediaFileName("file.txt")
        .withMediaProgressListener(new ProgressListener() {
            @Override
            public void onStarted() {
                Timber.d("Upload started");
            }
            @Override
            public void onProgress(long bytes) {
                Timber.d("Uploaded " + bytes + " bytes");
            }
            @Override
            public void onCompleted(String mediaSid) {
                Timber.d("Upload completed");
            }
        }),
    new CallbackListener<Message>() {
        @Override
        public void onSuccess(Message msg) {
            Timber.d("Successfully sent MEDIA message");
        }
        @Override
        public void onError(ErrorInfo error) {
            Timber.e("Error sending MEDIA message");
        }
    });

void com.twilio.conversations.Conversation.setAllMessagesRead ( CallbackListener< Long > listener )

Mark all messages in conversation as read.

This method set last read message index to last message index in conversation.

Parameters

listener Status listener to report result of the operation that receives current number of unread messages.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.setAllMessagesUnread ( CallbackListener< Long > listener )

Mark all messages in conversation as unread.

This method set last read message index before the first message index in conversation.

Parameters

listener Status listener to report result of the operation that receives current number of unread messages.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.setAttributes	(	Attributes	attributes,
		StatusListener	listener
	)

Set attributes associated with this conversation.

Attributes are stored as a JSON format object, of arbitrary internal structure. Conversation attributes are limited in size to 32Kb.

Passing null will reset conversation attributes to an empty json object.

Parameters

attributes	The new developer-provided Attributes for this conversation.
listener	Listener that will receive callback with the result.

See also: getAttributes

void com.twilio.conversations.Conversation.setFriendlyName	(	String	friendlyName,
		StatusListener	listener
	)

Update the friendly name for this conversation.

Parameters

friendlyName	New friendly name.
listener	Listener that will receive callback with the status of update operation.

See also: getFriendlyName

void com.twilio.conversations.Conversation.setLastReadMessageIndex	(	long	lastReadMessageIndex,
		CallbackListener< Long >	listener
	)

Set user last read message index for the conversation.

Parameters

lastReadMessageIndex	read message index
listener	Status listener to report result of the operation that receives current number of unread messages.

Exceptions

IllegalStateException If conversation isn't synchronized properly.

void com.twilio.conversations.Conversation.setNotificationLevel	(	NotificationLevel	notificationLevel,
		StatusListener	listener
	)

Set the user's notification level for the conversation.

This property determines whether the user will receive push notifications for activity on this conversation.

Parameters

notificationLevel	The new notification level for the current user on this conversation.
listener	Listener that will receive callback with the status of update operation.

See also: getNotificationLevel

void com.twilio.conversations.Conversation.setUniqueName	(	String	uniqueName,
		StatusListener	listener
	)

Update the unique name for this conversation.

Unique name is unique within Service Instance. You will receive an error if you try to set a name that is not unique.

Parameters

uniqueName	New unique name for this conversation.
listener	Listener that will receive callback with the result.

See also: getUniqueName

void com.twilio.conversations.Conversation.typing ( )

Indicate that Participant is typing in this conversation.

You should call this method to indicate that a local user is entering a message into current conversation. The typing state is forwarded to users subscribed to this conversation through ConversationListener#onTypingStarted and ConversationListener#onTypingEnded callbacks.

After approximately 5 seconds after the last typing call the SDK will emit ConversationListener#onTypingEnded signal.

One common way to implement this indicator is to call typing repeatedly in response to key input events.

Classes

Public Member Functions

Detailed Description

Member Function Documentation