SMS Trunk Object#

JSON:API object with type sms_trunks.

The trunk type is defined by data.attributes.configuration.type. The configuration attributes depend on the type. See Configuration.

Request#

URI Parameters#

Name

Type

Is Required?

Description

id

string

Yes

Unique identifier of the SMS trunk.

Data Attributes#

Name

Type

Description

name

string

Friendly name of the SMS trunk. Must be unique among the SMS trunks and SMS trunk groups of the account.

external_reference_id

string

Optional identifier for the SMS trunk in the customer’s external system. Maximum length is 100 characters. Can be null.

blocked

boolean

When true, the trunk does not handle messages. Default value is false.

priority

integer

Routing priority of the trunk within its SMS Trunk Group. The range is 0-32767. Defaults to 100 on the trunk types that can join a group (sms_to_email, http_in, smpp_esme, smpp_smsc). Always null on http_out trunks, which cannot join a group. Inbound messages are offered to the trunk with the higher priority value first. See SMS Trunk Groups for how priority is applied.

allow_any_did_as_source

boolean

When true, any DID of the account can be used as the source address of messages sent through the trunk, and outgoing_dids is empty. Can be enabled only on http_out, smpp_esme, and smpp_smsc trunks. Default value is false.

allow_in

boolean

Read-only. true when the trunk handles inbound messages. Derived from the configuration type.

allow_out

boolean

Read-only. true when the trunk can send messages. Derived from the configuration type.

configuration

object

Trunk configuration object with type and attributes. See Configuration.

created_at

DateTime

Read-only. The date and time when the SMS trunk was created.

updated_at

DateTime

Read-only. The date and time when the SMS trunk was last updated.

Object Relationships#

Name

Type

Description

outgoing_dids

to-many

DID Object. DIDs allowed as the source address of messages sent through the trunk. Empty while allow_any_did_as_source is true.

incoming_dids

to-many

DID Object. Read-only. DIDs routed to the trunk for inbound messages. A DID is routed to a trunk through the sms_trunk relationship of the DID.

sms_trunk_group

to-one

SMS Trunk Group Object. The group the trunk belongs to. Can be null.

sender_id_verifications

to-many

Sender ID Verification Object. Read-only. Sender ID verifications routed through the trunk. A verification is routed through a trunk with its sms_trunk relationship.

Object Meta#

Name

Type

Description

host

string

Full URL of the endpoint to which outbound messages are submitted, for example https://us.sms-out.didww.com/outbound_messages. Returned for http_out trunks only. The other endpoints listed in the SMS OUT HTTP specification also accept the trunk’s messages.

Configuration#

The configuration object contains:

Name

Type

Description

type

string

Configuration type. Possible values: sms_to_email - DIDWW forwards inbound messages as email. http_in - DIDWW delivers inbound messages as an HTTP request. http_out - the customer submits outbound messages to DIDWW over HTTP. smpp_esme - the customer connects to DIDWW as an SMPP ESME. smpp_smsc - DIDWW connects to the customer’s SMSC as an SMPP client. The type cannot be changed after the trunk is created.

attributes

object

Configuration attributes. Their set depends on type.

The configuration type defines what the trunk can do:

Type

allow_in

allow_out

Can join a group

Generated credentials

sms_to_email

true

false

Yes

None

http_in

true

false

Yes

None

http_out

false

true

No

auth_name, auth_password

smpp_esme

true

true

Yes

system_id, password

smpp_smsc

true

true

Yes

None

Read-only attributes are generated by DIDWW and cannot be sent in requests. Generated credentials can be replaced with Regenerate SMS Trunk Credentials.

sms_to_email#

DIDWW forwards inbound messages as email. See SMS to Email trunk.

Name

Type

Nullable

Read-only

Description

send_to

string

No

No

Recipient email address.

subject

string

No

No

Email subject template.

message

string

No

No

Email body template.

http_in#

DIDWW delivers inbound messages as an HTTP request. The query parameters, headers, and body can use the placeholders {SMS_TEXT}, {SMS_TEXT_BASE64_ENCODED}, {SMS_SRC_ADDR}, {SMS_DST_ADDR}, and {SMS_TIME}. See SMS IN HTTP specification and SMS to HTTP IN trunk.

