com.nexmo.client

Class NexmoClient

java.lang.Object

com.nexmo.client.NexmoClient

public class NexmoClient
extends java.lang.Object

The NexmoClient is the main entry point into the SDK and is instantiated to use the NexmoConversation API in your application.

Unless otherwise specified, all the methods invoked by this client are executed asynchronously.

First step is to create a NexmoClient instance using NexmoClient.Builder and passing application context:

 NexmoClient client = new NexmoClient.Builder().build(context);
 

Note: Check NexmoClient.Builder class to see all configuration options.

Note: After initializing the NexmoClient instance can be also retrieved using the get() method:

 NexmoClient client = NexmoClient.get();
 

Second step is to connect to the session:

 client.login("JWT");
 

Note: A session is the period during which your app is connected to Nexmo API. Sessions last the lifetime of the auth token. Tokens can be set for one time use (login), before becoming invalid for another login attempt. If the authToken is revoked while a session is active the session may be terminated by the server. It is only possible to have one single session active over a socket.io connection at a time. Session multiplexing is not supported.

Remember to logout when needed in order to remove current user and disconnect from the underlying connection. To disconnect from the session call logout() method:

 client.logout();
 

To monitor connection state add NexmoConnectionListener:

 client.setConnectionListener(new NexmoConnectionListener() {
     @Override
     public void onConnectionStatusChange(@NonNull ConnectionStatus connectionStatus, @NonNull ConnectionStatusReason connectionStatusReason) {
         Log.d("onConnectionStatusChange", "Connection status changed: " + connectionStatus + " " + connectionStatusReason);

         if (connectionStatus == ConnectionStatus.CONNECTED) {
              Log.d("onConnectionStatusChange", "User is logged in");
         }
     }
 });
 

Common use cases:

• To place a call for another user or phone number use call(String, NexmoCallHandler, NexmoRequestListener) method
• To receive a call for another user or phone number add addIncomingCallListener(NexmoIncomingCallListener) listener
• To end a call use NexmoCall.hangup(NexmoRequestListener) method
• For more use cases and samples please check the client-sdk-android-samples repository

For more use cases and samples please check the client-sdk-android-samples repository.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NexmoClient.Builder Builds new NexmoClient.
static class	NexmoClient.NexmoClientConfig The settings used to initialise the NexmoClient that was built by NexmoClient.Builder.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	NexmoClient(NexmoClient.NexmoClientConfig config, android.content.Context context)

Method Summary

