On this page

Voice SDK Call Message Events

(information)

Info

The Call Message Events feature is in Public Beta.

Voice SDK Call Message Events Feature Overview

The Call Message Events feature allows your client-side and server-side applications to communicate via custom ("user-defined") messages during a Voice SDK call. The feature leverages the existing signaling connection, so you don't need to set up your own communication channel between your client-side and server-side applications.

Two Twilio REST API Resources are used for server-side implementation:

The UserDefinedMessage Resource , which allows your server-side application to send messages to the Voice SDK end user during an active Call
The UserDefinedMessageSubscription Resource , which allows your server-side application to subscribe to messages sent from the Voice SDK for an active Call

The JavaScript, iOS, Android, and React Native SDKs provide the following functionality for the client-side implementation of Call Message Events:

JavaScript SDKiOS SDKAndroid SDKReact Native SDK

Method

call.sendMessage()

Events

Call messageSent event

Call messageReceived event

Classes

TVOCallMessage

TVOCallMessageBuilder

Method

[TVOCall sendMessage:]

Callbacks

[TVOCallMessageDelegate call:didReceiveMessage:]

[TVOCallMessageDelegate call:didSendMessage:]

[TVOCallMessageDelegate call:didFailToSendMessage:]

See the iOS SDK API Reference documentation for more information.

Requirements

In order to implement the Call Message Events feature, you must use supported versions of the Voice SDK and Helper Libraries.

Client-Side SDK	Minimum Version Required
Voice JavaScript SDK	v2.2.0
Voice iOS SDK	v6.5.0
Voice Android SDK	v6.4.0
Voice React Native SDK	v1.0.0

Helper Library	Minimum Version Required
Node.js	v3.83.1
Java	v9.1.1
C#	v5.81.1
Python	v7.15.1
PHP	v6.43.1
Go	v1.1.1
Twilio CLI	v5.2.2

A note on "active" Calls

The Call Message Events feature works only for active Calls.

Client side

From the perspective of the SDK, a Call is active when both the signaling and media connections are established.

Select language/platform below to see how to active Calls are defined in the SDK.

JavaScript SDKiOS SDKAndroid SDKReact Native SDK

The Call is active and ready for sending and receiving messages when the Call instance's status is "open" or "ringing".

The status of the Call is retrieved via the call.status() method.

The Call instance's accept event is emitted when the Call state transitions to open.

The Call instance's ringing event is emitted when the Call state transitions to ringing.

A Call is active and ready for sending and receiving messages when the TVOCallState is TVOCallStateConnected or TVOCallStateRinging.

The Call's state is returned via the TVOCallState property.

The [TVOCallDelegate callDidConnect:] callback is emitted when the Call state transitions to TVOCallStateConnected.

The [TVOCallDelegate callDidStartRinging:] callback is emitted when the Call state transitions to TVOCallStateRinging.

A Call is active and ready for sending and receiving messages when the Call.State is State.CONNECTED or State.RINGING.

The Call's state is returned via the Call.getState() method.

The Call.Listener.onConnected(...) callback is emitted when the Call state transitions to State.CONNECTED.

The Call.Listener.onRinging(...) callback is emitted when the Call state transitions to State.RINGING.

The Call is active and ready for sending and receiving messages when the Call.State is Call.State.Connected or Call.State.Ringing.

The Call's state is returned via the Call.getState() method.

The Call event Call.Event.Connected is emitted when the Call state transitions to Call.State.Connected.

The Call event Call.Event.Ringing is emitted when the Call state transitions to Call.State.Ringing.

Server side

From the server side perspective, an "active" Call is a Call Resource with a CallStatus value of either in-progress or ringing.

The status for a Call Resource can be retrieved from the body of status callback requests or by fetching a Call Resource via API.

Send messages from server, receive messages in the SDK

The general flow of sending a message from the server side to the SDK is as follows:

An SDK end user answers or places a Call and the Call is currently active.
The server-side application makes a POST request to the Call's UserDefinedMessages endpoint . This request contains the message to be sent.
The SDK receives the message.

