Class: Conversation

Conversation


new Conversation()

A single conversation Object.

Properties:
Name Type Argument Description
me Member

my Member object that belongs to this conversation

application Application

the parent Application

name string

the name of the Conversation (unique)

display_name string <optional>

the display_name of the Conversation

members Map.<string, Member> <optional>

the members of the Conversation keyed by a member's id

events Map.<string, NXMEvent> <optional>

the events of the Conversation keyed by an event's id

sequence_number number <optional>

the last event id

Source:

Members


me :Member

A Member Object representing the current user.
Only set if the user is or has been a member of the Conversation,
otherwise the value will be null.

Type:
Source:

Methods


abortSendImage(imageRequest)

Cancel sending an Image message to the conversation.

Parameters:
Name Type Description
imageRequest XMLHttpRequest
Source:
Returns:

void

Example

cancel sending an image

conversation.sendImage(fileInput.files[0]).then((imageRequest) => {
   conversation.abortSendImage(imageRequest);
});

<async> del()

Delete a conversation

Source:
Returns:
Type
Promise
Example

delete the conversation

conversation.del().then(() => {
   console.log("conversation deleted");
	})

deleteEvent(event)

Delete an NXMEvent (e.g. Text)

Parameters:
Name Type Description
event NXMEvent
Source:
Returns:
Type
Promise

<async> getEvents(params)

Query the service to get a list of events in this conversation.

Parameters:
Name Type Description
params object

configure defaults for paginated events 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

event_type string <optional>

the type of event used to filter event requests. Supports wildcard options with :* eg. 'members:*'

Source:
Returns:
  • Populate Conversations.events.
Type
Promise.<EventsPage.<Map.<Events>>>
Example

Get Events

