DocStrap

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 uploading or sending an Image message to the conversation.

Parameters:
Name Type Description
imageRequest XMLHttpRequest
Source:
Returns:

void

Examples

cancel sending an image

conversation.sendImage(fileInput.files[0]).then((imageRequest) => {
   conversation.abortSendImage(imageRequest);
}).catch((error) => {
   console.error("error sending the image ", error);
});

cancel uploading an image

conversation.uploadImage(fileInput.files[0]).then((imageRequest) => {
   conversation.abortSendImage(imageRequest);
}).catch((error) => {
   console.error("error uploading the image ", error);
});

<async> del()

Delete a conversation

Source:
Returns:
Type
Promise
Example

delete the Conversation

conversation.del().then(() => {
   console.log("conversation deleted");
}).catch((error) => {
 console.error("error deleting conversation ", error);
});

deleteEvent(event)

Delete an NXMEvent (e.g. Text)

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

delete an Event

conversation.deleteEvent(eventToBeDeleted).then(() => {
 console.log("event was deleted");
}).catch((error) => {
 console.error("error deleting the event ", error);
});

<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)
  })
}).catch((error) => {
 console.error("error getting the events ", error);
});

<async> getMember(member_id)

Query the service to get a member in this conversation.

Parameters:
Name Type Description
member_id string

the id of the member to return
Source:
Returns:
Type
Promise.<Member>
Example

Get Member

conversation.getMember("MEM-id").then((member) => {
  render(member)
}).catch((error) => {
 console.error("error getting member", error);
});

<async> getMembers(params)

Query the service to get a list of members 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
Source:
Returns:
Type
Promise.<MembersPage.<Map.<Member>>>
Example

Get Members

const params = {
  order: "desc",
  page_size: 100
}
conversation.getMembers(params).then((members_page) => {
  members_page.items.forEach(member => {
    render(member)
  })
}).catch((error) => {
 console.error("error getting the members ", error);
});

<async> getMyMember()

Query the service to get my member in this conversation.

Source:
Returns:
Type
Promise.<Member>
Example

Get My Member

conversation.getMyMember().then((member) => {
  render(member)
}).catch((error) => {
 console.error("error getting my member", error);
});

<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 user_name 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 = 'id of User to invite';
const user_name = 'username of User to invite';