Modifier and Type	Method and Description
void	addIncomingCallListener(NexmoIncomingCallListener incomingCallListener) Adds a callback to be notified about incoming call.
void	addReceiveConversationListener(NexmoReceiveConversationListener receiveConversationListener) Adds listener to be notified about incoming conversation.
void	call(java.lang.String callee, NexmoCallHandler callType, NexmoRequestListener<NexmoCall> listener) Deprecated. Use inAppCall(callee, listener) or serverCall(callee, customData, listener) instead.
void	disablePushNotifications(NexmoRequestListener<java.lang.Void> listener) Unregister device, so it will not receive push notifications.
void	enablePushNotifications(java.lang.String deviceToken, NexmoRequestListener<java.lang.Void> listener) Register device to receive push notifications.
static NexmoClient	get() Returns the current NexmoClient instance, call this function after NexmoClient.Builder.build(Context).
java.lang.String	getAuthToken() Gets the last used JWT authToken for logging in the NexmoUser, synchronously.
NexmoClient.NexmoClientConfig	getConfig() Gets the config used to build NexmoClient.
android.content.Context	getContext() Gets the context used for building NexmoClient.
void	getConversation(java.lang.String conversationId, NexmoRequestListener<NexmoConversation> listener) Gets the conversation instance.
void	getConversations(java.lang.Integer pageSize, NexmoPageOrder order, NexmoRequestListener<NexmoConversationsPage> listener) Deprecated.
void	getConversations(java.lang.Integer pageSize, java.lang.String state, NexmoPageOrder order, NexmoRequestListener<NexmoConversationsPage> listener) Gets conversations.
java.lang.String	getSDKVersion() Returns the current version of the Nexmo Client SDK.
NexmoUser	getUser() Gets the currently logged-in NexmoUser, synchronously.
void	getUser(java.lang.String userId, NexmoRequestListener<NexmoUser> listener) Gets the user info for given userId.
void	getUserSessions(java.lang.String userId, java.lang.Integer pageSize, NexmoPageOrder order, NexmoRequestListener<NexmoUserSessionsPage> listener) Gets user sessions.
void	inAppCall(java.lang.String username, NexmoRequestListener<NexmoCall> listener) Create NexmoCall and invite user by username or userId.
boolean	isConnected() Gets the Boolean determining whatever or not the connection status is connected (check if a user is logged-in).
static boolean	isNexmoPushNotification(java.util.Map<java.lang.String,java.lang.String> data) Checks if notification received from Firebase is a Nexmo push notification.
void	login(java.lang.String authToken) Logs in this NexmoClient instance based on the builder information and login details.
void	logout() Logs out the current NexmoUser.
void	newConversation(java.lang.String conversationName, java.lang.String conversationDisplayName, NexmoRequestListener<NexmoConversation> listener) Creates a new NexmoConversation for a given display name.
NexmoPushPayload	processNexmoPush(java.util.Map<java.lang.String,java.lang.String> data, NexmoPushEventListener listener) Process Nexmo push notification.For complete push notifications config see set up push notifications guide.
void	processPushNotification(java.util.Map<java.lang.String,java.lang.String> data, NexmoPushEventListener listener) Deprecated.
void	reconnectCall(java.lang.String conversationId, java.lang.String legId, NexmoRequestListener<NexmoCall> listener) Reconnect to an exisiting on going call
void	removeIncomingCallListeners() Removes incoming call listener.
void	removeNewConversationListener() Removes new conversation call listener.
void	serverCall(java.lang.String callee, java.util.HashMap<java.lang.String,java.lang.Object> customData, NexmoRequestListener<NexmoCall> listener) Creates a NexmoCall through NCCO call control.
void	setConnectionListener(NexmoConnectionListener connectionListener) Sets connection state listener.
void	updateAuthToken(java.lang.String authToken) Updates auth token.
void	uploadAttachment(java.io.File attachment, NexmoRequestListener listener) Uploads an attachment to Nexmo Media Service.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NexmoClient

protected NexmoClient(NexmoClient.NexmoClientConfig config,
                      android.content.Context context)

Method Detail

get

public static NexmoClient get()

Returns the current NexmoClient instance, call this function after NexmoClient.Builder.build(Context).

Returns:

The current NexmoClient object.

isNexmoPushNotification

public static boolean isNexmoPushNotification(java.util.Map<java.lang.String,java.lang.String> data)

Checks if notification received from Firebase is a Nexmo push notification. For complete push notifications config see set up push notifications guide.

setConnectionListener

public void setConnectionListener(NexmoConnectionListener connectionListener)

Sets connection state listener.

Parameters:

connectionListener - The request completion listener.

getSDKVersion

public java.lang.String getSDKVersion()

Returns the current version of the Nexmo Client SDK.

Returns:

The current version of the Nexmo Client SDK.

getConfig

public NexmoClient.NexmoClientConfig getConfig()

Gets the config used to build NexmoClient.

Returns:

the config

getContext

public android.content.Context getContext()

Gets the context used for building NexmoClient.

Returns:

a context.

getUser

public final NexmoUser getUser()

Gets the currently logged-in NexmoUser, synchronously.

Returns:

The logged-in NexmoUser, if any.

getAuthToken

public java.lang.String getAuthToken()

Gets the last used JWT authToken for logging in the NexmoUser, synchronously.

Returns:

The last used JWT authToken, if any.

login

public void login(java.lang.String authToken)

Logs in this NexmoClient instance based on the builder information and login details.

Depending on the validity of the supplied authToken, NexmoConnectionListener.onConnectionStatusChange(NexmoConnectionListener.ConnectionStatus, NexmoConnectionListener.ConnectionStatusReason) can be fired for:

