SMS Trunk Groups#

Note

To configure SMS trunk groups in the User Panel, see SMS Trunk Groups.

Use the SMS Trunk Groups resource to create, retrieve, update, and delete groups of SMS trunks used for inbound SMS routing.

An SMS Trunk Group organizes several inbound-capable SMS Trunks into one routing destination that can be assigned to DIDs. The priority of each member trunk defines the order in which DIDWW attempts delivery: inbound SMS are offered to the trunk with the higher priority value first, which provides failover between the trunks of the group.

Each group has a unique name and an optional external reference ID. Group records also provide their member trunks, the DIDs routed to the group, and the number of trunks in the group.

SMS trunk groups are available starting from version 2026-11-19.

Requirements and behavior#

When creating, updating, or deleting an SMS Trunk Group:

  • Provide a name when creating the group. The name must be unique among the SMS trunks and SMS trunk groups of the account.

  • Sending the sms_trunks relationship replaces the whole membership of the group with the listed trunks. Send an empty list to remove all trunks.

  • Only SMS trunks of your account that handle inbound messages can be members: sms_to_email, http_in, smpp_esme, and smpp_smsc. http_out trunks and other groups cannot be added, and the list must not contain duplicates.

  • A trunk can also join or leave a group through the sms_trunk_group relationship of the SMS Trunk. The member order is set with the trunk’s priority.

  • incoming_dids is read-only. To route inbound SMS of a DID to a group, update the sms_trunk_group relationship of the DID.

  • SMS trunk groups count toward the same account limit as SMS trunks. When the limit is reached, a create request returns 400 Bad Request with the title Quota limit reached.

  • Deleting a group also deletes every trunk in the group; the member trunks are not kept as standalone trunks. The request is rejected while any DID is routed to the group or to any of its trunks.

Endpoints#

Action

Method

Endpoint

Retrieve all SMS Trunk Groups

GET

/v3/sms_trunk_groups

Retrieve SMS Trunk Group

GET

/v3/sms_trunk_groups/{id}

Create SMS Trunk Group

POST

/v3/sms_trunk_groups

Update SMS Trunk Group

PATCH

/v3/sms_trunk_groups/{id}

Delete SMS Trunk Group

DELETE

/v3/sms_trunk_groups/{id}

Retrieve all SMS Trunk Groups#

Retrieves all SMS Trunk Groups configured for the account.

Use this endpoint to filter groups by name, external reference ID, or ID, and sort results by name, external reference ID, creation time, or update time. Member trunks and incoming DIDs can be included in the response.

See Retrieve All SMS Trunk Groups.

GET /v3/sms_trunk_groups

Retrieve SMS Trunk Group#

Retrieves a specific SMS Trunk Group by its unique ID.

Use this endpoint to inspect the group settings, member-trunk count, member trunks, and the DIDs routed to the group.

See Retrieve SMS Trunk Group.

GET /v3/sms_trunk_groups/{id}

Create SMS Trunk Group#

Creates an SMS Trunk Group.

Provide a unique group name and optionally set an external reference ID and the SMS trunks that should belong to the group.

See Create SMS Trunk Group.

POST /v3/sms_trunk_groups

Update SMS Trunk Group#

Updates a specific SMS Trunk Group.

Use this endpoint to change the group name, external reference ID, or member trunks. Sending sms_trunks replaces the whole membership.

See Update SMS Trunk Group.

PATCH /v3/sms_trunk_groups/{id}

Delete SMS Trunk Group#

Deletes a specific SMS Trunk Group together with all of its member trunks. The request is rejected while any DID is routed to the group or to any of its trunks.

See Delete SMS Trunk Group.

DELETE /v3/sms_trunk_groups/{id}

Data reference#

See SMS Trunk Group Object for the complete group attribute, relationship, and metadata definitions.

Common SMS Trunk Group use cases#

Use case

Description

Configure failover for inbound SMS

Combine several inbound-capable trunks and set their priority values to control the delivery order.

Route DIDs to one destination

Assign the group to DIDs through the DID sms_trunk_group relationship.

Manage group membership

Replace the member trunks when creating or updating the group.

Inspect member trunks

Include the sms_trunks relationship and review the returned sms_trunks_count metadata.

Synchronize external systems

Store an external_reference_id for the corresponding record in another system.