Configure a Messaging Profile with the Telnyx CLI

A Telnyx messaging profile holds the webhook URLs, allowed destination countries, and spend limit for the numbers assigned to it. This guide updates an existing profile with telnyx messaging-profiles update and reads the result back with retrieve.

What you will build

A messaging profile named orders-notifications that sends US and Canada traffic only, delivers events to a primary and a failover webhook, and enforces a daily spend limit of 5.00 USD.

telnyx messaging-profiles list      -> find the profile id
telnyx messaging-profiles update    -> set name, webhooks, destinations, spend limit
telnyx messaging-profiles retrieve  -> read the stored values back

AI Prompt

Using the Telnyx CLI, configure an existing messaging profile named "orders-notifications" to allow only US and CA destinations, send webhooks to https://example.com/telnyx/messaging with a failover at https://example.com/telnyx/messaging-backup, and enforce a daily spend limit of 5.00 USD. Then read the profile back and confirm each value.

Requirements:
- Use telnyx CLI 0.32.0 with the TELNYX_API_KEY environment variable.
- `messaging-profiles update` takes the profile id in `--messaging-profile-id`. Repeat `--whitelisted-destination` once per country code.
- `--daily-spend-limit` takes a string such as 5.00 and only takes effect when `--daily-spend-limit-enabled` is set.
- Webhook URLs must use https.
- Use `--transform` to exclude the profile's `v1_secret` field from any output you display.
- Run the verification step below before finishing.

Using the Telnyx CLI, configure an existing messaging profile named "orders-notifications" to allow only US and CA destinations, send webhooks to https://example.com/telnyx/messaging with a failover at https://example.com/telnyx/messaging-backup, and enforce a daily spend limit of 5.00 USD. Then read the profile back and confirm each value.

Requirements:
- Use telnyx CLI 0.32.0 with the TELNYX_API_KEY environment variable.
- `messaging-profiles update` takes the profile id in `--messaging-profile-id`. Repeat `--whitelisted-destination` once per country code.
- `--daily-spend-limit` takes a string such as 5.00 and only takes effect when `--daily-spend-limit-enabled` is set.
- Webhook URLs must use https.
- Use `--transform` to exclude the profile's `v1_secret` field from any output you display.
- Run the verification step below before finishing.

Prerequisites

The Telnyx CLI at version 0.32.0 (go install github.com/team-telnyx/telnyx-cli/cmd/[email protected]) and TELNYX_API_KEY exported.
At least one messaging profile on the account. Run telnyx messaging-profiles create --help to see the creation flags. --name and at least one --whitelisted-destination are required.
Some account levels allow only one messaging profile. See Common issues.

Note: Output below is trimmed with --transform to the fields relevant to each step. The full profile response also contains a v1_secret value, which this guide never prints.

1. Find the profile id

telnyx messaging-profiles list \
  --transform '{id:id,name:name,webhook_url:webhook_url}' \
  --format json

telnyx messaging-profiles list \
  --transform '{id:id,name:name,webhook_url:webhook_url}' \
  --format json

Real output for an account with one profile that has not been configured yet:

{
  "id": "4001a112-7f46-4a40-aa4e-d8e6725420c3",
  "name": "default-profile",
  "webhook_url": null
}

{
  "id": "4001a112-7f46-4a40-aa4e-d8e6725420c3",
  "name": "default-profile",
  "webhook_url": null
}

With list, the transform runs once per profile, so write it against a single profile object ({id:id}), not against data.#.

Export the id for the next steps:

export MESSAGING_PROFILE_ID="4001a112-7f46-4a40-aa4e-d8e6725420c3"

export MESSAGING_PROFILE_ID="4001a112-7f46-4a40-aa4e-d8e6725420c3"

2. Update the profile

telnyx messaging-profiles update \
  --messaging-profile-id "$MESSAGING_PROFILE_ID" \
  --name orders-notifications \
  --whitelisted-destination US \
  --whitelisted-destination CA \
  --webhook-url https://example.com/telnyx/messaging \
  --webhook-failover-url https://example.com/telnyx/messaging-backup \
  --daily-spend-limit 5.00 \
  --daily-spend-limit-enabled \
  --transform 'data.{id,name,enabled,webhook_url,webhook_failover_url,webhook_api_version,whitelisted_destinations,daily_spend_limit,daily_spend_limit_enabled}' \
  --format json

telnyx messaging-profiles update \
  --messaging-profile-id "$MESSAGING_PROFILE_ID" \
  --name orders-notifications \
  --whitelisted-destination US \
  --whitelisted-destination CA \
  --webhook-url https://example.com/telnyx/messaging \
  --webhook-failover-url https://example.com/telnyx/messaging-backup \
  --daily-spend-limit 5.00 \
  --daily-spend-limit-enabled \
  --transform 'data.{id,name,enabled,webhook_url,webhook_failover_url,webhook_api_version,whitelisted_destinations,daily_spend_limit,daily_spend_limit_enabled}' \
  --format json

Real output:

