@twilio/conversations
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 constructor.

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 `'initialized'` event.
client.on('initialized', () => {
  // Use the client.
});

// To catch client initialization errors, subscribe to the `'initFailed'` event.
client.on('initFailed', ({ error }) => {
  // Handle the error.
});

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 `'initialized'` event.
client.on('initialized', () => {
  // Use the client.
});

// To catch client initialization errors, subscribe to the `'initFailed'` event.
client.on('initFailed', ({ error }) => {
  // Handle the error.
});

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://sdk.twilio.com/js/conversations/v2.5/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:

const client = new Twilio.Conversations.Client(token);

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://sdk.twilio.com/js/conversations/releases/2.5.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 Android118
Firefox for Android118
UC Browser for Android15.5
Chrome118, 117, 116
Edge118, 117, 116
Firefox118, 117, 116
Internet Explorer11
Safari for iOS17.0, 16.6
Safari17.0, 16.6, 16.5
Samsung Internet22, 21

Changelog

See this link.

Index

Classes

Interfaces

Type aliases

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

ContentData

ContentData: ContentDataText | ContentDataMedia | ContentDataLocation | ContentDataQuickReply | ContentDataCallToAction | ContentDataListPicker | ContentDataCard | ContentDataOther

A union of possible data types in rich content templates.

ContentDataAction

ContentDataAction: ContentDataActionUrl | ContentDataActionPhone | ContentDataActionReply | ContentDataActionOther

A union of possible actions used in ContentDataCallToAction and ContentDataCard.

ContentDataActionOther

ContentDataActionOther: { rawData: string; type: "other" }

Used for unknown action types which aren't present in the current version of the Conversations SDK.

Type declaration

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly type: "other"

    The type discriminant.

ContentDataActionPhone

ContentDataActionPhone: { phone: string; rawData: string; title: string; type: "phone" }

Shows a button that calls a phone number.

Type declaration

  • Readonly phone: string

    Phone number to call when the recipient taps the button.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly title: string

    Display value for the action.

  • Readonly type: "phone"

    The type discriminant.

ContentDataActionReply

ContentDataActionReply: { id?: string; index: number; rawData: string; title: string; type: "reply" }

Shows a button that sends back a predefined text.

Type declaration

  • Optional Readonly id?: string

    Postback payload. This field is not visible to the end user.

  • Readonly index: number

    Index for the action.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly title: string

    Display value for the action. This is the message that will be sent back when the user taps on the button.

  • Readonly type: "reply"

    The type discriminant.

ContentDataActionUrl

ContentDataActionUrl: { rawData: string; title: string; type: "url"; url: string }

Shows a button that redirects recipient to a predefined URL.

Type declaration

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly title: string

    Display value for the action.

  • Readonly type: "url"

    The type discriminant.

  • Readonly url: string

    URL to direct to when the recipient taps the button.

ContentDataCallToAction

ContentDataCallToAction: { actions: ContentDataAction[]; body: string; rawData: string; type: "callToAction" }

Buttons that let recipients tap to trigger actions such as launching a website or making a phone call. Represents the twilio/call-to-action content type.

Type declaration

  • Readonly actions: ContentDataAction[]

    Buttons that recipients can tap on to act on the message.

  • Readonly body: string

    The text of the message you want to send. This is included as a regular text message.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly type: "callToAction"

    The type discriminant.

ContentDataCard

ContentDataCard: { actions: ContentDataAction[]; media: string[]; rawData: string; subtitle?: string; title: string; type: "card" }

Shows a menu of up to 10 options, which offers a simple way for users to make a selection. Represents the twilio/card content type.

Type declaration

  • Readonly actions: ContentDataAction[]

    Buttons that the recipients can tap on to act on the message.

  • Readonly media: string[]

    URLs of the media to send with the message.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Optional Readonly subtitle?: string

    Subtitle of the card.

  • Readonly title: string

    Title of the card.

  • Readonly type: "card"

    The type discriminant.

ContentDataListItem

ContentDataListItem: { description?: string; id: string; item: string }

Represents an item in the ContentDataListPicker.

Type declaration

  • Optional Readonly description?: string

    Description of the item.

  • Readonly id: string

    Unique item identifier. Not visible to the recipient.

  • Readonly item: string

    Display value of the item.