Required setup for server to SDK messaging

Prepare your server-side application to send messages to the SDK

You must have some way of retrieving the Call SID on your server side. One way to do this is with the statusCallback and statusCallbackEvent attributes in your <Client> and <Number> TwiML, in conjunction with an endpoint that handles status callback requests from Twilio.

Prepare your client-side application to receive messages

Add logic to your client-side application that handles incoming messages.

Select your Voice SDK language/platform below to see an example of receiving messages in the SDK.

JavaScript SDKiOS SDKAndroid SDKReact Native SDK


_10call.on("messageReceived", (message) => {
_10  console.log(JSON.stringify(message.content));
_10  //the voiceEventSid can be used for tracking the message
_10  console.log('voiceEventSid: ', message.voiceEventSid);
_10})


_10extension ViewController: CallMessageDelegate {
_10
_10    func callDidReceiveMessage(call: Call, message callMessage: CallMessage) {
_10        NSLog("Call message received. Message: (callMessage.content)")
_10    }
_10
_10}


_14class MyCallMessageListener implements Call.CallMessageListener {
_14   @Override
_14   public void onMessageReceived(final CallMessage callMesssage) {
_14      Log.d("[debug]", "Call message received. Message: " + callMessage.getContent());
_14   }
_14   @Override
_14   public void onMessageSent(final String voiceEventSID) {
_14      Log.d("[debug]", "Call message sent. Message Id: " + voiceEventSID);
_14   }
_14   @Override
_14   public void onMessageFailure(final String voiceEventSID, final VoiceException error) {
_14      Log.d("[debug]", "Call message failure. Message id: " +voiceEventSID + " error: " + error.getMessage());
_14   }
_14}


_10call.addListener(Call.Event.MessageReceived, (message: CallMessage) => {
_10  console.log(JSON.stringify(message.getContent()))
_10  //the voiceEventSid can be used for tracking the message
_10  console.log('voiceEventSid: ', message.getSid());
_10});

Send a message from the server to the SDK

Once a Call is active, send a message by sending a POST request to the Call's UserDefinedMessages endpoint. The message content is passed in the Content parameter as a JSON string.

Send a message to the SDK

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20
_20async function createUserDefinedMessage() {
_20  const userDefinedMessage = await client
_20    .calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_20    .userDefinedMessages.create({
_20      content: JSON.stringify({ key1: "Hello from the server side." }),
_20    });
_20
_20  console.log(userDefinedMessage.accountSid);
_20}
_20
_20createUserDefinedMessage();

Output


_10{
_10  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10  "sid": "KXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10  "date_created": "Wed, 18 Dec 2019 20:02:01 +0000"
_10}

(information)

Info

Be sure you're using the correct Call SID when creating a subscription.

If the SDK end user (the recipient of the message) made an outgoing call, you must subscribe to the parent Call SID.

If the SDK end user (the recipient of the message) accepted an incoming call, you must subscribe to the child Call SID.

Learn more about Call legs and the SDKs on the Voice SDK Overview page.

Receive messages in the SDK

Provided that the message was sent successfully from the server side, the SDK will receive the message. See the code samples above for SDK-specific handling of incoming messages.

Send messages from the SDK to the server side

In order to receive messages on your server from the SDK, you need to set up a subscription to the Call's messages. In the subscription, you specify where Twilio should send the messages. Once a subscription is created, the SDK end-user can send messages that Twilio will then send in an HTTP request to your server-side application.

The general flow of sending a message from the SDK to the server side is as follows:

An SDK end user answers or places a Call and the Call is currently active.
The server-side application makes a POST request to the Call's UserDefinedMessageSubscriptions endpoint .
The call.sendMessage() method is invoked in the SDK.
The endpoint specified in the UserDefinedMessageSubscription request receives the message from Twilio.

Required setup for SDK to server messaging

Prepare your server-side application to receive messages from the SDK

