Documentation Class: Conversation

Properties:

Name	Type	Argument	Description
`attributes`	any		The Conversation's custom attributes
`createdBy`	String		The identity of the User that created this Conversation
`dateCreated`	Date		The Date this Conversation was created
`dateUpdated`	Date		The Date this Conversation was last updated
`friendlyName`	String	<optional>	The Conversation's name
`lastReadMessageIndex`	Number \| null		Index of the last Message the User has read in this Conversation
`lastMessage`	Conversation#LastMessage		Last Message sent to this Conversation
`notificationLevel`	Conversation#NotificationLevel		User Notification level for this Conversation
`sid`	String		The Conversation's unique system identifier
`status`	Conversation#Status		The Conversation's status
`state`	Conversation#State		The Conversation's state
`uniqueName`	String		The Conversation's unique name

Fires:

Methods

add(identity [, attributes])

Add a participant to the Conversation by its Identity.

Parameters:

Name	Type	Argument	Description
`identity`	String		Identity of the Client to add
`attributes`	any	<optional>	Attributes to be attached to the participant

Returns:

Type: Promise.<void>

addNonChatParticipant(proxyAddress, address [, attributes])

Add a non-chat participant to the Conversation.

Parameters:

Name	Type	Argument	Description
`proxyAddress`	String		Proxy (Twilio) address of the participant
`address`	String		User address of the participant
`attributes`	any	<optional>	Attributes to be attached to the participant

Returns:

Type: Promise.<void>

advanceLastReadMessageIndex(index)

Advance Conversation's last read Message index to current read horizon. Rejects if User is not Participant of Conversation. Last read Message index is updated only if new index value is higher than previous.

Parameters:

Name	Type	Description
`index`	Number	Message index to advance to as last read

Returns:

resulting unread messages count in the conversation

Type: Promise.<number>

delete()

Delete the Conversation and unsubscribe from its events.

Returns:

Type: Promise.<Conversation>

getAttributes()

Get the custom attributes of this Conversation.

Returns:

attributes of this Conversation

Type: Promise.<any>

getMessages( [pageSize] [, anchor] [, direction])

Returns messages from conversation using paginator interface.

Parameters:

Name	Type	Argument	Default	Description
`pageSize`	Number	<optional>	30	Number of messages to return in single chunk
`anchor`	Number	<optional>		Index of newest Message to fetch. From the end by default
`direction`	'backwards' \| 'forward'	<optional>	backwards	Query direction. By default it query backwards from newer to older. 'forward' will query in opposite direction

Returns:

page of messages

Type: Promise.<Paginator.<Message>>

getMessagesCount()

Get total message count in a conversation.
This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversations system does not provide real time events for counter values changes.
So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time.

Returns:

Type: Promise.<number>

getParticipantByIdentity(identity)

Get a Participant by its identity.

Parameters:

Name	Type	Description
`identity`	String	Participant identity

Returns:

Type: Promise.<Participant>

getParticipantBySid(participantSid)

Get a Participant by its SID.

Parameters:

Name	Type	Description
`participantSid`	String	Participant sid

Returns:

Type: Promise.<Participant>

getParticipants()

Get a list of all Participants joined to this Conversation.

Returns:

Type: Promise.<Array.<Participant>>

getParticipantsCount()

Get conversation participants count.
This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversation system does not provide real time events for counter values changes.
So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time.

Returns:

Type: Promise.<number>

getUnreadMessagesCount()

Get unread messages count for the User if they are a Participant of this Conversation. Rejects if the User is not a Participant of the Conversation.
Use this method to obtain the number of unread messages together with updateLastReadMessageIndex() instead of relying on the Message indices which may have gaps. See Message.index for details.
This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Chat system does not provide real time events for counter values changes.
This is quite useful for any “unread messages count” badges, but is not recommended to build any core application logic based on these counters being accurate in real time.

Returns:

Type: Promise.<(number|null)>

join()

Join the Conversation and subscribe to its events.

Returns:

Type: Promise.<Conversation>

leave()

Leave the Conversation.

