@twilio/conversations
Options
All
  • Public
  • Public/Protected
  • All
Menu

A client is the starting point to the Twilio Conversations functionality.

Hierarchy

  • ReplayEventEmitter<ClientEvents>
    • Client

Index

Constructors

Events

Properties

Accessors

Methods

Constructors

constructor

  • Returned Conversations instance is not yet fully initialized. Calling any operations will block until it is. Use connection events to monitor when client becomes fully available (connectionStateChanged with state 'connected') or not available (connectionStateChange with state 'denied', event tokenExpired, event connectionError).

    Parameters

    • fpaToken: string

      Access token

    • options: ClientOptions = {}

      Options to customize the Client

    Returns Client

    A not yet fully-initialized client.

Events

Static Readonly connectionError

connectionError: "connectionError" = "connectionError"

Fired when the connection is interrupted for an unexpected reason.

Parameters:

  1. object data - info object provided with the event. It has the following properties:
    • boolean terminal - Twilsock will stop connection attempts if true
    • string message - the error message of the root cause
    • number? httpStatusCode - http status code if available
    • number? errorCode - Twilio public error code if available

Static Readonly connectionStateChanged

connectionStateChanged: "connectionStateChanged" = "connectionStateChanged"

Fired when the connection state of the client has been changed.

Paremeters:

  1. ConnectionState state - the new connection state

Static Readonly conversationAdded

conversationAdded: "conversationAdded" = "conversationAdded"

Fired when a conversation becomes visible to the client. The event is also triggered when the client creates a new conversation. Fired for all conversations client has joined.

Parameters:

  1. Conversation conversation - the conversation in question

Static Readonly conversationJoined

conversationJoined: "conversationJoined" = "conversationJoined"

Fired when the client joins a conversation.

Parameters:

  1. Conversation conversation - the conversation in question

Static Readonly conversationLeft

conversationLeft: "conversationLeft" = "conversationLeft"

Fired when the client leaves a conversation.

Parameters:

  1. Conversation conversation - the conversation in question

Static Readonly conversationRemoved

conversationRemoved: "conversationRemoved" = "conversationRemoved"

Fired when a conversation is no longer visible to the client.

Parameters:

  1. Conversation conversation - the conversation in question

Static Readonly conversationUpdated

conversationUpdated: "conversationUpdated" = "conversationUpdated"

Fired when the attributes or the metadata of a conversation have been updated. During conversation's creation and initialization, this event might be fired multiple times for same joined or created conversation as new data is arriving from different sources.

Parameters:

  1. object data - info object provided with the event. It has the following properties:

Static Readonly messageAdded

messageAdded: "messageAdded" = "messageAdded"

Fired when a new message has been added to the conversation on the server.

Parameters:

  1. Message message - the message in question

Static Readonly messageRemoved

messageRemoved: "messageRemoved" = "messageRemoved"

Fired when a message is removed from the message list of a conversation.

Parameters:

  1. Message message - the message in question

Static Readonly messageUpdated

messageUpdated: "messageUpdated" = "messageUpdated"

Fired when the fields of an existing message are updated with new values.

Parameters:

  1. object data - info object provided with the event. It has the following properties:

Static Readonly participantJoined

participantJoined: "participantJoined" = "participantJoined"

Fired when a participant has joined a conversation.

Parameters:

  1. Participant participant - the participant in question

Static Readonly participantLeft

participantLeft: "participantLeft" = "participantLeft"

Fired when a participant has left a conversation.

Parameters:

  1. Participant participant - the participant in question

Static Readonly participantUpdated

participantUpdated: "participantUpdated" = "participantUpdated"

Fired when a participant's fields have been updated.

Parameters:

  1. object data - info object provided with the event. It has the following properties:

Static Readonly pushNotification

pushNotification: "pushNotification" = "pushNotification"

Fired when the client has received (and parsed) a push notification via one of the push channels (apn or fcm).

Parameters:

  1. PushNotification pushNotification - the push notification in question

Static Readonly stateChanged

stateChanged: "stateChanged" = "stateChanged"

Fired when the state of the client has been changed.

Parameters:

  1. State state - the new client state

Static Readonly tokenAboutToExpire

tokenAboutToExpire: "tokenAboutToExpire" = "tokenAboutToExpire"

Fired when the token is about to expire and needs to be updated.

  • Parameters:
  1. number message - token's time to live

Static Readonly tokenExpired

tokenExpired: "tokenExpired" = "tokenExpired"

Fired when the token has expired.

Static Readonly typingEnded

