The Call Message Events feature is in Public Beta.
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 JavaScript, iOS, Android, and React Native SDKs provide the following functionality for the client-side implementation of Call Message Events:
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 |
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.
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.
The general flow of sending a message from the server side to the SDK is as follows:
POST
request to the Call's
UserDefinedMessages endpoint
. This request contains the message to be sent.
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.
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.
_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})
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.
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.
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.
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:
POST
request to the Call's
UserDefinedMessageSubscriptions endpoint
.
call.sendMessage()
method is invoked in the SDK.
Callback
parameter when subscribing to a Call's messages.
statusCallback
and
statusCallbackEvent
attributes in your
<Client>
and
<Number>
TwiML, in conjunction with an endpoint that handles status callback requests from Twilio.
Add logic to your client-side application that:
call.sendMessage()
method during an active call
Select your Voice SDK language/platform below to see an example of sending a message from the SDK to the server side.
_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}
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.
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.
Once a subscription has been set up, the SDK can now invoke the call.sendMessage() event.
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. |