DocStrap

Class: Application

Application

new Application(SDK, params)

Core application class for the SDK.
Application is the parent object holding the list of conversations, the session object.
Provides methods to create conversations and retrieve a list of the user's conversations, while it holds the listeners for
user's invitations

Parameters:
Name Type Description
SDK NexmoClient

session Object
params object
Source:
Fires:
Example

Accessing the list of conversations

 rtc.createSession(token).then((application) => {
   console.log(application.conversations);
   console.log(application.me.name, application.me.id);
 }).catch((error) => {
   console.error(error);
 });

Members

<static, readonly> CONVERSATION_API_VERSION :string

Enum for Application getConversation version.

Type:
  • string
Properties:
Name Type Default Description
v1 string v0.1
v3 string v0.3
Source:

Methods

<async> callServer(user, type, custom_data)

Creates a call to phone a number.
The call object is created under application.calls when the call has started.
listen for it with application.on("call:status:changed")

You don't need to start the stream, the SDK will play the audio for you

Parameters:
Name Type Argument Default Description
user string

the phone number or the username you want to call
type string <optional>
 "phone"

the type of the call you want to have. possible values "phone" or "app" (default is "phone")
custom_data object <optional>

custom data to be included in the call object, i.e. { yourCustomKey: yourCustomValue }
Source:
Returns:
Type
Promise.<NXMCall>
Example

Create a call to a phone

 application.on("call:status:changed", (nxmCall) => {
   if (nxmCall.status === nxmCall.CALL_STATUS.STARTED) {
		  console.log('the call has started');
		}
 });

 application.callServer(phone_number).then((nxmCall) => {
   console.log('Calling phone ' + phone_number);
   console.log('Call Object ': nxmCall);
 }).catch((error) => {
   console.error(error);
 });

<async> getConversation(id, version)

Query the service to see if this conversation exists with the
logged in user as a member and retrieve the data object
Result added (or updated) in this.conversations

Parameters:
Name Type Default Description
id string

the id of the conversation to fetch
version string Application.CONVERSATION_API_VERSION.v3

{Application.CONVERSATION_API_VERSION.v1 || Application.CONVERSATION_API_VERSION.v3} - the version of the Conversation Service API to use (v1 includes the full list of the members of the conversation but v3 does not)
Source:
Returns:
  • the requested conversation
Type
Promise.<Conversation>
Example

Get a conversation

 application.getConversation(id).then((conversation) => {
     console.log("Retrieved conversation: ", conversation);
 }).catch((error) => {
   console.error(error);
 });

<async> getConversations(params)

Query the service to obtain a complete list of conversations of which the
logged-in user is a member with a state of JOINED or INVITED.

Parameters:
Name Type Description
params object

configure defaults for paginated conversations query

Properties
Name Type Argument Description
order string

'asc' or 'desc' ordering of resources based on creation time
page_size number

the number of resources returned in a single request list
cursor string <optional>

string to access the starting point of a dataset
Source:
Returns:
  • Populate Application.conversations.
Type
Promise.<Page.<Map.<Conversation>>>
Example

Get Conversations

 application.getConversations({ page_size: 20 }).then((conversations_page) => {
   conversations_page.items.forEach(conversation => {
     render(conversation)
   })
 }).catch((error) => {
     console.error(error);
 });

<async> getUser(id)

Get Details of a user by using their id. If no id is present, will return your own user details.

Parameters:
Name Type Description
id string

the id of the user to fetch, if skipped, it returns your own user details
Source:
Returns:
Type
Promise.<User>
Example

Get User details

 application.getUser(id).then((user) => {
   console.log('User details: 'user);
 }).catch((error) => {
     console.error(error);
 });

<async> getUserSessions(params)

Query the service to obtain a complete list of userSessions of a given user

Parameters:
Name Type Description
params object

configure defaults for paginated user sessions query

Properties
Name Type Argument Description
order string

'asc' or 'desc' ordering of resources based on creation time
page_size number

the number of resources returned in a single request list
cursor string <optional>

string to access the starting point of a dataset
user_id string <optional>

the user id that the sessions are being fetched
Source:
Returns:
Type
Promise.<Page.<Map.<UserSession>>>
Example

Get User Sessions

 application.getUserSessions({ user_id: "id", page_size: 20 }).then((user_sessions_page) => {
   user_sessions_page.items.forEach(user_session => {
     render(user_session)
   })
 }).catch((error) => {
     console.error(error);
 });

<async> inAppCall(usernames)

Creates a call to specified user/s.

Parameters:
Name Type Description
usernames Array.<string>

the user names for those we want to call
Source:
Returns:

a NXMCall object with all the call properties

Type
Promise.<NXMCall>
Example

Create a call with users

 application.on("call:status:changed", (nxmCall) => {
   if (nxmCall.status === nxmCall.CALL_STATUS.STARTED) {
		  console.log('the call has started');
		}
 });

 application.inAppCall(usernames).then(() => {
   console.log('Calling user(s)...');
 }).catch((error) => {
   console.error(error);
 });

<async> newConversation(params)

Query the service to create a new conversation
The conversation name must be unique per application.