typingEnded: "typingEnded" = "typingEnded"

Fired when a participant has stopped typing.

Parameters:

  1. Participant participant - the participant in question

Static Readonly typingStarted

typingStarted: "typingStarted" = "typingStarted"

Fired when a participant has started typing.

Parameters:

  1. Participant participant - the participant in question

Static Readonly userSubscribed

userSubscribed: "userSubscribed" = "userSubscribed"

Fired when the client has subscribed to a user.

Parameters:

  1. User user - the user in question

Static Readonly userUnsubscribed

userUnsubscribed: "userUnsubscribed" = "userUnsubscribed"

Fired when the client has unsubscribed from a user.

Parameters:

  1. User user - the user in question

Static Readonly userUpdated

userUpdated: "userUpdated" = "userUpdated"

Fired when the properties or the reachability status of a user have been updated.

Parameters:

  1. object data - info object provided with the event. It has the following properties:
    • User user - the user in question
    • UserUpdateReason[] updateReasons - array of reasons for the update

Properties

connectionState

connectionState: ConnectionState = "unknown"

Client connection state.

Readonly version

version: string = ...

Current version of the Conversations client.

Static Readonly version

version: string = ...

Current version of the Conversations client.

Accessors

reachabilityEnabled

  • get reachabilityEnabled(): boolean

  • Client reachability state. Throws if accessed before the client initialization was completed.

    Returns boolean

user

  • Information of the logged-in user. Before client initialization, returns an uninitialized user. Will trigger a Client.userUpdated event after initialization.

    Returns User

Methods

createConversation

  • Create a conversation on the server and subscribe to its events. The default is a conversation with an empty friendly name.

    Parameters

    Returns Promise<Conversation>

getConversationBySid

  • getConversationBySid(conversationSid: string): Promise<Conversation>

  • Get a known conversation by its SID.

    Parameters

    • conversationSid: string

      Conversation sid

    Returns Promise<Conversation>

getConversationByUniqueName

  • getConversationByUniqueName(uniqueName: string): Promise<Conversation>

  • Get a known conversation by its unique identifier name.

    Parameters

    • uniqueName: string

      The unique identifier name of the conversation.

    Returns Promise<Conversation>

getSubscribedConversations

getSubscribedUsers

  • getSubscribedUsers(): Promise<User[]>

  • Get a list of subscribed user objects.

    Returns Promise<User[]>

getUser

  • getUser(identity: string): Promise<User>

  • Gets a user with the given identity. If it's in the subscribed list, then return the user object from it; if not, then subscribe and add user to the subscribed list.

    Parameters

    • identity: string

      Identity of the user.

    Returns Promise<User>

    A fully initialized user.

handlePushNotification

  • handlePushNotification(notificationPayload: any): Promise<void>

  • Handle push notification payload parsing and emit the Client.pushNotification event on this Client instance.

    Parameters

    • notificationPayload: any

      Push notification payload

    Returns Promise<void>

removePushRegistrations

  • removePushRegistrations(channelType: ChannelType, registrationId: string): Promise<void>

  • Clear existing registrations directly using provided device token. This is useful to ensure stopped subscriptions without resubscribing.

    This function goes completely beside the state machine and removes all registrations. Use with caution: if it races with current state machine operations, madness will ensue.

    Parameters

    • channelType: ChannelType

      Channel type.

    • registrationId: string

      Push notification ID provided by the FCM/APNS service on the platform.

    Returns Promise<void>

setPushRegistrationId

  • setPushRegistrationId(channelType: ChannelType, registrationId: string): Promise<void>

  • Register for push notifications.

    Parameters

    • channelType: ChannelType

      Channel type.

    • registrationId: string

      Push notification ID provided by the FCM/APNS service on the platform.

    Returns Promise<void>

shutdown

  • shutdown(): Promise<void>

  • Gracefully shut down the client.

    Returns Promise<void>

unsetPushRegistrationId

  • unsetPushRegistrationId(channelType: ChannelType): Promise<void>

  • Unregister from push notifications.

    deprecated

    Use removePushRegistrations() instead.

    Parameters

    • channelType: ChannelType

      Channel type.

    Returns Promise<void>

updateToken

  • updateToken(token: string): Promise<Client>

  • Update the token used by the client and re-register with the Conversations services.

    Parameters

    • token: string

      New access token.

    Returns Promise<Client>

Static parsePushNotification

  • Static method for push notification payload parsing. Returns parsed push as a PushNotification object.

    Parameters

    • notificationPayload: any

      Push notification payload.

    Returns PushNotification