public class

Conversation

extends Object
java.lang.Object
   ↳ com.nexmo.sdk.conversation.client.Conversation

Class Overview

A container that you use to manage communications between Members, the conversation history and context.

Users cannot manually create conversation objects, but creating a Conversation via ConversationClient#newConversation(String, RequestHandler) will dispatch a new Conversation object.

Every action on a conversation will dispatch a completion callback that contains an updated Conversation object. For ex: 

     myConversation.sendText("payload", new RequestHandler() {
         @Override
         public void onSuccess(Event text) {
              // Update the application UI here if needed with updated conversation.
         }
         @Override
         public void onError(NexmoAPIError error) {
              // Update the application UI here if needed.
         }
     });

Listen for incoming events messageEvent()

Example usage:

   conversation.messageEvent().add(new ResultListener() {
    @Override
    public void onSuccess(Event result) {
        notifyUI("New event from " + result.getMemberById());
    }
  });

Sending a text message to a specific conversation is achieved using Conversation#sendText(String, RequestHandler)

Example usage:

     myConversation.sendText("message payload...", new RequestHandler() {
         @Override
         public void onSuccess(Event event) {
              // Update the application UI here if needed.
         }
         @Override
         public void onError(NexmoAPIError error) {
              // Update the application UI here if needed.
         }
    });

Marking an event as seen is achieved using markAsSeen(RequestHandler)

Example usage:

     textEvent.markAsSeen( new RequestHandler() {
         @Override
         public void onSuccess(SeenReceipt seenReceipt) {
              // Update the application UI here if needed.
         }
         @Override
         public void onError(NexmoAPIError error) {
              // Update the application UI here if needed.
         }
    });

Listen for typing indicator events Conversation#typingEvent().add(ResultListener

