Create a pronunciation dictionary

Create a new pronunciation dictionary for the authenticated organization. Each dictionary contains a list of items that control how specific words are spoken. Items can be alias type (text replacement) or phoneme type (IPA pronunciation notation).

As an alternative to providing items directly as JSON, you can upload a dictionary file (PLS/XML or plain text format, max 1MB) using multipart/form-data. PLS files use the standard W3C Pronunciation Lexicon Specification XML format. Text files use a line-based format: word=alias for aliases, word:/phoneme/ for IPA phonemes.

Limits:

Maximum 50 dictionaries per organization
Maximum 100 items per dictionary
Text: max 200 characters
Alias/phoneme value: max 500 characters
File upload: max 1MB (1,048,576 bytes)

POST

pronunciation_dicts

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const pronunciationDict = await client.pronunciationDicts.create({
  items: [
    {
      alias: 'tel-nicks',
      text: 'Telnyx',
      type: 'alias',
    },
  ],
  name: 'Brand Names',
});

console.log(pronunciationDict.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
pronunciation_dict = client.pronunciation_dicts.create(
    items=[{
        "alias": "tel-nicks",
        "text": "Telnyx",
        "type": "alias",
    }],
    name="Brand Names",
)
print(pronunciation_dict.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	pronunciationDict, err := client.PronunciationDicts.New(context.TODO(), telnyx.PronunciationDictNewParams{
		Items: []telnyx.PronunciationDictNewParamsItemUnion{{
			OfAlias: &telnyx.PronunciationDictAliasItemParam{
				Alias: "tel-nicks",
				Text:  "Telnyx",
				Type:  telnyx.PronunciationDictAliasItemTypeAlias,
			},
		}},
		Name: "Brand Names",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", pronunciationDict.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictAliasItem;
import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictCreateParams;
import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        PronunciationDictCreateParams params = PronunciationDictCreateParams.builder()
            .addItem(PronunciationDictAliasItem.builder()
                .alias("tel-nicks")
                .text("Telnyx")
                .type(PronunciationDictAliasItem.Type.ALIAS)
                .build())
            .name("Brand Names")
            .build();
        PronunciationDictCreateResponse pronunciationDict = client.pronunciationDicts().create(params);
    }
}

require "telnyx"

telnyx = Telnyx::Client.new(api_key: "My API Key")

pronunciation_dict = telnyx.pronunciation_dicts.create(
  items: [{alias: "tel-nicks", text: "Telnyx", type: :alias}],
  name: "Brand Names"
)

puts(pronunciation_dict)

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $pronunciationDict = $client->pronunciationDicts->create(
    items: [['alias' => 'tel-nicks', 'text' => 'Telnyx', 'type' => 'alias']],
    name: 'Brand Names',
  );

  var_dump($pronunciationDict);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/pronunciation_dicts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Brand Names",
  "items": [
    {
      "text": "Telnyx",
      "type": "alias",
      "alias": "tel-nicks"
    }
  ]
}
'

{
  "data": {
    "record_type": "pronunciation_dict",
    "id": "c215a3e1-be41-4701-97e8-1d3c22f9a5b7",
    "name": "Brand Names",
    "items": [
      {
        "text": "Telnyx",
        "type": "alias",
        "alias": "tel-nicks"
      }
    ],
    "version": 1,
    "created_at": "2026-03-25T12:00:00.000Z",
    "updated_at": "2026-03-25T12:00:00.000Z"
  }
}

Authorizations

Authorization

string

header

required

Telnyx API v2 key. Obtain from https://portal.telnyx.com

Body

Request body for creating a pronunciation dictionary.

name

string

required

Human-readable name. Must be unique within the organization.

Required string length: 1 - 255

Example:

"Brand Names"

items

object[]

required

List of pronunciation items (alias or phoneme type). At least one item is required.

Required array length: 1 - 100 elements

A single pronunciation dictionary item. Use type 'alias' to replace matched text with a spoken alias, or type 'phoneme' to specify exact pronunciation using IPA notation.

Option 1
Option 2

Show child attributes

Response

Pronunciation dictionary created successfully.

Response containing a single pronunciation dictionary.

data

object

A pronunciation dictionary record.

Show child attributes

⌘I

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const pronunciationDict = await client.pronunciationDicts.create({
  items: [
    {
      alias: 'tel-nicks',
      text: 'Telnyx',
      type: 'alias',
    },
  ],
  name: 'Brand Names',
});

console.log(pronunciationDict.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
pronunciation_dict = client.pronunciation_dicts.create(
    items=[{
        "alias": "tel-nicks",
        "text": "Telnyx",
        "type": "alias",
    }],
    name="Brand Names",
)
print(pronunciation_dict.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	pronunciationDict, err := client.PronunciationDicts.New(context.TODO(), telnyx.PronunciationDictNewParams{
		Items: []telnyx.PronunciationDictNewParamsItemUnion{{
			OfAlias: &telnyx.PronunciationDictAliasItemParam{
				Alias: "tel-nicks",
				Text:  "Telnyx",
				Type:  telnyx.PronunciationDictAliasItemTypeAlias,
			},
		}},
		Name: "Brand Names",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", pronunciationDict.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictAliasItem;
import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictCreateParams;
import com.telnyx.sdk.models.pronunciationdicts.PronunciationDictCreateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        PronunciationDictCreateParams params = PronunciationDictCreateParams.builder()
            .addItem(PronunciationDictAliasItem.builder()
                .alias("tel-nicks")
                .text("Telnyx")
                .type(PronunciationDictAliasItem.Type.ALIAS)
                .build())
            .name("Brand Names")
            .build();
        PronunciationDictCreateResponse pronunciationDict = client.pronunciationDicts().create(params);
    }
}

require "telnyx"

telnyx = Telnyx::Client.new(api_key: "My API Key")

pronunciation_dict = telnyx.pronunciation_dicts.create(
  items: [{alias: "tel-nicks", text: "Telnyx", type: :alias}],
  name: "Brand Names"
)

puts(pronunciation_dict)

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $pronunciationDict = $client->pronunciationDicts->create(
    items: [['alias' => 'tel-nicks', 'text' => 'Telnyx', 'type' => 'alias']],
    name: 'Brand Names',
  );

  var_dump($pronunciationDict);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/pronunciation_dicts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Brand Names",
  "items": [
    {
      "text": "Telnyx",
      "type": "alias",
      "alias": "tel-nicks"
    }
  ]
}
'

{
  "data": {
    "record_type": "pronunciation_dict",
    "id": "c215a3e1-be41-4701-97e8-1d3c22f9a5b7",
    "name": "Brand Names",
    "items": [
      {
        "text": "Telnyx",
        "type": "alias",
        "alias": "tel-nicks"
      }
    ],
    "version": 1,
    "created_at": "2026-03-25T12:00:00.000Z",
    "updated_at": "2026-03-25T12:00:00.000Z"
  }
}

WebSocket Streaming

REST API

Providers

Other

API Reference

For AI Agents

Create a pronunciation dictionary

Authorizations

Body

Response