Skip to contentSkip to navigationSkip to topbar
On this page

Voice SDK Call Message Events



Voice SDK Call Message Events Feature Overview

voice-sdk-call-message-events-feature-overview page anchor

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

Requirements

requirements page anchor

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

Client-Side SDKMinimum Version Required
Voice JavaScript SDKv2.2.0
Voice iOS SDKv6.5.0
Voice Android SDKv6.4.0
Voice React Native SDKv1.0.0
Helper LibraryMinimum Version Required
Node.jsv3.83.1
Javav9.1.1
C#v5.81.1
Pythonv7.15.1
PHPv6.43.1
Gov1.1.1
Twilio CLIv5.2.2

A note on "active" Calls

a-note-on-active-calls page anchor

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.

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

send-messages-from-server-receive-messages-in-the-sdk page anchor

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

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

Required setup for server to SDK messaging

required-setup-for-server-to-sdk-messaging page anchor

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

prepare-your-server-side-application-to-send-messages-to-the-sdk page anchor

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

prepare-your-client-side-application-to-receive-messages page anchor

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
1
call.on("messageReceived", (message) => {
2
console.log(JSON.stringify(message.content));
3
//the voiceEventSid can be used for tracking the message
4
console.log('voiceEventSid: ', message.voiceEventSid);
5
})

Send a message from the server to the SDK

send-a-message-from-the-server-to-the-sdk page anchor

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 SDKLink to code sample: Send a message to the SDK
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createUserDefinedMessage() {
11
const userDefinedMessage = await client
12
.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.userDefinedMessages.create({
14
content: JSON.stringify({ key1: "Hello from the server side." }),
15
});
16
17
console.log(userDefinedMessage.accountSid);
18
}
19
20
createUserDefinedMessage();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"sid": "KXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"date_created": "Wed, 18 Dec 2019 20:02:01 +0000"
6
}
(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

receive-messages-in-the-sdk page anchor

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

send-messages-from-the-sdk-to-the-server-side page anchor

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:

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

Required setup for SDK to server messaging

required-setup-for-sdk-to-server-messaging page anchor

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

prepare-your-server-side-application-to-receive-messages-from-the-sdk page anchor
  • 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

prepare-your-client-side-application-to-send-messages page anchor

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
1
// Errors related to Call Message Events are emitted by the Device instance.
2
device.on("error", function (twilioError) {
3
console.error(twilioError);
4
});
5
6
// a Call is active
7
8
// add listener for 'messageSent' event
9
call.on("messageSent", () => {
10
console.log("Message sent.")
11
});
12
13
// create the Call Message
14
const callMessage = {
15
content: { key1: 'This is a messsage from the parent call' },
16
messageType: 'user-defined-message',
17
contentType: "application/json"
18
}
19
20
// send the message
21
// the voiceEventSid can be used for tracking the message
22
sendMessageButton.onclick = () => {
23
console.log('Sending message.')
24
const voiceEventSid = call.sendMessage(callMessage)
25
}

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.

Subscribe to an active Call's messages

subscribe-to-an-active-calls-messages page anchor

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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createUserDefinedMessageSubscription() {
11
const userDefinedMessageSubscription = await client
12
.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.userDefinedMessageSubscriptions.create({
14
callback:
15
"https://www.example.com/your-endpoint-that-can-receive-messages",
16
method: "POST",
17
});
18
19
console.log(userDefinedMessageSubscription.accountSid);
20
}
21
22
createUserDefinedMessageSubscription();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"sid": "ZYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
6
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions/ZYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
7
}
(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

send-a-message-from-the-sdk page anchor

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

Receive the message on the server side

receive-the-message-on-the-server-side page anchor

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.

1
{
2
ContentType: 'application/json',
3
Content: '{"key1":"This is a messsage from the SDK"}',
4
SequenceNumber: '1',
5
CallSid: 'CA0aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
6
Timestamp: 'Fri, 2 Dec 2022 22:02:49 +0000',
7
AccountSid: 'ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
8
Sid: 'KXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
9
}
ParameterDescription
ContentTypeThe Content-Type of the request. (Currently, Twilio only supports application/json.)
ContentThe message sent from the SDK as a JSON string.
SequenceNumberThe order in which the messages were sent, starting from 0.
CallSidThe SID of the Call Resource this message is associated with
TimestampThe timestamp when Twilio sent this message, given as UTC in RFC 2822 format.
AccountSidThe Twilio Account SID associated with the message.
SidA unique identifier for this message. This can be used for internal logging/tracking.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.