# SMS Trunk Groups

Note

To configure SMS trunk groups in the User Panel, see
[SMS Trunk Groups](../../../../sms/sms-trunks/trunk-groups/sms-trunk-groups.html#user-panel-sms-trunk-group).

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](../sms-trunks/index.html)
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](../sms-trunks/index.html). 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](../did/index.html).
- 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-sms-trunk-groups.html).

```
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-sms-trunk-group.html).

```
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](create-sms-trunk-group.html).

```
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](update-sms-trunk-group.html).

```
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-sms-trunk-group.html).

```
DELETE /v3/sms_trunk_groups/{id}
```

## Data reference

See [SMS Trunk Group Object](sms-trunk-group-object.html) 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. |

## Related resources

Use SMS Trunk Groups together with SMS Trunks and DIDs to configure inbound SMS delivery.

| Resource | Description |
| --- | --- |
| [SMS Trunks](../sms-trunks/index.html) | Inbound SMS destinations that can be members of a group. |
| [DIDs](../did/index.html) | DID phone numbers that can use an SMS Trunk Group for inbound SMS routing. |
