new Conversation()
A single conversation Object.
- Source:
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 |
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 benull
.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 givenParameters:
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.imageRequestParameters:
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.imageRequestParameters:
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- Source:
Properties:
Name Type Description member
Member the member object linked to this event
event
NXMEvent information about the mute event
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- Source:
Properties:
Name Type Description member
Member the Member object linked to this event
event
NXMEvent information about the mute event
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.
- Source:
Properties:
Name Type Description member
Member the Member who deleted an event
event
NXMEvent deleted event: event.id
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.
- Source:
Properties:
Name Type Description sender
Member The sender of the image
image
ImageEvent The image message received
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.
- Source:
Properties:
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.
- Source:
Properties:
Name Type Description member
Member the member that saw the image
image
ImageEvent the image that was seen
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.
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.
- Source:
Properties:
Name Type Description member
Member the Member that is invited
event
NXMEvent data regarding the receiver of the invitation
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.
- Source:
Properties:
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).
- Source:
Properties:
Name Type Description member
Member the Member that has left
event
NXMEvent data regarding the receiver of the invitation
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.
- Source:
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
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.
- Source:
Properties:
Name Type Description member
Member the member that message was delivered to
message
MessageEvent the message that was delivered
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.
- Source:
Properties:
Name Type Description member
Member the member that message was rejected by
message
MessageEvent the message that was rejected
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.
- Source:
Properties:
Name Type Description member
Member the member that message was seen by
message
MessageEvent the message that was seen
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.
- Source:
Properties:
Name Type Description member
Member the member that message was submitted to
message
MessageEvent the message that was submitted
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.
- Source:
Properties:
Name Type Description member
Member the member that message was undeliverable to
message
MessageEvent the message that was undeliverable
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.
- Source:
Properties:
Name Type Description member
Member the Member that saw the text
text
TextEvent the text that was seen
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.
- Source:
Properties:
Name Type Description member
Member the member that stopped typing
event
NXMEvent the stop typing event
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.
- Source:
Properties:
Name Type Description member
Member the member that started typing
event
NXMEvent the start typing event
Example
get the display name of the Member that is typing
conversation.on("text:typing:on", (member, event) => { console.log(member.displayName + " is typing..."); });