Before you can receive any messages from the SDK, you need to set up an HTTP endpoint where Twilio will send messages. Your endpoint must be able to accept application/json. This endpoint's URL is used as the Callback parameter when subscribing to a Call's messages.
You must have some way of retrieving the Call SID on your server side. One way to do this is with the statusCallback and statusCallbackEvent attributes in your <Client> and <Number> TwiML, in conjunction with an endpoint that handles status callback requests from Twilio.

Prepare your client-side application to send messages

Add logic to your client-side application that:

constructs a valid message object
invokes the call.sendMessage() method during an active call
handles the success/failure of a message sending attempt

Select your Voice SDK language/platform below to see an example of sending a message from the SDK to the server side.

JavaScript SDKiOS SDKAndroid SDKReact Native SDK


_25// Errors related to Call Message Events are emitted by the Device instance.
_25device.on("error", function (twilioError) {
_25  console.error(twilioError);
_25});
_25
_25// a Call is active
_25
_25// add listener for 'messageSent' event
_25call.on("messageSent", () => {
_25  console.log("Message sent.")
_25});
_25
_25// create the Call Message
_25const callMessage = { 
_25  content: { key1: 'This is a messsage from the parent call' },
_25  messageType: 'user-defined-message', 
_25  contentType: "application/json"
_25}
_25
_25// send the message
_25// the voiceEventSid can be used for tracking the message
_25sendMessageButton.onclick = () => {
_25  console.log('Sending message.')
_25  const voiceEventSid = call.sendMessage(callMessage)
_25}


_22let call = TwilioVoiceSDK.connect(options: connectOptions, delegate: self)
_22
_22// Wait for a call to be connected
_22
_22// Construct the message object
_22let message = "{ \"key1\": \"This is a message from the SDK\"}"
_22let callMessage = CallMessage(content: message)
_22
_22// Send the message
_22// voiceEventSid can be used for tracking the message
_22let voiceEventSid = call.sendMessage(callMessage)
_22
_22// Handle success/failure
_22extension ViewController: CallMessageDelegate {
_22    func callDidSendMessage(call: Call, voiceEventSid: String) {
_22        NSLog("Call message sent. Voice Event SID: (voiceEventSid)")
_22    }
_22
_22    func callDidFailToSendMessage(call: Call, voiceEventSid: String, error: Error) {
_22        NSLog("Failed to send call message. Voice Event SID: (voiceEventSid). Error: (error.localizedDescription)")
_22    }
_22}


_31ConnectOptions cxnOptions = new ConnectOptions.Builder(accessToken)
_31  .callMessageListener(new Call.CallMessageListener() {
_31    @Override
_31    public void onMessageReceived(final CallMessage callMesssage) {
_31      Log.d("[debug]", "Call message received. Message: " + callMessage.getContent());
_31    }
_31    @Override
_31    public void onMessageSent(final String voiceEventSID) {
_31      Log.d("[debug]", "Call message sent. Message Id: " + voiceEventSID);
_31    }
_31    @Override
_31    public void onMessageFailure(final String voiceEventSID, final VoiceException error) {
_31      Log.d("[debug]", "Call message failure. Message id: " +voiceEventSID + " error: " + error.getMessage());
_31    }
_31  })
_31  .params(params)
_31  .build();
_31Call call = voice.connect(myActivityContext, cxnOptions, myCallListener);
_31
_31// Wait for call to be connected
_31...
_31// Construct call message
_31final CallMessage callMessage = (new CallMessage.Builder(CallMessage.MessageType.UserDefinedMessage))
_31  .contentType("application/json")
_31  .content((new JSONObject())
_31    .put("test_field", "test")
_31    .toString())
_31  .build();
_31...
_31// Send message
_31call.sendMessage(callMessage);


