Class: Conversation

Conversation

A Conversation represents communication between multiple Conversations Clients

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'

Events


messageAdded

Fired when a new Message has been added to the Conversation.
Type: Message

messageRemoved

Fired when Message is removed from Conversation's message list.
Type: Message

messageUpdated

Fired when an existing Message's fields are updated with new values.
Type: Object
Properties:
Name Type Description
message Message Updated Message
updateReasons Array.<Message#UpdateReason> Array of Message's updated event reasons

participantJoined

Fired when a Participant has joined the Conversation.
Type: Participant

participantLeft

Fired when a Participant has left the Conversation.
Type: Participant

participantUpdated

Fired when a Participant's fields has been updated.
Type: Object
Properties:
Name Type Description
participant Participant Updated Participant
updateReasons Array.<Participant#UpdateReason> Array of Participant's updated event reasons

removed

Fired when the Conversation was destroyed or currently logged in User has left private Conversation
Type: Conversation

typingEnded

Fired when a Participant has stopped typing.
Type: Participant

typingStarted

Fired when a Participant has started typing.
Type: Participant

updated

Fired when a Conversation's attributes or metadata have been updated.
Type: Object
Properties:
Name Type Description
conversation Conversation Updated Conversation
updateReasons Array.<Conversation#UpdateReason> Array of Conversation's updated event reasons