Name

Type

Nullable

Read-only

Description

url

string

No

No

Endpoint the request is sent to.

http_method

string

No

No

HTTP method of the request. Possible values: get; post; put.

query_parameters

object

Yes

No

Query parameters added to the request, as an object of string names and string values.

headers

object

Yes

No

Headers added to the request, as an object of string names and string values.

body_type

string

Yes

No

How body is encoded. Possible values: json; html_multipart; html_url_encoded; raw. null when http_method is get.

body

string or object

Yes

No

Request body template. A JSON object encoded as a string when body_type is json. An object of string names and string values when body_type is html_multipart or html_url_encoded. A string when body_type is raw. null when http_method is get.

follow_redirect

boolean

No

No

When true, DIDWW follows 3xx responses. Default value is false.

validate_https_certificate

boolean

No

No

When true, DIDWW rejects an untrusted TLS certificate of the endpoint. Default value is true.

http_out#

The customer submits outbound messages to DIDWW over HTTP, to the endpoint URL returned in meta.host. See SMS OUT HTTP specification and SMS to HTTP OUT trunk.

Name

Type

Nullable

Read-only

Description

callback_url

string

Yes

No

HTTP(S) URL to which DIDWW sends the status events of messages submitted through the trunk. See SMS OUT callbacks.

allowed_ips

Array of strings

Yes

No

IP addresses from which messages are accepted, in the format (IPv4|IPv6)[/mask]. Up to 15 unique entries. Single addresses are returned as /32 (IPv4) or /128 (IPv6) networks; IPv6 addresses are returned in full (uncompressed) notation. When empty, messages are accepted from any address.

auth_name

string

Yes

Yes

Generated HTTP authentication username. See SMS OUT authentication.

auth_password

string

Yes

Yes

Generated HTTP authentication password.

smpp_esme#

The customer connects and binds to DIDWW as an SMPP ESME. See SMPP specification, SMPP over TLS, and SMPP ESME trunk.

Name

Type

Nullable

Read-only

Description

system_type

string

Yes

No

SMPP system_type. Maximum length is 12 characters.

allowed_ips

Array of strings

Yes

No

IP addresses from which the ESME may bind, in the format (IPv4|IPv6)[/mask]. Up to 15 unique entries. Single addresses are returned as /32 (IPv4) or /128 (IPv6) networks; IPv6 addresses are returned in full (uncompressed) notation. When empty, binding is allowed from any address.

server_location

string

No

No

Location of the DIDWW SMPP server the trunk is served from. Possible values: nyc - US, NY. ams - NL, AMS. In the sandbox environment only nyc is accepted. See Server locations and IP addresses.

system_id

string

No

Yes

Generated SMPP system_id to bind with.

password

string

No

Yes

Generated SMPP bind password.

smpp_smsc#

DIDWW connects and binds to the customer’s SMSC as an SMPP client. See SMPP specification and SMPP SMSC trunk.

Name

Type

Nullable

Read-only

Description

host

string

No

No

SMSC host DIDWW binds to.

tx_port

integer

No

No

Transmitter port. Default value is 2775.

rx_port

integer

No

No

Receiver port. Default value is 2776.

transceiver_mode

boolean

No

No

When true, DIDWW binds as a transceiver instead of separate transmitter and receiver binds. Default value is false.

connection_timeout

integer

No

No

Bind timeout in seconds. Default value is 20.

use_ssl

boolean

No

No

When true, the connection is wrapped in TLS. Default value is false.

system_id

string

No

No

SMPP system_id DIDWW binds with. Maximum length is 15 characters.

system_type

string

Yes

No

SMPP system_type. Maximum length is 12 characters.

password

string

No

No

SMPP bind password. Maximum length is 8 characters.

server_location

string

No

No

Location of the DIDWW SMPP server that connects to the SMSC. Possible values: nyc - US, NY. ams - NL, AMS. In the sandbox environment only nyc is accepted. See Server locations and IP addresses.