Returns:

Type: Promise.<Conversation>

removeParticipant(participant)

Remove a Participant from the Conversation. When a string is passed as the argument, it will assume that the string is an identity.

Parameters:

Name	Type	Description
`participant`	String \| Participant	identity or participant object to remove

Returns:

Type: Promise.<void>

sendMessage(message [, messageAttributes] [, emailOptions])

Send a Message in the Conversation.

Parameters:

Name	Type	Argument	Description
`message`	String \| FormData \| Conversation#SendMediaOptions \| null		The message body for text message, FormData or MediaOptions for media content. Sending FormData supported only with browser engine
`messageAttributes`	any	<optional>	attributes for the message
`emailOptions`	Conversation#SendEmailOptions	<optional>	email options for the message

Returns:

new Message's index in the Conversation's messages list

Type: Promise.<number>

setAllMessagesRead()

Set last read Conversation's Message index to last known Message's index in this Conversation.

Returns:

resulting unread messages count in the conversation

Type: Promise.<number>

setAllMessagesUnread()

Set all messages in the conversation unread.

Returns:

resulting unread messages count in the conversation

Type: Promise.<number>

setUserNotificationLevel(notificationLevel)

Set User Notification level for this conversation.

Parameters:

Name	Type	Description
`notificationLevel`	Conversation#NotificationLevel	The new user notification level

Returns:

Type: Promise.<void>

typing()

Send a notification to the server indicating that this Client is currently typing in this Conversation. Typing ended notification is sent after a while automatically, but by calling again this method you ensure typing ended is not received.

Returns:

Type: Promise.<void>

updateAttributes(attributes)

Update the Conversation's attributes.

Parameters:

Name	Type	Description
`attributes`	any	The new attributes object

Returns:

Type: Promise.<Conversation>

updateFriendlyName(name)

Update the Conversation's friendlyName.

Parameters:

Name	Type	Description
`name`	String \| null	The new Conversation friendlyName

Returns:

Type: Promise.<Conversation>

updateLastReadMessageIndex(index)

Set Conversation's last read Message index to current read horizon.

Parameters:

Name	Type	Description
`index`	Number \| null	Message index to set as last read. If null provided, then the behavior is identical to Conversation#setAllMessagesUnread

Returns:

resulting unread messages count in the conversation

Type: Promise.<number>

updateUniqueName(uniqueName)

Update the Conversation's unique name.

Parameters:

Name	Type	Description
`uniqueName`	String \| null	New unique name for the Conversation. Setting unique name to null removes it.

Returns:

Type: Promise.<Conversation>

Type Definitions

LastMessage

The Conversation's last message's information.

Type:

Object

Properties:

Name	Type	Description
`index`	Number	Message's index
`dateCreated`	Date	Message's creation date

NotificationLevel

The User's Notification level for Conversation, determines whether the currently logged-in User will receive pushes for events in this Conversation. Can be either muted or default, where default defers to global Service push configuration.

Type:

'default' | 'muted'

SendEmailOptions

These options can be passed to Conversation#sendMessage.

Type:

Object

Properties:

Name	Type	Description
`subject`	String	subject for the message. Ignored for media messages.

SendMediaOptions

These options can be passed to Conversation#sendMessage.

Type:

Object

Properties:

Name	Type	Description
`contentType`	String	content type of media
`media`	String \| Buffer	content to post

State

The Conversation's state.

Type:

Object

Properties:

Name	Type	Description
`current`	'active' \| 'inactive' \| 'closed'	the current state
`dateUpdated`	Date	date at which the latest conversation state update happened

Status

The status of the Conversation, relative to the Client: whether the Conversation has been joined or the Client is notParticipating in the Conversation.

Type:

'notParticipating' | 'joined'

UpdateReason

The update reason for updated event emitted on Conversation

Type:

'attributes' | 'createdBy' | 'dateCreated' | 'dateUpdated' | 'friendlyName' | 'lastReadMessageIndex' | 'state' | 'status' | 'uniqueName' | 'lastMessage' | 'notificationLevel'