---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/voice/api/userdefinedmessage-resource#article
headline: UserDefinedMessages subresource
description: Reference guide for the Twilio UserDefinedMessages resource. View properties and API parameters to send user-defined messages to Voice SDK end users.
url: https://www.twilio.com/docs/voice/api/userdefinedmessage-resource
inLanguage: en
dateModified: 2026-06-22T10:15:32.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# UserDefinedMessages subresource

On this reference page, you'll learn about the properties, parameters, and methods for the UserDefinedMessages subresource. See [Related how-to documentation](#related-how-to-documentation) to learn the steps to use the info on this page.

> \[!NOTE]
>
> See the [Voice SDK Call Message Events page](/docs/voice/sdks/call-message-events) for more information.

UserDefinedMessages is a subresource of [Calls](/docs/voice/api/call-resource) and represents a user-defined message that is sent to a Voice SDK end user during an active call.

A UserDefinedMessage subresource can only be created during an active call associated with the Voice SDK.

Read more about the Voice SDK messaging feature on the [Voice SDK Call Message Events Page](/docs/voice/sdks/call-message-events).

## UserDefinedMessages properties

<OperationTable type="properties" data={{"type":"object","refName":"api.v2010.account.call.user_defined_message","modelName":"api_v2010_account_call_user_defined_message","properties":{"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created User Defined Message."},"call_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^CA[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Call](https://www.twilio.com/docs/voice/api/call-resource) the User Defined Message is associated with."},"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^KX[0-9a-fA-F]{32}$","nullable":true,"description":"The SID that uniquely identifies this User Defined Message."},"date_created":{"type":"string","format":"date-time-rfc-2822","nullable":true,"description":"The date that this User Defined Message was created, given in RFC 2822 format."}}}} />

## Create a UserDefinedMessage

`POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/UserDefinedMessages.json`

### Path parameters

```json
[{"name":"AccountSid","in":"path","description":"The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created User Defined Message.","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](https://www.twilio.com/docs/voice/api/call-resource) the User Defined Message is associated with.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^CA[0-9a-fA-F]{32}$"},"required":true}]
```

### Request body parameters

```json
{"schema":{"type":"object","title":"CreateUserDefinedMessageRequest","required":["Content"],"properties":{"Content":{"type":"string","description":"The User Defined Message in the form of URL-encoded JSON string."},"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."}}},"examples":{"create":{"value":{"lang":"json","value":"{\n  \"Content\": \"{\\\"key\\\":\\\"value\\\"}\",\n  \"IdempotencyKey\": \"1\"\n}","meta":"","code":"{\n  \"Content\": \"{\\\"key\\\":\\\"value\\\"}\",\n  \"IdempotencyKey\": \"1\"\n}","tokens":[["{","#C9D1D9"],"\n  ",["\"Content\"","#7EE787"],[":","#C9D1D9"]," ",["\"{","#A5D6FF"],["\\\"","#79C0FF"],["key","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["value","#A5D6FF"],["\\\"","#79C0FF"],["}\"","#A5D6FF"],[",","#C9D1D9"],"\n  ",["\"IdempotencyKey\"","#7EE787"],[":","#C9D1D9"]," ",["\"1\"","#A5D6FF"],"\n",["}","#C9D1D9"]],"annotations":[],"themeName":"github-dark","style":{"color":"#c9d1d9","background":"#0d1117","colorScheme":"dark"}}}},"encodingType":"application/x-www-form-urlencoded","conditionalParameterMap":{}}
```

Send a message from the server side to the Voice SDK by making a `POST` request to an active Call's UserDefinedMessages endpoint.

The content of your message is contained in the `Content` parameter of your request as a stringified JSON object.

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.

Send a UserDefinedMessage to an SDK end-user

```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 at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createUserDefinedMessage() {
  const userDefinedMessage = await client
    .calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    .userDefinedMessages.create({
      content: JSON.stringify({ example_key: "Hello from the server side!" }),
    });

  console.log(userDefinedMessage.accountSid);
}

createUserDefinedMessage();
```

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

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

user_defined_message = client.calls(
    "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
).user_defined_messages.create(
    content=json.dumps({"example_key": "Hello from the server side!"})
)

print(user_defined_message.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;
using System.Collections.Generic;
using Newtonsoft.Json;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var userDefinedMessage = await UserDefinedMessageResource.CreateAsync(
            content: JsonConvert.SerializeObject(
                new Dictionary<string, Object>() {
                    { "example_key", "Hello from the server side!" }
                },
                Formatting.Indented),
            pathCallSid: "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");

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

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

import java.util.HashMap;
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.call.UserDefinedMessage;
import org.json.JSONObject;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);
        UserDefinedMessage userDefinedMessage =
            UserDefinedMessage
                .creator("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", new JSONObject(new HashMap<String, Object>() {
                    {
                        put("example_key", "Hello from the server side!");
                    }
                }).toString())
                .create();

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

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

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

func main() {
	// Find your Account SID at twilio.com/console
	// Provision API Keys at twilio.com/console/runtime/api-keys
	// and set the environment variables. See http://twil.io/secure
	// For local testing, you can use your Account SID and Auth token
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	apiKey := os.Getenv("TWILIO_API_KEY")
	apiSecret := os.Getenv("TWILIO_API_SECRET")
	client := twilio.NewRestClientWithParams(twilio.ClientParams{
		Username:   apiKey,
		Password:   apiSecret,
		AccountSid: accountSid,
	})

	Content, ContentError := json.Marshal(map[string]interface{}{
		"example_key": "Hello from the server side!",
	})

	if ContentError != nil {
		fmt.Println(ContentError)
		os.Exit(1)
	}

	params := &api.CreateUserDefinedMessageParams{}
	params.SetContent(string(Content))

	resp, err := client.Api.CreateUserDefinedMessage("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 at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
$apiKey = $_ENV["TWILIO_API_KEY"];
$apiSecret = $_ENV["TWILIO_API_SECRET"];
$sid = $_ENV["TWILIO_ACCOUNT_SID"];
$twilio = new Client($apiKey, $apiSecret, $sid);

$user_defined_message = $twilio
    ->calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    ->userDefinedMessages->create(
        json_encode([
            "example_key" => "Hello from the server side!",
        ]), // Content
    );

print $user_defined_message->accountSid;
```

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

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

user_defined_message = @client
                       .api
                       .v2010
                       .calls('CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')
                       .user_defined_messages
                       .create(
                         content: {
                             'example_key' => 'Hello from the server side!'
                           }.to_json
                       )

puts user_defined_message.account_sid
```

```bash
EXCLAMATION_MARK='!'
# Install the twilio-cli from https://twil.io/cli

twilio api:core:calls:user-defined-messages:create \
   --call-sid CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
   --content "{\"example_key\":\"Hello from the server side$EXCLAMATION_MARK\"}"
```

```bash
EXCLAMATION_MARK='!'

CONTENT_OBJ=$(cat << EOF
{
  "example_key": "Hello from the server side$EXCLAMATION_MARK"
}
EOF
)
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json" \
--data-urlencode "Content=$CONTENT_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

```json
{
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sid": "KXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "Wed, 18 Dec 2019 20:02:01 +0000"
}
```

## Related how-to documentation

Find how-to documentation for the topics on this page.

* [How to Send and Receive User-Defined Messages with the Voice SDK](/docs/voice/sdks/call-message-events)
* [Make Twilio API requests](/docs/usage/requests-to-twilio)
  * To learn more about this API, see the [Programmable Voice API overview](/docs/voice/api)
