Menu

Expand
Rate this page:

Voice SDK Call Message Events

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 JavaScript and iOS SDKs provide the following functionality for the client-side implementation of Call Message Events:

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
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.

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

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.

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

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

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

Server side

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

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:

  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

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.

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

    func callDidReceiveMessage(call: Call, message callMessage: CallMessage) {
        NSLog("Call message received. Message: \(callMessage.content)")
    }
    
}

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

        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:

        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

        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.

        // Errors related to Call Message Events are emitted by the Device instance. 
        device.on("error", function (twilioError) {
          console.error(twilioError);
        });
        
        // a Call is active
        
        // add listener for 'messageSent' event
        call.on("messageSent", () => {
          console.log("Message sent.")
        });
        
        // create the Call Message
        const callMessage = { 
          content: { key1: 'This is a messsage from the parent call' },
          messageType: 'user-defined-message', 
          contentType: "application/json"
        }
        
        // send the message
        // the voiceEventSid can be used for tracking the message
        sendMessageButton.onclick = () => {
          console.log('Sending message.')
          const voiceEventSid = call.sendMessage(callMessage)
        }
        let call = TwilioVoiceSDK.connect(options: connectOptions, delegate: self)
            
        // Wait for a call to be connected
        
        // Construct the message object
        let message = "{ \"key1\": \"This is a message from the SDK\"}"
        let callMessage = CallMessage(content: message)
            
        // Send the message
        // voiceEventSid can be used for tracking the message
        let voiceEventSid = call.sendMessage(callMessage)
        
        // Handle success/failure
        extension ViewController: CallMessageDelegate {
            func callDidSendMessage(call: Call, voiceEventSid: String) {
                NSLog("Call message sent. Voice Event SID: \(voiceEventSid)")
            }
            
            func callDidFailToSendMessage(call: Call, voiceEventSid: String, error: Error) {
                NSLog("Failed to send call message. Voice Event SID: \(voiceEventSid). Error: \(error.localizedDescription)")
            }        
        }

        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

        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.

              
              
              

              Subscribe to a Call's Messages

              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.

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

              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.
              Rate this page:

              Need some help?

              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

              Thank you for your feedback!

              Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

              Sending your feedback...
              🎉 Thank you for your feedback!
              Something went wrong. Please try again.

              Thanks for your feedback!

              thanks-feedback-gif