{
  "id": "4001a112-7f46-4a40-aa4e-d8e6725420c3",
  "name": "orders-notifications",
  "enabled": true,
  "webhook_url": "https://example.com/telnyx/messaging",
  "webhook_failover_url": "https://example.com/telnyx/messaging-backup",
  "webhook_api_version": "2",
  "whitelisted_destinations": ["CA", "US"],
  "daily_spend_limit": "5.00",
  "daily_spend_limit_enabled": true
}

{
  "id": "4001a112-7f46-4a40-aa4e-d8e6725420c3",
  "name": "orders-notifications",
  "enabled": true,
  "webhook_url": "https://example.com/telnyx/messaging",
  "webhook_failover_url": "https://example.com/telnyx/messaging-backup",
  "webhook_api_version": "2",
  "whitelisted_destinations": ["CA", "US"],
  "daily_spend_limit": "5.00",
  "daily_spend_limit_enabled": true
}

The destinations come back sorted (CA, US), not in the order they were passed.

Verify the result

Read the profile back in a separate request and check each configured value:

telnyx messaging-profiles retrieve \
  --messaging-profile-id "$MESSAGING_PROFILE_ID" \
  --transform 'data.{id,name,enabled,webhook_url,webhook_failover_url,webhook_api_version,whitelisted_destinations,daily_spend_limit,daily_spend_limit_enabled}' \
  --format json

telnyx messaging-profiles retrieve \
  --messaging-profile-id "$MESSAGING_PROFILE_ID" \
  --transform 'data.{id,name,enabled,webhook_url,webhook_failover_url,webhook_api_version,whitelisted_destinations,daily_spend_limit,daily_spend_limit_enabled}' \
  --format json

Expected: the same object as step 2, with name set to orders-notifications, both webhook URLs set, whitelisted_destinations equal to ["CA", "US"], and daily_spend_limit of "5.00" with daily_spend_limit_enabled true.

How it works

update sends a partial update to the profile, so fields you omit keep their current values. retrieve is a separate GET of the stored profile, which makes it a check on what was saved, not on what the update call echoed back. The spend limit is two settings: the amount (daily_spend_limit) and the switch (daily_spend_limit_enabled).

Common issues

Creating a second profile can fail with an account-limit error

On the account used for this guide, telnyx messaging-profiles create returned HTTP 403, error code 10039, with the detail Only 1 messaging profile is allowed at this account level. Refer to https://telnyx.com/upgrade. Update the existing profile instead, as shown above.

`create` requires a destination

Running telnyx messaging-profiles create --name bad-hook --webhook-url ftp://example.com/x fails before any request is sent with Required flag "whitelisted-destination" not set.

Webhook URLs must be https

Updating --webhook-url to ftp://example.com/x returns HTTP 400, error code 10003, detail The supplied URL is invalid., with the pointer /webhook_url. Updating it to http://example.com/x returns the same error code with the detail URL scheme must be https.

Destination codes must be ISO country codes

--whitelisted-destination XX returns HTTP 400, error code 10015, with the detail All items in the whitelisted destinations list must be valid ISO 3166-1 alpha-2 country codes.

A non-numeric spend limit returns a server error

--daily-spend-limit abc returned HTTP 500, error code 10007, with the detail Failed to update profile with profile_id '<id>'. Pass a decimal string such as 5.00.

Clearing a webhook and disabling a profile

Passing an empty string, --webhook-url "", reset webhook_url to null. --enabled=false set enabled to false, and --enabled set it back to true.

Looking up an id that does not exist

telnyx messaging-profiles retrieve --messaging-profile-id 00000000-0000-0000-0000-000000000000 returns HTTP 404, error code 10005, Resource not found.

Next steps

Search for a number to attach to the profile: 01-search-available-phone-numbers-with-the-telnyx-cli.md.
Verify the webhooks this profile sends: 04-verify-telnyx-webhook-signatures-in-python.md.

verification:
  status: verified
  tested_at: "2026-10-06"
  product_version: "telnyx CLI 0.32.0"
  command: "telnyx messaging-profiles retrieve --messaging-profile-id \"$MESSAGING_PROFILE_ID\" --transform 'data.{id,name,enabled,webhook_url,webhook_failover_url,webhook_api_version,whitelisted_destinations,daily_spend_limit,daily_spend_limit_enabled}' --format json"
  expected_result: "The stored profile shows name orders-notifications, both webhook URLs, whitelisted_destinations [CA, US], and daily_spend_limit 5.00 with daily_spend_limit_enabled true."

verification:
  status: verified
  tested_at: "2026-10-06"
  product_version: "telnyx CLI 0.32.0"
  command: "telnyx messaging-profiles retrieve --messaging-profile-id \"$MESSAGING_PROFILE_ID\" --transform 'data.{id,name,enabled,webhook_url,webhook_failover_url,webhook_api_version,whitelisted_destinations,daily_spend_limit,daily_spend_limit_enabled}' --format json"
  expected_result: "The stored profile shows name orders-notifications, both webhook URLs, whitelisted_destinations [CA, US], and daily_spend_limit 5.00 with daily_spend_limit_enabled true."