_23// create the Call Message
_23const message = new CallMessage({
_23  // Note: content must match contentType
_23  content: { key1: 'This is a message from the parent call' },
_23  contentType: CallMessage.ContentType.ApplicationJson,
_23  messageType: CallMessage.MessageType.UserDefinedMessage
_23});
_23
_23// send the message 
_23const outgoingCallMessage: OutgoingCallMessage = await call.sendMessage(message);
_23
_23// the voiceEventSid can be used for tracking the message
_23const voiceEventSID = outgoingCallMessage.getSid()
_23
_23// add listener for 'messageFailure' event
_23outgoingCallMessage.addListener(OutgoingCallMessage.Event.Failure, (error) => {
_23  // outgoingCallMessage failed, handle error
_23});
_23
_23// add listener for 'messageSent' event
_23outgoingCallMessage.addListener(OutgoingCallMessage.Event.Sent, () => {
_23    // outgoingCallMessage sent
_23});

You can only send messages during an active Call. If you have any UI elements that your SDK end user interacts with (e.g. a "Send Message" button), make sure that sending messages is only enabled during an active Call.

Once a Call is active, your server-side must set up a subscription to a Call's messages by making a POST request to the Call's UserDefinedMessageSubscription Resource.

The Callback parameter specifies your endpoint that will receive messages from Twilio.

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_22// Download the helper library from https://www.twilio.com/docs/node/install
_22const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_22
_22// Find your Account SID and Auth Token at twilio.com/console
_22// and set the environment variables. See http://twil.io/secure
_22const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22const authToken = process.env.TWILIO_AUTH_TOKEN;
_22const client = twilio(accountSid, authToken);
_22
_22async function createUserDefinedMessageSubscription() {
_22  const userDefinedMessageSubscription = await client
_22    .calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_22    .userDefinedMessageSubscriptions.create({
_22      callback:
_22        "https://www.example.com/your-endpoint-that-can-receive-messages",
_22      method: "POST",
_22    });
_22
_22  console.log(userDefinedMessageSubscription.accountSid);
_22}
_22
_22createUserDefinedMessageSubscription();

Output


_10{
_10  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10  "sid": "ZYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10  "date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
_10  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions/ZYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_10}

(information)

Info

Be sure you're using the correct Call SID when creating a subscription.

If the SDK end user (who is sending messages that you wish to receive) made an outgoing call, you must subscribe to the parent Call SID.

If the SDK end user (who is sending messages that you wish to receive) accepted an incoming call, you must subscribe to the child Call SID.

Learn more about Call legs and the SDKs on the Voice SDK Overview page.

Send a message from the SDK

Once a subscription has been set up, the SDK can now invoke the call.sendMessage() event.

Receive the message on the server side

If a subscription was created and then the SDK sent a message successfully, your Callback endpoint will receive the request from Twilio. The message from the SDK is contained in the Content property of the request.

See an example of the Twilio's request to the Callback endpoint below, followed by a description of the parameters in the request.


_10{
_10  ContentType: 'application/json',
_10  Content: '{"key1":"This is a messsage from the SDK"}',
_10  SequenceNumber: '1',
_10  CallSid: 'CA0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
_10  Timestamp: 'Fri, 2 Dec 2022 22:02:49 +0000',
_10  AccountSid: 'ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
_10  Sid: 'KXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
_10}

Parameter	Description
ContentType	The Content-Type of the request. (Currently, Twilio only supports application/json.)
Content	The message sent from the SDK as a JSON string.
SequenceNumber	The order in which the messages were sent, starting from 0.
CallSid	The SID of the Call Resource this message is associated with
Timestamp	The timestamp when Twilio sent this message, given as UTC in RFC 2822 format.
AccountSid	The Twilio Account SID associated with the message.
Sid	A unique identifier for this message. This can be used for internal logging/tracking.

Voice SDK Call Message Events

Info

Voice SDK Call Message Events Feature Overview

Requirements

A note on "active" Calls

Send messages from server, receive messages in the SDK

Required setup for server to SDK messaging

Prepare your server-side application to send messages to the SDK

Prepare your client-side application to receive messages

Send a message from the server to the SDK

Send a message to the SDK

Info

Receive messages in the SDK

Send messages from the SDK to the server side

Required setup for SDK to server messaging

Prepare your server-side application to receive messages from the SDK

Prepare your client-side application to send messages

Subscribe to an active Call's messages

Subscribe to a Call's Messages

Info

Send a message from the SDK

Receive the message on the server side