Example usage:

     myConversation.typingEvent().add(new ResultListener

Summary

Nested Classes
enum Conversation.MEDIA_TYPE  
Protected Constructors
Conversation(String displayName)
Conversation(String displayName, String cid)
Conversation(String displayName, String cid, String lastEventId)
Conversation(String displayName, String cid, Member member)
Conversation(String displayName, String cid, Member member, Date creationDate)
Conversation(String name, String cid, String lastEventId, Member member)
Conversation(String displayName, String cid, String lastEventId, Member member, Date creationDate, List<Member> members)
Conversation(String name, String cid, String lastEventId, Date creationDate)
Conversation(String displayName, String cid, String lastEventId, Member member, Date creationDate)
Conversation(String displayName, String cid, String lastEventId, Member member, Date creationDate, List<Member> members, List<Event> events)
Conversation(Conversation conversation)
Public Methods
void deleteEvent(Event event, RequestHandler<Void> eventDeleteListener)
Delete a message event
EventSource<Receipt<DeliveredReceipt>> deliveryEvent()
Register for receiving delivered receipt events.
boolean equals(Object o)
Image findImage(String id)
Find an Image message based on event ID, synchronously.
Text findText(String id)
Find a Text message based on event ID, synchronously.
static Conversation fromCursor(Cursor cursor)
static Conversation fromJson(JSONObject body)
Construct object from the network response.
String getConversationId()
The id of this conversation.
Date getCreationDate()
Get the creation date of this conversation, synchronously.
String getDisplayName()
The name of this conversation.
Event getEvent(String event_id)
Get an event based on its ID, synchronously.
List<Event> getEvents()
Get the list of events that were lastly retrieved, synchronously.
List<Image> getImages()
Get the list of image events only , synchronously.
String getLastEventId()
The last event id of this conversation.
Member getMemberById(String member_id)
Get a member based on its member ID, synchronously.
Member getMemberByName(String member_name)
Get a member based on its username, synchronously.
Member getMemberByUser(User user)
Get a member based on its user details, synchronously.
String getMemberId()
Get the member ID of the current user in this conversation.
List<Member> getMembers()
Get all members that are JOINED/INVITED/LEFT in this conversation, synchronously.
Member getSelf()
Get the member object for current user.
List<Text> getTexts()
Get the list of text events only , synchronously.
int hashCode()
void invite(String username, RequestHandler<Member> inviteSendListener)
Invite a user to a certain conversation.
void inviteWithAudio(String userId, String username, boolean muted, boolean isEarmuff, RequestHandler<Member> requestHandler)
Invite a user to an audio conversation, using preset params for muted and earmuff.
void join(String username, RequestHandler<Member> requestHandler)
Current User allows another user to join a Conversation.
void join(RequestHandler<Member> requestHandler)
Current User joins a Conversation.
void leave(RequestHandler<Void> leaveListener)
Leave a conversation the User has joined, or is invited to.
AudioCallManager media(Conversation.MEDIA_TYPE mediaType)
EventSource<Invitation> memberInvitedEvent()
Register for receiving member invited events.
EventSource<Member> memberJoinedEvent()
Register for receiving member joined events.
EventSource<Member> memberLeftEvent()
Register for receiving member left events.
EventSource<Event> messageEvent()
Listen for incoming messages from this conversation.
EventSource<Receipt<SeenReceipt>> seenEvent()
Register for receiving seen receipt events.
ImageUploader.CancelableCall sendImage(String imagePath, RequestHandler<Event> imageSendListener)
Send/Upload an Image event to a conversation.
void sendText(String message, RequestHandler<Event> listener)
Send a Text event to a conversation.
void setAudioRoute(AppRTCAudioManager.AudioDevice audioRoute)
void startTyping(RequestHandler<Member.TYPING_INDICATOR> listener)
Send a typing indicator {ON event for the current member of a conversation.
void stopTyping(RequestHandler<Member.TYPING_INDICATOR> listener)
Send a typing indicator OFF event for the current member of a conversation.
String toString()
EventSource<Member> typingEvent()
Register for receiving typing indicator events from other members.
void update(RequestHandler<Conversation> requestHandler)
Retrieve full conversation information, like members and conversation details.
void updateEvents(String startId, String endId, RequestHandler<Conversation> requestHandler)
Retrieve the event history of a Conversation.
Protected Methods
void setTypingTimeOutLength(long typingTimeOutLength)
[Expand]
Inherited Methods
From class java.lang.Object

Protected Constructors

protected Conversation (String displayName)

protected Conversation (String displayName, String cid)

protected Conversation (String displayName, String cid, String lastEventId)

protected Conversation (String displayName, String cid, Member member)

protected Conversation (String displayName, String cid, Member member, Date creationDate)

protected Conversation (String name, String cid, String lastEventId, Member member)

protected Conversation (String displayName, String cid, String lastEventId, Member member, Date creationDate, List<Member> members)

protected Conversation (String name, String cid, String lastEventId, Date creationDate)

protected Conversation (String displayName, String cid, String lastEventId, Member member, Date creationDate)

protected Conversation (String displayName, String cid, String lastEventId, Member member, Date creationDate, List<Member> members, List<Event> events)

protected Conversation (Conversation conversation)

Public Methods

public void deleteEvent (Event event, RequestHandler<Void> eventDeleteListener)

Delete a message event

Parameters
event The event that needs to be deleted.

public EventSource<Receipt<DeliveredReceipt>> deliveryEvent ()

Register for receiving delivered receipt events.

public boolean equals (Object o)

public Image findImage (String id)

Find an Image message based on event ID, synchronously.

Parameters
id The event id.
Returns
  • The image object.

public Text findText (String id)

Find a Text message based on event ID, synchronously.

Parameters
id The event id.
Returns
  • The text object.

public static Conversation fromCursor (Cursor cursor)

public static Conversation fromJson (JSONObject body)

Construct object from the network response.

Parameters
body network response
Throws
JSONException if required fields don't exist

public String getConversationId ()

The id of this conversation.

Returns
  • The auto-generated application unique ID of this conversation.

public Date getCreationDate ()

Get the creation date of this conversation, synchronously.

Returns
  • creation date.

public String getDisplayName ()

The name of this conversation.

Returns
  • The name used to create this conversation.

public Event getEvent (String event_id)

Get an event based on its ID, synchronously.

Parameters
event_id The event ID.
Returns
  • The event object.

public List<Event> getEvents ()

Get the list of events that were lastly retrieved, synchronously.

Returns
  • The list of events in this conversation.

public List<Image> getImages ()

Get the list of image events only , synchronously.

Returns
  • The list of image events in this conversation.

public String getLastEventId ()

The last event id of this conversation.

Returns
  • event id.

public Member getMemberById (String member_id)

Get a member based on its member ID, synchronously. If the member appears to be missing this conversation is out of sync, call Conversation#update(RequestHandler) to force fetch all members.

Parameters
member_id The auto-generated memberID.
Returns
  • The member or null if member is not found locally.

public Member getMemberByName (String member_name)

Get a member based on its username, synchronously. If the member appears to be missing this conversation is out of sync, call Conversation#update(RequestHandler) to force fetch all members.

Parameters
member_name The username.
Returns
  • The member or null if member is not found locally.

public Member getMemberByUser (User user)

Get a member based on its user details, synchronously. If the member appears to be missing this conversation is out of sync, call Conversation#update(RequestHandler) to force fetch all members.

Parameters
user The current user.
Returns
  • The member or null if member is not found locally.

public String getMemberId ()

Get the member ID of the current user in this conversation.

Returns
  • The auto-generated memberId for current user, or null if user is not part of the conversation.

public List<Member> getMembers ()

Get all members that are JOINED/INVITED/LEFT in this conversation, synchronously.

Returns
  • The list of all members.

public Member getSelf ()

Get the member object for current user. Once a user joins or gets invited to a conversation, a Member object will be created with same username and id, and auto-generated member ID.

Note: If current user it not part of this conversation (neither joined or was invited to), then this method will return null.

Returns
  • User's member in current conversation.

public List<Text> getTexts ()

Get the list of text events only , synchronously.

Returns
  • The list of text events in this conversation.

public int hashCode ()

public void invite (String username, RequestHandler<Member> inviteSendListener)

Invite a user to a certain conversation. The receiving user can accept an invite join(RequestHandler) or reject an invite leave(RequestHandler).

Parameters
username The user id or name.
inviteSendListener The completion listener.

public void inviteWithAudio (String userId, String username, boolean muted, boolean isEarmuff, RequestHandler<Member> requestHandler)

Invite a user to an audio conversation, using preset params for muted and earmuff. Invite by either userId or username, providing one of this params is mandatory. The receiving user can accept an invite join(RequestHandler) or reject an invite leave(RequestHandler).

A user accepting an invite to a conversation with audio enabled will need to manually enable audio after accepting invitation.

Parameters
userId The user id.
username The user name.
muted The user will join as muted or not.
isEarmuff The user will join as earmuff or not.
requestHandler The completion listener.

public void join (String username, RequestHandler<Member> requestHandler)

Current User allows another user to join a Conversation.

Note: any User that joins a Conversation becomes a Member.

Parameters
username The user id or name to join to a conversation.
requestHandler The handler in charge of dispatching the result.

public void join (RequestHandler<Member> requestHandler)

Current User joins a Conversation.

Note: any User that joins a Conversation becomes a Member.

The User will always be current user that has successfully logged-in.

Parameters
requestHandler The handler in charge of dispatching the result.

public void leave (RequestHandler<Void> leaveListener)

Leave a conversation the User has joined, or is invited to. No ownership is enforced on conversation, so any member may invite or remove others.

Parameters
leaveListener The completion listener in charge of dispatching the result.

public AudioCallManager media (Conversation.MEDIA_TYPE mediaType)

public EventSource<Invitation> memberInvitedEvent ()

Register for receiving member invited events. This applies for other members being invited to this conversation.

Returns
  • The listener in charge of dispatching the result.

public EventSource<Member> memberJoinedEvent ()

Register for receiving member joined events.

Returns
  • The listener in charge of dispatching the result.

public EventSource<Member> memberLeftEvent ()

Register for receiving member left events.

Returns
  • The listener in charge of dispatching the result.

public EventSource<Event> messageEvent ()

Listen for incoming messages from this conversation. Event types:

  • "text" Text event
  • "image" Image event.
  • "event:delete" Event delete of either Text or Image.
  • "member:media" A member has either enabled or disabled audio. Typically when a member enables/disables audio with enable(AudioCallEventListener) and disable(RequestHandler).

For incoming Image event type, the THUMBNAIL representation will be downloaded automatically.

public EventSource<Receipt<SeenReceipt>> seenEvent ()

Register for receiving seen receipt events.

When registering for receipt records, the current member will receive all of them, regardless of whether he was the one sending the associated messages.

Note: None of the receipt records can be un-done.

public ImageUploader.CancelableCall sendImage (String imagePath, RequestHandler<Event> imageSendListener)

Send/Upload an Image event to a conversation.

Once the image is uploaded, you will be able to access all 3 representations:

Each ImageRepresentation contains a ImageRepresentation#bitmap that can be used to update UI

Please note that sending image does not get retried in case an error occurs. It is up to the user to resend the image when convenient.

For listening to incoming/sent events events, register using messageEvent()

Note: at this only the image path is allowed, but bitmap or file will soon be added.

Parameters
imagePath The image location, mandatory.
imageSendListener The completion listener, mandatory.
Returns
  • object to control upload process or null in case of error.

public void sendText (String message, RequestHandler<Event> listener)

Send a Text event to a conversation.

For listening to incoming/sent events events, register using messageEvent()

Parameters
message The payload.
listener The listener in charge of dispatching the completion result.

public void setAudioRoute (AppRTCAudioManager.AudioDevice audioRoute)

public void startTyping (RequestHandler<Member.TYPING_INDICATOR> listener)

Send a typing indicator {ON event for the current member of a conversation.

Parameters
listener The listener in charge of dispatching the completion result.

public void stopTyping (RequestHandler<Member.TYPING_INDICATOR> listener)

Send a typing indicator OFF event for the current member of a conversation.

Parameters
listener The listener in charge of dispatching the completion result.

public String toString ()

public EventSource<Member> typingEvent ()

Register for receiving typing indicator events from other members.

Returns
  • The listener in charge of dispatching the result.

public void update (RequestHandler<Conversation> requestHandler)

Retrieve full conversation information, like members and conversation details. available information includes:

For retrieving the text/image events use Conversation#updateEvents(String, String, RequestHandler).

Please bear in mind to refresh the members list on a regular basis to avoid events from 'unknown' members.

For the first time launching the app, the local cache will not present any results.

Parameters
requestHandler The handler in charge of dispatching the result.

public void updateEvents (String startId, String endId, RequestHandler<Conversation> requestHandler)

Retrieve the event history of a Conversation. available information includes:

Parameters
startId Optional, the first event id to get.
endId Optional, the last event id to get.
requestHandler The handler in charge of dispatching the result.

Protected Methods

protected void setTypingTimeOutLength (long typingTimeOutLength)