conversation.invite({
 id: user_id,
 user_name: user_name
}).then((member) => {
 displayMessage(member.state + " user: " + user_id + " " + user_name);
}).catch((error) => {
 console.error("error inviting user ", 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 user_name 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 = 'id of User to invite';
const user_name = 'username of User to invite';

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

<async> join(params)

Join the given User to this Conversation. Will typically be used 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 the Conversation

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

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
Example

leave the Conversation

conversation.leave({reason_code: "mycode", reason_text: "my reason for leaving"}).then(() => {
 console.log("successfully left conversation");
}).catch((error) => {
 console.error("error leaving conversation ", error);
});

<async> sendCustomEvent(params)

Send a custom event to the Conversation

Parameters:
Name Type Description
params object

params of the custom event

Properties
Name Type Description
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: { mykey: "my value" }}).then((event) => {
 console.log("custom event was sent", event);
}).catch((error)=>{
 console.error("error sending the custom event", error);
});

<async> sendImage(file, params)

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 Description
file File

single input file (jpeg/jpg)
params object

params of image sent

Properties
Name Type Argument Default Description
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
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
thumbnail_size_ratio string <optional>
 30

a value between 1 and 100. 1 indicates the new image is 1% of original, 100 - same size as original
Deprecated:
  • since version 8.3.0
Source:
Returns:
Type
Promise.<XMLHttpRequest>
Example

sending an image

const params = {
 quality_ratio : "90",
 medium_size_ratio: "40",
 thumbnail_size_ratio: "20"
}
conversation.sendImage(fileInput.files[0], params).then((imageRequest) => {
 imageRequest.onprogress = (e) => {
   console.log("Image request progress: ", e);
   console.log("Image progress: " + e.loaded + "/" + e.total);
 };
 imageRequest.onabort = (e) => {
   console.log("Image request aborted: ", e);
   console.log("Image: " + e.type);
 };
 imageRequest.onloadend = (e) => {
   console.log("Image request successful: ", e);
   console.log("Image: " + e.type);
 };
}).catch((error) => {
 console.error("error sending the image ", error);
});

<async> sendMessage(params)

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

Parameters:
Name Type Description
params object

the content of the message you want sent

Properties
Name Type Argument Description
message_type string

the type of the message. It should be one of 'text', 'image', 'audio', 'video', 'file'
text string <optional>

the text content when message type is 'text
image object <optional>
Properties
Name Type Description
url string

the image url when message type is 'image'
audio object <optional>
Properties
Name Type Description
url string

the audio url when message type is 'audio'
video object <optional>
Properties
Name Type Description
url string

the video url when message type is 'video'
file object <optional>
Properties
Name Type Description
url string

the file url when message type is 'file'
Source:
Returns:
  • the message that was sent
Type
Promise.<MessageEvent>
Example

sending a message 

conversation.sendMessage({ "message_type": "text", "text": "Hi Vonage!" }).then((event) => {
 console.log("message was sent", event);
}).catch((error)=>{
 console.error("error sending the message ", error);
});

<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
Deprecated:
  • since version 8.3.0
Source:
Returns:
  • the text message that was sent
Type
Promise.<TextEvent>
Example

sending a text 

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

startTyping()

Send start typing indication

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

send start typing event when key is pressed

messageTextarea.addEventListener('keypress', (event) => {
   conversation.startTyping();
});

stopTyping()

Send stop typing indication

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

send stop typing event when a key has not been pressed for half a second

let timeout = null;
messageTextarea.addEventListener('keyup', (event) => {
   clearTimeout(timeout);
   timeout = setTimeout(() => {
     conversation.stopTyping();
   }, 500);
});

<async> uploadImage(file, params)

Uploads an Image to Media Service.
implements xhr (https://xhr.spec.whatwg.org/) - this.imageRequest

Parameters:
Name Type Description
file File

single input file (jpeg/jpg)
params object

params of image sent

Properties
Name Type Argument Default Description
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
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
thumbnail_size_ratio string <optional>
 30

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

uploading an image

const params = {
 quality_ratio : "90",
 medium_size_ratio: "40",
 thumbnail_size_ratio: "20"
}
conversation.uploadImage(fileInput.files[0], params).then((uploadImageRequest) => {
 uploadImageRequest.onprogress = (e) => {
   console.log("Image request progress: ", e);
   console.log("Image progress: " + e.loaded + "/" + e.total);
 };
 uploadImageRequest.onabort = (e) => {
   console.log("Image request aborted: ", e);
   console.log("Image: " + e.type);
 };
 uploadImageRequest.onloadend = (e) => {
   console.log("Image request successful: ", e);
   console.log("Image: " + e.type);
 };
 uploadImageRequest.onreadystatechange = () => {
   if (uploadImageRequest.readyState === 4 && uploadImageRequest.status === 200) {
     const representations = JSON.parse(uploadImageRequest.responseText);
     console.log("Original image url: ", representations.original.url);
     console.log("Medium image url: ", representations.medium.url);
     console.log("Thumbnail image url: ", representations.thumbnail.url);
   }
 };
}).catch((error) => {
   console.error("error uploading the image ", error);
});

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:
Example

listen for audio mute off events 

conversation.on("audio:mute:off", (member, event) => {
 console.log("member that is unmuted ", member);
 console.log(event);
});

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:
Example

listen for audio mute on events 

conversation.on("audio:mute:on", (member, event) => {
 console.log("member that is muted ", member);
 console.log(event);
});

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 if your own imageEvent or someone else's.
   if (image.from !== conversation.me.id){
       displayImages(image);
   }
 });

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){
       renderMyMessages(message)
   } else {
       renderOtherMessages(message)
   }
 });

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", (member, image) => {
 console.log(image);
 if (conversation.me.id !== member.memberId) {
   console.log(member);
 };
});

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.userName + " 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.userName+ " 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.userName + " 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", (member, event) => {
 console.log(event.body.media); //{"audio": true, "audio_settings": {"enabled": true, "muted": false, "earmuffed": false}}
});

message:delivered

Conversation listening for Members delivered messages.

Properties:
Name Type Description
member Member

the member that message was delivered to
message MessageEvent

the message that was delivered
Source:
Example

listen for delivered message events

conversation.on("message:delivered", (member, message) => {
 console.log(message);
 if (conversation.me.id !== member.memberId) {
   console.log(member);
 };
});

message:rejected

Conversation listening for Members rejected messages.

Properties:
Name Type Description
member Member

the member that message was rejected by
message MessageEvent

the message that was rejected
Source:
Example

listen for rejected message events

conversation.on("message:rejected", (member, message) => {
 console.log(message);
 if (conversation.me.id !== member.memberId) {
   console.log(member);
 };
});

message:seen

Conversation listening for Members seen messages.

Properties:
Name Type Description
member Member

the member that message was seen by
message MessageEvent

the message that was seen
Source:
Example

listen for seen message events

conversation.on("message:seen", (member, message) => {
 console.log(message);
 if (conversation.me.id !== member.memberId) {
   console.log(member);
 };
});

message:submitted

Conversation listening for Members submitted messages.

Properties:
Name Type Description
member Member

the member that message was submitted to
message MessageEvent

the message that was submitted
Source:
Example

listen for submitted message events

conversation.on("message:submitted", (member, message) => {
 console.log(message);
 if (conversation.me.id !== member.memberId) {
   console.log(member);
 };
});

message:undeliverable

Conversation listening for Members undeliverable messages.

Properties:
Name Type Description
member Member

the member that message was undeliverable to
message MessageEvent

the message that was undeliverable
Source:
Example

listen for undeliverable message events

conversation.on("message:undeliverable", (member, message) => {
 console.log(message);
 if (conversation.me.id !== member.memberId) {
   console.log(member);
 };
});

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", (member, text) => {
 console.log(text);
 if (conversation.me.id !== member.memberId) {
   console.log(member);
 }
});

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 display name of the Member that stopped typing

conversation.on("text:typing:off", (member, event) => {
 console.log(member.displayName + " 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 display name of the Member that is typing

conversation.on("text:typing:on", (member, event) => {
 console.log(member.displayName + " is typing...");
});