• NexmoConnectionListener.ConnectionStatusReason.TOKEN_EXPIRED. Supplied authToken has expired, your application needs to retrieve another one in order to complete login.
• NexmoConnectionListener.ConnectionStatusReason.TERMINATED. your connection has been terminated.
• NexmoConnectionListener.ConnectionStatusReason.NETWORK_ERROR. network error while trying to connect.
• NexmoConnectionListener.ConnectionStatusReason.MAX_SESSIONS. max sessions for client.
• NexmoConnectionListener.ConnectionStatusReason.SESSION_ERROR. error in your session.
• NexmoConnectionListener.ConnectionStatusReason.SESSION_INVALID. your session is invalid.
• NexmoConnectionListener.ConnectionStatusReason.TOKEN_REFRESHED. The status changed because of token refresh.
• NexmoConnectionListener.ConnectionStatusReason.LOGOUT. The status changed because of logout.
• NexmoConnectionListener.ConnectionStatusReason.LOGIN. The status changed because of login.
• NexmoConnectionListener.ConnectionStatusReason.UNKNOWN. Unknown reason for change in connection status.

Required parameters are:

• authToken: The backend authorization authToken.

Parameters:

authToken - The backend authorization JWT.

updateAuthToken

public void updateAuthToken(java.lang.String authToken)

Updates auth token.

Token may need an update when supplied auth token expires.

NexmoConnectionListener.onConnectionStatusChange(NexmoConnectionListener.ConnectionStatus, NexmoConnectionListener.ConnectionStatusReason) fires with NexmoConnectionListener.ConnectionStatusReason.TOKEN_EXPIRED.

Parameters:

authToken - The backend authorization JWT.

logout

public void logout()

Logs out the current NexmoUser.

This method also performs additional tasks:

• disconnects from the underlying connection.
• disables and terminates any active audio stream.
• cleans up any event listeners.

getUser

public void getUser(java.lang.String userId,
                    NexmoRequestListener<NexmoUser> listener)

Gets the user info for given userId.

Parameters:

userId - The id of user.

listener - The request completion listener.

getUserSessions

public void getUserSessions(java.lang.String userId,
                            java.lang.Integer pageSize,
                            NexmoPageOrder order,
                            NexmoRequestListener<NexmoUserSessionsPage> listener)

Gets user sessions.

Parameters:

userId - The id of the user.

pageSize - The size of the page.

order - The sorting order.

listener - The request completion listener.

getConversations

@Deprecated
public void getConversations(java.lang.Integer pageSize,
                                         NexmoPageOrder order,
                                         NexmoRequestListener<NexmoConversationsPage> listener)

Deprecated.

Gets conversations.

Parameters:

pageSize - The size of the page.

order - The sorting order.

listener - The request completion listener.

getConversations

public void getConversations(java.lang.Integer pageSize,
                             java.lang.String state,
                             NexmoPageOrder order,
                             NexmoRequestListener<NexmoConversationsPage> listener)

Gets conversations.

Parameters:

pageSize - The size of the page.

state - The state of the conversation. Value of this param the same as com.nexmo.clientcore.model.enums.EMemberState String ("JOINED", " INVITED" or "LEFT") . If null value is passed then method returns only the conversations where user state is "JOINED" or "INVITED" ,but not "LEFT" (not all all conversations like expected - this behaviour will most likely change in the future to rerun all conversations).

order - The sorting order.

listener - The request completion listener.

enablePushNotifications

public void enablePushNotifications(java.lang.String deviceToken,
                                    NexmoRequestListener<java.lang.Void> listener)

Register device to receive push notifications. For complete push notifications config see set up push notifications guide.

Parameters:

deviceToken - Token obtained from FirebaseMessagingService

listener - The request completion listener.

disablePushNotifications

public void disablePushNotifications(NexmoRequestListener<java.lang.Void> listener)

Unregister device, so it will not receive push notifications.

Parameters:

listener - The request completion listener.

processPushNotification