Parameters:
Name Type Argument Description
params object <optional>

leave empty to get a GUID as name

Properties
Name Type Description
name string

the name of the conversation. A UID will be assigned if this is skipped
display_name string

the display_name of the conversation.
Source:
Returns:
  • the created Conversation
Type
Promise.<Conversation>
Example

Create a conversation and join

 application.newConversation().then((conversation) => {
   //join the created conversation
   conversation.join().then((member) => {
     //Get the user's member belonging in this conversation.
     //You can also access it via conversation.me
     console.log("Joined as " + member.user.name);
   });
 }).catch((error) => {
   console.error(error);
 });

<async> newConversationAndJoin(params)

Query the service to create a new conversation and join it
The conversation name must be unique per application.

Parameters:
Name Type Argument Description
params object <optional>

leave empty to get a GUID as name

Properties
Name Type Description
name string

the name of the conversation. A UID will be assigned if this is skipped
display_name string

the display_name of the conversation.
Source:
Returns:
  • the created Conversation
Type
Promise.<Conversation>
Example

Create a conversation and join

 application.newConversationAndJoin().then((conversation) => {
   console.log("Joined as " + conversation.me.display_name);
 }).catch((error) => {
   console.error("Error creating a conversation and joining ", error);
 });

<async> reconnectCall(conversation_id, rtc_id, mediaParams)

Reconnect a leg to an ongoing call.
You don't need to start the stream, the SDK will play the audio for you

Parameters:
Name Type Argument Description
conversation_id string

the conversation that you want to reconnect
rtc_id string

the id of the leg that will be reconnected
mediaParams object <optional>

MediaStream params (same as Media.enable())
Source:
Returns:
Type
Promise.<NXMCall>
Examples

Reconnect a leg to an ongoing call

 application.reconnectCall("conversation_id", "rtc_id").then((nxmCall) => {
   console.log(nxmCall);
 }).catch((error) => {
   console.error(error);
 });

Reconnect a leg to an ongoing call without auto playing audio

 application.reconnectCall("conversation_id", "rtc_id", { autoPlayAudio: false }).then((nxmCall) => {
   console.log(nxmCall);
 }).catch((error) => {
   console.error(error);
 });

Reconnect a leg to an ongoing call choosing device ID

 application.reconnectCall("conversation_id", "rtc_id", { audioConstraints: { deviceId: "device_id" } }).then((nxmCall) => {
   console.log(nxmCall);
 }).catch((error) => {
   console.error(error);
 });

syncConversations()

Fetching all the conversations and sync progress events

Source:

<async> updateToken(token)

Update user's token that was generated when they were first authenticated.

Parameters:
Name Type Description
token string

the new token
Source:
Returns:
Type
Promise
Example

listen for expired-token error events and then update the token on Application level

application.on('system:error:expired-token', 'NXM-errors', (error) => {
	console.log('token expired');
	application.updateToken(token);
});

Events

call:status:changed

Application listening for nxmCall status changed events.

Properties:
Name Type Description
nxmCall NXMCall

the actual event
Source:
Example

listen for nxmCall status changed events on Application level

 application.on("call:status:changed",(nxmCall) => {
   console.log("call: " + nxmCall.status);
 });

NXM-errors

Application listening for client and expired-token errors events.

Properties:
Name Type Description
error NexmoClientError
Source:
Examples

listen for client error events on Application level

application.on('*', 'NXM-errors', (error) => {
   console.log('Error thrown with type ' + error.type);
 });

listen for expired-token error events and then update the token on Application level

application.on('system:error:expired-token', 'NXM-errors', (error) => {
	console.log('token expired');
	application.updateToken(token);
});

member:call

Application listening for member call events.

Properties:
Name Type Description
member Member

the member that initiated the nxmCall
nxmCall NXMCall

resolves the nxmCall object
Source:
Example

listen for member call events on Application level

 application.on("member:call", (member, nxmCall) => {
   console.log("NXMCall ", nxmCall);
 });

member:invited

Application listening for member invited events.

Properties:
Name Type Description
member Member

The invited member
event NXMEvent

The invitation event
Source:
Example

listen for member invited events on Application level

 application.on("member:invited",(member, event) => {
   console.log("Invited to the conversation: " + event.conversation.display_name || event.conversation.name);
   // identify the sender.
   console.log("Invited by: " + member.invited_by);
   //accept an invitation.
   application.conversations.get(event.conversation.id).join();
   //decline the invitation.
    application.conversations.get(event.conversation.id).leave();
 });

member:joined

Application listening for member joined events.

Properties:
Name Type Description
member Member

the member that joined the conversation
event NXMEvent

the join event
Source:
Example

listen for member joined events on Application level

 application.on("member:joined",(member, event) => {
   console.log("JOINED", "Joined conversation: " + event.conversation.display_name || event.conversation.name);
 });

sync:progress

Application listening for sync status events.

Properties:
Name Type Description
status.sync_progress number

Percentage of fetched conversations
Source:
Example

listen for changes in the synchronisation progress events on Application level

 application.on("sync:progress",(status) => {
	  console.log(status.sync_progress);
 });