# UserDefinedMessageSubscription Resource

> \[!NOTE]
>
> This feature is in Public Beta.
>
> See the [Voice SDK Call Message Events page](/docs/voice/sdks/call-message-events) 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](/docs/voice/sdks/call-message-events).

## UserDefinedMessageSubscription Properties

```json
{"type":"object","refName":"api.v2010.account.call.user_defined_message_subscription","modelName":"api_v2010_account_call_user_defined_message_subscription","properties":{"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](/docs/iam/api/account) that subscribed to the User Defined Messages."},"call_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^CA[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Call](/docs/voice/api/call-resource) the User Defined Message Subscription is associated with. This refers to the Call SID that is producing the User Defined Messages."},"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^ZY[0-9a-fA-F]{32}$","nullable":true,"description":"The SID that uniquely identifies this User Defined Message Subscription."},"date_created":{"type":"string","format":"date-time-rfc-2822","nullable":true,"description":"The date that this User Defined Message Subscription was created, given in RFC 2822 format."},"uri":{"type":"string","nullable":true,"description":"The URI of the User Defined Message Subscription Resource, relative to `https://api.twilio.com`."}}}
```

## Create a UserDefinedMessageSubscription Resource

`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](/docs/voice/sdks#call-legs-with-voice-sdk-calls) for more information on Voice SDK Call legs.

### Path parameters

```json
[{"name":"AccountSid","in":"path","description":"The SID of the [Account](/docs/iam/api/account) that subscribed to the User Defined Messages.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$"},"required":true},{"name":"CallSid","in":"path","description":"The SID of the [Call](/docs/voice/api/call-resource) the User Defined Messages subscription is associated with. This refers to the Call SID that is producing the user defined messages.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^CA[0-9a-fA-F]{32}$"},"required":true}]
```

### Request body parameters

```json
{"schema":{"type":"object","title":"CreateUserDefinedMessageSubscriptionRequest","required":["Callback"],"properties":{"Callback":{"type":"string","format":"uri","description":"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)."},"IdempotencyKey":{"type":"string","description":"A unique string value to identify API call. This should be a unique string value per API call and can be a randomly generated."},"Method":{"type":"string","format":"http-method","enum":["GET","POST"],"description":"The HTTP method Twilio will use when requesting the above `Url`. Either `GET` or `POST`. Default is `POST`."}}},"examples":{"create":{"value":{"lang":"json","value":"{\n  \"Callback\": \"http://www.example.com\",\n  \"Method\": \"POST\",\n  \"IdempotencyKey\": \"1\"\n}","meta":"","code":"{\n  \"Callback\": \"http://www.example.com\",\n  \"Method\": \"POST\",\n  \"IdempotencyKey\": \"1\"\n}","tokens":[["{","#C9D1D9"],"\n  ",["\"Callback\"","#7EE787"],[":","#C9D1D9"]," ",["\"http://www.example.com\"","#A5D6FF"],[",","#C9D1D9"],"\n  ",["\"Method\"","#7EE787"],[":","#C9D1D9"]," ",["\"POST\"","#A5D6FF"],[",","#C9D1D9"],"\n  ",["\"IdempotencyKey\"","#7EE787"],[":","#C9D1D9"]," ",["\"1\"","#A5D6FF"],"\n",["}","#C9D1D9"]],"annotations":[],"themeName":"github-dark","style":{"color":"#c9d1d9","background":"#0d1117"}}}},"encodingType":"application/x-www-form-urlencoded","conditionalParameterMap":{}}
```

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

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

async function createUserDefinedMessageSubscription() {
  const userDefinedMessageSubscription = await client
    .calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    .userDefinedMessageSubscriptions.create({
      callback:
        "https://www.example.com/your-endpoint-that-can-receive-messages",
    });

  console.log(userDefinedMessageSubscription.accountSid);
}

createUserDefinedMessageSubscription();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client

# Find your Account SID and Auth Token at twilio.com/console
# and set the environment variables. See http://twil.io/secure
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
client = Client(account_sid, auth_token)

user_defined_message_subscription = client.calls(
    "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
).user_defined_message_subscriptions.create(
    callback="https://www.example.com/your-endpoint-that-can-receive-messages"
)

print(user_defined_message_subscription.account_sid)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Api.V2010.Account.Call;
using System.Threading.Tasks;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID and Auth Token at twilio.com/console
        // and set the environment variables. See http://twil.io/secure
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
        string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");

        TwilioClient.Init(accountSid, authToken);

        var userDefinedMessageSubscription =
            await UserDefinedMessageSubscriptionResource.CreateAsync(
                callback: new Uri(
                    "https://www.example.com/your-endpoint-that-can-receive-messages"),
                pathCallSid: "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");

        Console.WriteLine(userDefinedMessageSubscription.AccountSid);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.net.URI;
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.call.UserDefinedMessageSubscription;

public class Example {
    // Find your Account SID and Auth Token at twilio.com/console
    // and set the environment variables. See http://twil.io/secure
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
    public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");

    public static void main(String[] args) {
        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
        UserDefinedMessageSubscription userDefinedMessageSubscription =
            UserDefinedMessageSubscription
                .creator("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                    URI.create("https://www.example.com/your-endpoint-that-can-receive-messages"))
                .create();

        System.out.println(userDefinedMessageSubscription.getAccountSid());
    }
}
```

```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	api "github.com/twilio/twilio-go/rest/api/v2010"
	"os"
)

func main() {
	// Find your Account SID and Auth Token at twilio.com/console
	// and set the environment variables. See http://twil.io/secure
	// Make sure TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN exists in your environment
	client := twilio.NewRestClient()

	params := &api.CreateUserDefinedMessageSubscriptionParams{}
	params.SetCallback("https://www.example.com/your-endpoint-that-can-receive-messages")

	resp, err := client.Api.CreateUserDefinedMessageSubscription("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
		params)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		if resp.AccountSid != nil {
			fmt.Println(*resp.AccountSid)
		} else {
			fmt.Println(resp.AccountSid)
		}
	}
}
```

```php
<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once "/path/to/vendor/autoload.php";

use Twilio\Rest\Client;

// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
$sid = getenv("TWILIO_ACCOUNT_SID");
$token = getenv("TWILIO_AUTH_TOKEN");
$twilio = new Client($sid, $token);

$user_defined_message_subscription = $twilio
    ->calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    ->userDefinedMessageSubscriptions->create(
        "https://www.example.com/your-endpoint-that-can-receive-messages" // Callback
    );

print $user_defined_message_subscription->accountSid;
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'rubygems'
require 'twilio-ruby'

# Find your Account SID and Auth Token at twilio.com/console
# and set the environment variables. See http://twil.io/secure
account_sid = ENV['TWILIO_ACCOUNT_SID']
auth_token = ENV['TWILIO_AUTH_TOKEN']
@client = Twilio::REST::Client.new(account_sid, auth_token)

user_defined_message_subscription = @client
                                    .api
                                    .v2010
                                    .calls('CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')
                                    .user_defined_message_subscriptions
                                    .create(
                                      callback: 'https://www.example.com/your-endpoint-that-can-receive-messages'
                                    )

puts user_defined_message_subscription.account_sid
```

```bash
# Install the twilio-cli from https://twil.io/cli

twilio api:core:calls:user-defined-message-subscriptions:create \
   --call-sid CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
   --callback https://www.example.com/your-endpoint-that-can-receive-messages
```

```bash
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json" \
--data-urlencode "Callback=https://www.example.com/your-endpoint-that-can-receive-messages" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

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

## Related resources

Go to the [Voice SDK Call Message Events page](/docs/voice/sdks/call-message-events) to learn more.