conversation.getEvents({ event_type: 'member:*' ).then((events_page) => {
  events_page.items.forEach(event => {
    render(event)
  })
});

<async> invite(params)

Invite the given user (id or name) to this conversation

Parameters:
Name Type Description
params Member
Properties
Name Type Argument Description
id or username string <optional>

the id or the username of the user to invite

Source:
Returns:
Type
Promise.<Member>
Example

invite a user to a conversation

const user_id = 'user to invite';
 const user_name = 'username to invite';

 conversation.invite({
  id: user_id,
  user_name: user_name
 }).then((member) => {
  displayMessage(member.state + " user: " + user_id + " " + user_name);
 }).catch((error) => {
  console.log(error);
 });

inviteWithAudio(params)

Invite the given user (id or name) to this conversation with media audio

Parameters:
Name Type Description
params Member
Properties
Name Type Argument Description
id or username string <optional>

the id or the username of the user to invite

Source:
Returns:
Type
Promise.<Member>
Example

invite a user to a conversation

const user_id = 'user to invite';
 const user_name = 'username to invite';

 conversation.inviteWithAudio({
  id: user_id,
  user_name: user_name
 }).then((member) => {
  displayMessage(member.state + " user: " + user_id + " " + user_name);
 }).catch((error) => {
  console.log(error);
 });

<async> join( [params])

Join the given user to this conversation, will typically use this to join
ourselves to a conversation we create.
Accept an invitation if our member has state INVITED and no user_id / user_name is given

Parameters:
Name Type Argument Default Description
params object <optional>
this.application.me.id

The user to join (defaults to this)

Properties
Name Type Description
user_name string

the user_name of the user to join

user_id string

the user_id of the user to join

Source:
Returns:
Type
Promise.<Member>
Example

join a user to a conversation

conversation.join().then((member) => {
   console.log("joined as member: ", member)
 })

leave( [reason])

Leave from the conversation

Parameters:
Name Type Argument Description
reason object <optional>

the reason for leaving the conversation

Properties
Name Type Argument Description
reason_code string <optional>

the code of the reason

reason_text string <optional>

the description of the reason

Source:
Returns:
Type
Promise

<async> sendCustomEvent(params, type, body)

Send a custom event to the conversation

Parameters:
Name Type Description
params object

params of the custom event

type string

the name of the custom event. Must not exceed 100 char length and contain only alpha numerics and '-' and '_' characters.

body object

customizable key value pairs

Source:
Returns:
  • the custom event that was sent
Type
Promise.<NXMEvent>
Example

sending a custom event

conversation.sendCustomEvent({ type: 'my-event', body: {}}).then(() => {
	  console.log('custom event was sent');
	}).catch((error)=>{
	  console.log('error sending the custom event', error);
	});

<async> sendImage(file)

Send an Image message to the conversation, which will be relayed to every other member of the conversation.
implements xhr (https://xhr.spec.whatwg.org/) - this.imageRequest

Parameters:
Name Type Argument Default Description
file File

single input file (jpeg/jpg)

params.quality_ratio string <optional>
100

a value between 0 and 100. 0 indicates 'maximum compression' and the lowest quality, 100 will result in the highest quality image

params.medium_size_ratio string <optional>
50

a value between 1 and 100. 1 indicates the new image is 1% of original, 100 - same size as original

params.thumbnail_size_ratio string <optional>
10

a value between 1 and 100. 1 indicates the new image is 1% of original, 100 - same size as original

Source:
Returns:
Type
Promise.<XMLHttpRequest>
Example

sending an image

conversation.sendImage(fileInput.files[0]).then((imageRequest) => {
 imageRequest.onabort = (e) => {
   console.log(e);
   console.log("Image:" + e.type);
 };
 imageRequest.onloadend = (e) => {
   console.log("Image:" + e.type);
 };
});

<async> sendText(text)

Send a text message to the conversation, which will be relayed to every other member of the conversation

Parameters:
Name Type Description
text string

the text message to be sent

Source:
Returns:
  • the text message that was sent
Type
Promise.<TextEvent>
Example

sending a text

conversation.sendText("Hi Nexmo").then(() => {
  console.log('message was sent');
	}).catch((error)=>{
	  console.log('error sending the message', error);
	});

startTyping()

Send start typing indication

Source:
Returns:
  • resolves the promise on successful sent
Type
Promise

stopTyping()

Send stop typing indication

Source:
Returns:
  • resolves the promise on successful sent
Type
Promise

Events


audio:mute:off

Conversation listening for mute off events
A member has unmuted their audio

Properties:
Name Type Description
member Member

the member object linked to this event

event NXMEvent

information about the mute event

Source:

audio:mute:on

Conversation listening for mute on events
A member has muted their audio

Properties:
Name Type Description
member Member

the member object linked to this event

event NXMEvent

information about the mute event

Source:

event:delete

Conversation listening for deleted events.

Properties:
Name Type Description
member Member

the member who deleted an event

event NXMEvent

deleted event: event.id

Source:
Example

get details about the deleted event

conversation.on("event:delete", (member, event) => {
 console.log(event.id);
 console.log(event.body.timestamp.deleted);
});

image

Conversation listening for image events.

Properties:
Name Type Description
sender Member

The sender of the image

image ImageEvent

The image message received

Source:
Example

listen for image events

conversation.on("image", (sender, image) => {
   console.log(sender,image);
   // Identify your own imageEvent.
   if (image.from !== conversation.me.id)
   // Identify if the event corresponds to the currently open conversation.
   if (image.cid === conversation.id)
 });

text

Conversation listening for text events.

Properties:
Name Type Description
sender Member

The sender of the text

text TextEvent

The text message received

Source:
Example

listen for text events

conversation.on("text",(sender, message) => {
   console.log(sender,message);
   // Identify your own message.
   if (message.from !== conversation.me.id)
   // Identify if the event corresponds to the currently open conversation.
   if (message.cid === conversation.id)
 });

image:seen

Conversation listening for members' seen images.

Properties:
Name Type Description
member Member

the member that saw the image

image ImageEvent

the image that was seen

Source:
Example

listen for seen image events

conversation.on("image:seen", (data, image) => {
 console.log(image);
 // Check if the event belongs to this conversation
 if (image.cid === conversation.id)
 // Get the list of members that have seen this event
 for (let member_id in image.state.seen_by) {
   if (conversation.me.id !== member_id) {
     console.log(conversation.members.get(member_id).name);
   }
 }
});

member:call:status

Conversation listening for members callStatus changes.

Properties:
Name Type Description
member Member

the member that has left

Source:
Example

get the callStatus of the member that changed call status

conversation.on("member:call:status", (member) => {
 console.log(member.callStatus);
});

member:invited

Conversation listening for members being invited.

Properties:
Name Type Description
member Member

the member that is invited

event NXMEvent

data regarding the receiver of the invitation

Source:
Example

get the name of the invited member

conversation.on("member:invited", (member, event) => {
 console.log(member.user.name + " invited to the conversation");
});

member:joined

Conversation listening for new members.

Properties:
Name Type Description
member Member

the member that joined

event NXMEvent

the join event

Source:
Example

get the name of the new member

conversation.on("member:joined", (member, event) => {
 console.log(event.id)
 console.log(member.user.name+ " joined the conversation");
});

member:left

Conversation listening for members leaving (kicked or left).

Properties:
Name Type Description
member Member

the member that has left

event NXMEvent

data regarding the receiver of the invitation

Source:
Example

get the username of the member that left

conversation.on("member:left", (member , event) => {
 console.log(member.user.name + " left");
 console.log(event.body.reason);
});

member:media

Conversation listening for members media changes (audio,text)

Change in media presence state. They are in the conversation with text or audio.

Properties:
Name Type Description
member Member

the member object linked to this event

event NXMEvent

information about media presence state

Properties
Name Type Description
body.audio boolean

is audio enabled

Source:
Example

get every member's media change events

conversation.on("member:media", (from, event) => {
 console.log(from.media.audio_settings.enabled); //true
	console.log(event.body.media); //{"audio_settings": {"enabled": true, "muted": false, "earmuffed": false}}
});

text:seen

Conversation listening for members' seen texts.

Properties:
Name Type Description
member Member

the member that saw the text

text TextEvent

the text that was seen

Source:
Example

listen for seen text events

conversation.on("text:seen", (data, text) => {
 console.log(text);
 // Check if the event belongs to this conversation
 if (text.cid === conversation.id)
 // Get the list of members that have seen this event
 for (let member_id in text.state.seen_by) {
   if (conversation.me.id !== member_id) {
     console.log(conversation.members.get(member_id).name);
   }
 }
});

text:typing:off

Conversation listening for members stopped typing.

Properties:
Name Type Description
member Member

the member that stopped typing

event NXMEvent

the stop typing event

Source:
Example

get the username of the member that stopped typing

conversation.on("text:typing:off", (data) => {
 console.log(data.name + " stopped typing...");
});

text:typing:on

Conversation listening for members typing.

Properties:
Name Type Description
member Member

the member that started typing

event NXMEvent

the start typing event

Source:
Example

get the username of the member that is typing

conversation.on("text:typing:on", (data) => {
 console.log(data.name + " is typing...");
});