Options
All
  • Public
  • Public/Protected
  • All
Menu

Twilio Conversations client library

Twilio Conversations: Create meaningful connections with customers across various communication channels. Visit our official site for more detalis: https://www.twilio.com/conversations

Instantiating and using

To use the library you need to generate a token and pass it to the conversations Client create factory.

NPM

npm install --save @twilio/conversations

Using this method, you can require twilio-conversations and then use the client:

const { Client } = require('@twilio/conversations');
const client = new Client(token);
// Before you use the client, subscribe to the `'stateChanged'` event and wait 
// for the `'initialized'` state to be reported.
client.on('stateChanged', (state) => {
  if (state === 'initialized') {
    // Use the client
  }
}

The SDK could also be imported using the ES module syntax:

import { Client } from '@twilio/conversations';
const client = new Client(token);
// Before you use the client, subscribe to the `'stateChanged'` event and wait 
// for the `'initialized'` state to be reported.
client.on('stateChanged', (state) => {
  if (state === 'initialized') {
    // Use the client
  }
}

CDN

Releases of twilio-conversations.js are hosted on a CDN, and you can include these directly in your web app using a <script> tag.

<script src="https://media.twiliocdn.com/sdk/js/conversations/v2.0/twilio-conversations.min.js"></script>

Using this method, twilio-conversations.js will set a browser global Twilio.Conversations through which you can use the client :

Twilio.Conversations.Client.create(token).then(client => {
    // Use client
});

or, if you prefer async/await syntax:

let client = await Twilio.Conversations.Client.create(token);
// Use client

Security

The CDN consumption described above allows you to consume latest bug fixed versions automatically, but does not prevent from detecting malicious modifications in the SDK code.

If you require more security you will have to consume SDK by using SRI and using an exact version number. While less flexible it is significantly more secure, which is required by some applications.

To consume securely use the following script snippet format:

<script src="https://media.twiliocdn.com/sdk/js/conversations/releases/2.0.0/twilio-conversations.min.js"
        integrity="sha256-<HASH FROM THE CHANGELOGS PAGE>"
        crossorigin="anonymous"></script>

Find the hash of each release published on the Changelog page.

Supported Browsers

BrowserSupported Versions
Chrome for Android94
Firefox for Android92
UC Browser for Android12.12
Chrome94, 93, 92
Edge94, 93, 92
Firefox93, 92, 91
Internet Explorer11
Safari for iOS15, 14.5-14.8
Safari15, 14.1, 14
Samsung Internet15.0, 14.0

Changelog

See this link.

Index

Type aliases

ConnectionState

ConnectionState: TwilsockConnectionState

Connection state of the client. Possible values are as follows:

  • 'connecting' - client is offline and connection attempt is in process
  • 'connected' - client is online and ready
  • 'disconnecting' - client is going offline as disconnection is in process
  • 'disconnected' - client is offline and no connection attempt is in process
  • 'denied' - client connection is denied because of invalid JWT access token. User must refresh token in order to proceed

ConversationStatus

ConversationStatus: "notParticipating" | "joined"

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

ConversationUpdateReason

ConversationUpdateReason: "attributes" | "createdBy" | "dateCreated" | "dateUpdated" | "friendlyName" | "lastReadMessageIndex" | "state" | "status" | "uniqueName" | "lastMessage" | "notificationLevel"

The reason for the updated event being emitted by a conversation.

DeliveryAmount

DeliveryAmount: "none" | "some" | "all"

Signifies the amount of participants which have the status for the message.

DeliveryStatus

DeliveryStatus: "sent" | "delivered" | "failed" | "read" | "undelivered" | "queued"

Message delivery status.

MediaCategory

MediaCategory: McsMediaCategory

Category of media. Possible values are as follows:

  • 'media'
  • 'body'
  • 'history'

MessageType

MessageType: "text" | "media"

Type of a message.

MessageUpdateReason

MessageUpdateReason: "body" | "lastUpdatedBy" | "dateCreated" | "dateUpdated" | "attributes" | "author" | "deliveryReceipt" | "subject"

The reason for the updated event being emitted by a message.

NotificationLevel

NotificationLevel: "default" | "muted"

The user's notification level for the 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 the global service push configuration.

NotificationsChannelType

NotificationsChannelType: ChannelType

Notifications channel type. Possible values are as follows:

  • 'fcm'
  • 'apn'

ParticipantType

ParticipantType: "chat" | "sms" | "whatsapp"

Type of a participant.

ParticipantUpdateReason

ParticipantUpdateReason: "attributes" | "dateCreated" | "dateUpdated" | "roleSid" | "lastReadMessageIndex" | "lastReadTimestamp"

The reason for the updated event being emitted by a participant.

PushNotificationType

PushNotificationType: "twilio.conversations.new_message" | "twilio.conversations.added_to_conversation" | "twilio.conversations.removed_from_conversation"

Push notification type.

State

State: "failed" | "initialized"

State of the client. Possible values are as follows:

  • 'failed' - the client failed to initialize
  • 'initialized' - the client successfully initialized

UserUpdateReason

UserUpdateReason: "friendlyName" | "attributes" | "reachabilityOnline" | "reachabilityNotifiable"

The reason for the updated event being emitted by a user.