@Deprecated
public void processPushNotification(java.util.Map<java.lang.String,java.lang.String> data,
                                                NexmoPushEventListener listener)

Deprecated.

Process Nexmo push notification.For complete push notifications config see set up push notifications guide.

Parameters:

data - Firebase remote message payload.

listener - The request completion listener.

processNexmoPush

public NexmoPushPayload processNexmoPush(java.util.Map<java.lang.String,java.lang.String> data,
                                         NexmoPushEventListener listener)

Process Nexmo push notification.For complete push notifications config see set up push notifications guide.

Parameters:

data - Firebase remote message payload.

listener - The request completion listener.

newConversation

public void newConversation(java.lang.String conversationName,
                            java.lang.String conversationDisplayName,
                            NexmoRequestListener<NexmoConversation> listener)

Creates a new NexmoConversation for a given display name.

In order for a NexmoUser to be able to be part of a NexmoConversation, he must either:

• explicitly join a conversation: NexmoConversation.join(String, NexmoRequestListener)
• accept a conversation invitation.

Parameters:

conversationName - The optional conversation name, it's case-insensitive. If not provided, a name will be auto-generated.

conversationDisplayName - The optional conversation display name. If not provided, will be left empty.

listener - The request completion listener.

getConversation

public void getConversation(java.lang.String conversationId,
                            NexmoRequestListener<NexmoConversation> listener)

Gets the conversation instance.

Parameters:

conversationId - The unique conversation ID.

listener - The request completion listener.

call

@Deprecated
public void call(java.lang.String callee,
                             NexmoCallHandler callType,
                             NexmoRequestListener<NexmoCall> listener)

Deprecated. Use inAppCall(callee, listener) or serverCall(callee, customData, listener) instead.

Initiates a NexmoCall.

Parameters:

callee - userName or phone number to start the call with.

callType - NexmoCall can be initiated through IN_APP flow or SERVER flow.

listener - Completion listener.

addIncomingCallListener

public void addIncomingCallListener(NexmoIncomingCallListener incomingCallListener)

Adds a callback to be notified about incoming call.

Parameters:

incomingCallListener - The incoming call listener.

removeIncomingCallListeners

public void removeIncomingCallListeners()

Removes incoming call listener.

addReceiveConversationListener

public void addReceiveConversationListener(NexmoReceiveConversationListener receiveConversationListener)

Adds listener to be notified about incoming conversation.

Parameters:

receiveConversationListener - The receive conversation listener.

removeNewConversationListener

public void removeNewConversationListener()

Removes new conversation call listener.

serverCall

public void serverCall(java.lang.String callee,
                       java.util.HashMap<java.lang.String,java.lang.Object> customData,
                       NexmoRequestListener<NexmoCall> listener)

Creates a NexmoCall through NCCO call control.

Parameters:

callee - String representing the phone number or username.

customData - HashMap representing additional custom data.

listener - The request completion listener.

inAppCall

public void inAppCall(java.lang.String username,
                      NexmoRequestListener<NexmoCall> listener)

Create NexmoCall and invite user by username or userId.

Parameters:

username - The username of the user that will be invited to this call.

listener - Completion listener.

reconnectCall

public void reconnectCall(java.lang.String conversationId,
                          java.lang.String legId,
                          NexmoRequestListener<NexmoCall> listener)

Reconnect to an exisiting on going call

Parameters:

conversationId - The Conversation Id of the existing call

legId - Your Members Leg id within the exisitng call

listener - Completion listener.

uploadAttachment

public void uploadAttachment(java.io.File attachment,
                             NexmoRequestListener listener)

Uploads an attachment to Nexmo Media Service.

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

• Original at 100% size via NexmoImage.getOriginal()
• Medium at 50% size via NexmoImage.getMedium()
• Thumbnail at 10% size via NexmoImage.getThumbnail()

Parameters:

attachment - The attachment file.

listener - The request completion listener.

isConnected

public boolean isConnected()

Gets the Boolean determining whatever or not the connection status is connected (check if a user is logged-in).

Returns:

true if is connected, otherwise returns false.