ContentDataListPicker

ContentDataListPicker: { body: string; button: string; items: ContentDataListItem[]; rawData: string; type: "listPicker" }

Shows a menu of up to 10 options, which offers a simple way for users to make a selection. Represents the twilio/list-picker content type.

Type declaration

  • Readonly body: string

    The text of the message you want to send. This is rendered as the body of the message.

  • Readonly button: string

    Display value of the primary button.

  • Readonly items: ContentDataListItem[]

    List item objects displayed in the list. See ContentDataListItem.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly type: "listPicker"

    The type discriminant.

ContentDataLocation

ContentDataLocation: { label?: string; latitude: number; longitude: number; rawData: string; type: "location" }

Contains a location pin and an optional label, which can be used to enhance delivery notifications or connect recipients to physical experiences you offer. Represents the twilio/location content type.

Type declaration

  • Optional Readonly label?: string

    The label to be displayed to the end user alongside the location pin.

  • Readonly latitude: number

    The latitude value of the location pin you want to send.

  • Readonly longitude: number

    The longitude value of the location pin you want to send.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly type: "location"

    The type discriminant.

ContentDataMedia

ContentDataMedia: { body?: string; media: string[]; rawData: string; type: "media" }

Used to send file attachments, or to send long texts via MMS in the US and Canada. Represents the twilio/media content type.

Type declaration

  • Optional Readonly body?: string

    The text of the message you want to send.

  • Readonly media: string[]

    URLs of the media you want to send.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly type: "media"

    The type discriminant.

ContentDataOther

ContentDataOther: { rawData: string; type: "other" }

Used for unknown content types which aren't present in the current version of the Conversations SDK.

Type declaration

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly type: "other"

    The type discriminant.

ContentDataQuickReply

ContentDataQuickReply: { body: string; rawData: string; replies: ContentDataReply[]; type: "quickReply" }

Let recipients tap, rather than type, to respond to the message. Represents the twilio/quick-reply content type.

Type declaration

  • Readonly body: string

    The text of the message you want to send. This is included as a regular text message.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly replies: ContentDataReply[]

    Up to 3 buttons can be created for quick reply. See ContentDataReply.

  • Readonly type: "quickReply"

    The type discriminant.

ContentDataReply

ContentDataReply: { id?: string; title: string }

Shows a button that sends back a predefined text. Used in ContentDataQuickReply.

Type declaration

  • Optional Readonly id?: string

    Postback payload. This field is not visible to the end user.

  • Readonly title: string

    Display value of the action. This is the message that will be sent back when the user taps on the button.

ContentDataText

ContentDataText: { body: string; rawData: string; type: "text" }

Contains only the plain text-based content. Represents the twilio/text content type.

Type declaration

  • Readonly body: string

    The text of the message you want to send.

  • Readonly rawData: string

    Full data as a stringified JSON. This could be used for future content types and fields which are not yet supported by the newest version of the Conversations SDK, or for using newer types in the older versions of the SDK.

  • Readonly type: "text"

    The type discriminant.

ConversationStatus

ConversationStatus: "notParticipating" | "joined"

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" | "bindings"

Reason for the updated event emission 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.

EmailRecipientLevel

EmailRecipientLevel: "to" | "from" | "cc"

Email recipient level.

JSONArray

JSONArray: JSONValue[]

Represents a JSON array.

JSONObject

JSONObject: {}

Represents a JSON object.

Type declaration

JSONValue

JSONValue: null | string | number | boolean | JSONObject | JSONArray

Represents a JSON value.

MediaCategory

MediaCategory: McsMediaCategory

Category of media. Possible values are as follows:

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

MessageType

MessageType: "text" | "media"

Type of message.

MessageUpdateReason

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

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

NotificationLevel

NotificationLevel: "default" | "muted"

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'

ParticipantEmailLevel

ParticipantEmailLevel: "to" | "cc"

Email participation level. to = to/from cc = cc

ParticipantType

ParticipantType: "chat" | "sms" | "whatsapp" | "email" | string

Participant type. The string variant can be used to denote new types of participant that aren't supported by this version of the SDK.

ParticipantUpdateReason

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

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

RecipientDescriptor

RecipientDescriptor: EmailRecipientDescriptor | UnknownRecipientDescriptor

Message recipient descriptor.

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.