SMS Trunks#

Note

To configure SMS trunks in the User Panel, see SMS Trunks. For the message formats and protocols used by the trunks, see the SMS HTTP specification and the SMPP specification.

Use the SMS Trunks resource to create, retrieve, update, and delete SMS trunks, and to regenerate the credentials DIDWW generates for some trunk types.

An SMS trunk defines how DIDWW delivers the inbound SMS sent to your DIDs, how your application submits outbound SMS to DIDWW, or both. The configuration attribute selects the trunk type, and the type decides which configuration attributes the trunk takes and which directions it handles:

Configuration type

Direction

Description

sms_to_email

Inbound

DIDWW forwards inbound SMS as email.

http_in

Inbound

DIDWW delivers inbound SMS as an HTTP request to your endpoint.

http_out

Outbound

Your application submits outbound SMS to DIDWW over HTTP.

smpp_esme

Inbound and outbound

Your application connects to DIDWW as an SMPP ESME.

smpp_smsc

Inbound and outbound

DIDWW connects to your SMSC as an SMPP client.

SMS trunks are available starting from version 2026-11-19.

Requirements and behavior#

When creating or updating an SMS trunk:

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

  • The configuration type cannot be changed after the trunk is created. On update, the configuration.type must match the trunk’s type; the configuration attributes you send are written and the others keep their stored values.

  • Each configuration type requires its own set of attributes on creation. See Create SMS Trunk.

  • priority and the sms_trunk_group relationship apply only to the trunk types that can join an SMS Trunk Group: sms_to_email, http_in, smpp_esme, and smpp_smsc. On these types priority defaults to 100. On http_out trunks priority must stay null and a group cannot be assigned.

  • allow_any_did_as_source can be enabled only on the trunk types that send messages: http_out, smpp_esme, and smpp_smsc. Enabling it removes all outgoing_dids, which must stay empty while it is true.

  • outgoing_dids accepts only DIDs of your account that support the p2p feature, and rejects DIDs awaiting registration.

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

  • smpp_esme and http_out trunks receive credentials generated by DIDWW. They are returned as read-only configuration attributes and can be replaced with Regenerate SMS Trunk Credentials.

  • The number of SMS trunks and SMS trunk groups an account can create is limited. When the limit is reached, a create request returns 400 Bad Request with the title Quota limit reached. Contact DIDWW Support to request a higher limit.

  • A trunk cannot be deleted while any DID is routed to it for inbound SMS. Sender ID verifications that use a deleted trunk are left without one, and their outbound messages stop until another trunk is assigned.

  • sender_id_verifications is read-only. To route a verification through a trunk, update the sms_trunk relationship of the Sender ID Verification.

Endpoints#

Action

Method

Endpoint

Retrieve all SMS Trunks

GET

/v3/sms_trunks

Retrieve SMS Trunk

GET

/v3/sms_trunks/{id}

Create SMS Trunk

POST

/v3/sms_trunks

Update SMS Trunk

PATCH

/v3/sms_trunks/{id}

Delete SMS Trunk

DELETE

/v3/sms_trunks/{id}

Regenerate SMS Trunk credentials

POST

/v3/sms_trunk_regenerate_credentials

Retrieve all SMS Trunks#

Retrieves all SMS trunks configured for the account.

Use this endpoint to filter trunks by name, external reference ID, ID, or configuration type. Outgoing DIDs, incoming DIDs, the SMS trunk group, and Sender ID verifications can be included in the response.

See Retrieve All SMS Trunks.

GET /v3/sms_trunks

Retrieve SMS Trunk#

Retrieves a specific SMS trunk by its unique ID.

Use this endpoint to inspect the trunk configuration, including the generated credentials of smpp_esme and http_out trunks, and the URL of the endpoint to which http_out trunks submit outbound SMS (meta.host).

See Retrieve SMS Trunk.

GET /v3/sms_trunks/{id}

Create SMS Trunk#

Creates an SMS trunk of one of the five configuration types.

Provide a unique name and the configuration, and optionally set the external reference ID, status, priority, source-address settings, outgoing DIDs, and the SMS trunk group.

See Create SMS Trunk.

POST /v3/sms_trunks

Update SMS Trunk#

Updates a specific SMS trunk.

Use this endpoint to change the trunk name, external reference ID, status, priority, source-address settings, configuration attributes, outgoing DIDs, or SMS trunk group. The configuration type cannot be changed.

See Update SMS Trunk.

PATCH /v3/sms_trunks/{id}

Delete SMS Trunk#

Permanently deletes a specific SMS trunk. The request is rejected while any DID is routed to the trunk for inbound SMS; route those DIDs elsewhere first. Sender ID verifications that use the trunk are left without one, and their outbound messages stop until another trunk is assigned.

See Delete SMS Trunk.

DELETE /v3/sms_trunks/{id}

Regenerate SMS Trunk credentials#

Replaces the generated credentials of an smpp_esme trunk (system_id and password) or an http_out trunk (auth_name and auth_password). The response contains only the trunk ID; retrieve the trunk to read the new credentials.

See Regenerate SMS Trunk Credentials.

POST /v3/sms_trunk_regenerate_credentials

Data reference#

See SMS Trunk Object for the complete trunk attributes, the configuration attributes of each trunk type, relationships, and metadata.

Common SMS Trunk use cases#

Use case

Description

Receive inbound SMS by email

Create an sms_to_email trunk and route DIDs to it.

Receive inbound SMS on a web endpoint

Create an http_in trunk with the URL, method, and request template DIDWW uses to deliver each message.

Send outbound SMS over HTTP

Create an http_out trunk, read its generated credentials and the endpoint URL in meta.host, and submit messages as described in the SMS OUT HTTP specification.

Exchange SMS over SMPP

Create an smpp_esme trunk to bind to DIDWW, or an smpp_smsc trunk to let DIDWW bind to your SMSC.

Control source addresses

Assign outgoing_dids or enable allow_any_did_as_source on a trunk that sends messages.

Configure failover for inbound SMS

Add trunks to an SMS Trunk Group and set their priority.

Rotate credentials

Regenerate the credentials of an smpp_esme or http_out trunk.

Pause a trunk

Set blocked to true to stop the trunk from handling messages.