Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Rate this page:
On this page

UserDefinedMessageSubscription Resource

(information)

Info

This feature is in Public Beta.

See the Voice SDK Call Message Events page for more information.

A UserDefinedMessageSubscription Resource is a Call subresource that represents a subscription to user-defined messages sent from the Voice SDK. You must create a UserDefinedMessageSubscription Resource in order to receive messages from the Voice SDK.

A UserDefinedMessageSubscription Resource can only be created during an active Call associated with the Voice SDK.

Your Voice SDK application must be configured to send messages. Read more about sending and receiving Voice SDK messages on the Voice SDK Call Message Events page.

UserDefinedMessageSubscription Properties

userdefinedmessagesubscription-properties page anchor
Property nameTypePIIDescription
account_sidSID<AC>
Not PII

The SID of the Account that subscribed to the User Defined Messages.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
call_sidSID<CA>
Not PII

The SID of the Call the User Defined Message Subscription is associated with. This refers to the Call SID that is producing the User Defined Messages.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34
sidSID<ZY>
Not PII

The SID that uniquely identifies this User Defined Message Subscription.

Pattern: ^ZY[0-9a-fA-F]{32}$Min length: 34Max length: 34
date_createdstring<date-time-rfc-2822>
Not PII

The date that this User Defined Message Subscription was created, given in RFC 2822 format.

uristring
Not PII

The URI of the User Defined Message Subscription Resource, relative to https://api.twilio.com.

Create a UserDefinedMessageSubscription Resource

create-a-userdefinedmessagesubscription-resource page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/UserDefinedMessageSubscriptions.json

You need to subscribe to a Call's user-defined messages in order to receive messages from the Voice SDK. You do this by creating a UserDefinedMessageSubscription Resource for that Call SID.

You must have an endpoint that can handle POST or GET requests with a Content-Type of application/json. You specify this endpoint in the Callback parameter when creating your UserDefinedMessageSubscription, and this is where Twilio will send requests containing the messages from the Voice SDK.

Use the appropriate Call SID in the path of your POST request. Use the parent Call SID if you wish to send a message to parent Call leg. Use the child Call SID if you wish to send a message to the child Call leg.

See the Voice SDK Overview page for more information on Voice SDK Call legs.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required
Not PII

The SID of the Account that subscribed to the User Defined Messages.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
CallSidSID<CA>required
Not PII

The SID of the Call the User Defined Messages subscription is associated with. This refers to the Call SID that is producing the user defined messages.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters page anchor
Property nameTypeRequiredPIIDescription
Callbackstring<uri>required
Not PII

The URL we should call using the method to send user defined events to your application. URLs must contain a valid hostname (underscores are not permitted).

IdempotencyKeystringOptional
Not PII

A unique string value to identify API call. This should be a unique string value per API call and can be a randomly generated.

Methodenum<http-method>Optional
Not PII

The HTTP method Twilio will use when requesting the above Url. Either GET or POST. Default is POST.

Possible values:
GETPOST

Set up a subscription to receive user-defined messages from the Voice SDK

set-up-a-subscription-to-receive-user-defined-messages-from-the-voice-sdk page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

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
}

Rate this page: