HTTP IN trunk#

HTTP IN SMS trunks allow you to forward incoming SMS messages from your Direct Inward Dialing (DID) numbers to a specified web server or application endpoint. Each message is delivered as an HTTP request.

Use this trunk type when an application or web server should receive the messages sent to your DID numbers. To receive messages by email instead, use an SMS to Email trunk. To exchange messages over SMPP, use an SMPP ESME trunk or an SMPP SMSC trunk. An HTTP IN trunk receives inbound messages. To send messages over HTTP, use an HTTP OUT trunk.

How inbound SMS reaches your HTTP endpoint#

When someone sends an SMS to one of your DID numbers, DIDWW uses the SMS trunk assigned to that number to determine where to deliver the message. For an HTTP IN trunk, DIDWW sends an HTTP request to the trunk’s Request URL. Variables in the request carry data from the received message, such as the sender’s number and the message text.

        %%{init: {
  "theme": "base",
  "themeVariables": {
    "fontSize": "14px",
    "primaryColor": "#e0f2fe",
    "primaryBorderColor": "#38bdf8",
    "primaryTextColor": "#1f2d3d",
    "secondaryColor": "#ccfbf1",
    "secondaryBorderColor": "#2dd4bf",
    "secondaryTextColor": "#1f2d3d",
    "lineColor": "#0066cc",
    "textColor": "#1f2d3d",
    "nodeTextColor": "#1f2d3d",
    "edgeLabelBackground": "#ffffff"
  }
}}%%

flowchart LR

    sender["Sender"] --> |sends SMS| did["DID number"]
    did --> |assigned trunk| trunk["HTTP IN trunk"]
    trunk --> |HTTP request| app["Your HTTP endpoint"]
    app -.-> |2xx response| trunk

    classDef endpoint fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px
    classDef process fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px

    class sender,app endpoint
    class did,trunk process

    linkStyle default stroke:#0066cc,stroke-width:1.5px

HTTP IN trunks and DID numbers#

A DID number receives the inbound SMS, while the HTTP IN trunk defines the endpoint to which DIDWW delivers it. To receive messages, assign the HTTP IN trunk or an SMS trunk group containing it to one or more DID numbers that support inbound SMS. Creating a trunk does not assign it to a DID number.

Multiple DID numbers can use the same HTTP IN trunk. The {SMS_DST_ADDR} variable adds the DID number that received each message to the request, so that your endpoint can tell the numbers apart. See Request variables.

Integration choices#

You define the request that DIDWW sends to your endpoint. The HTTP Method can be GET, POST, or PUT. Optional Query Parameters and Headers add custom key-value pairs and HTTP headers to each request. For POST and PUT, the Body type sets the format of the request body, such as JSON. With GET, message data can be sent only in the Request URL, Query Parameters, and Headers.

Variables insert data from the received message into the Request URL, Query Parameters, Headers, and request body. The body format must match the format that your endpoint expects. See Request variables and Body type values.

HTTPS is recommended for the Request URL, and HTTP is also supported. With Validate HTTPS Certificate enabled, DIDWW validates the certificate of your server. With Follow redirect enabled, DIDWW follows HTTP 3xx redirect status codes.

DIDWW sends the requests from DIDWW-defined source IP addresses. If your endpoint is behind a firewall, the firewall must allow these addresses. See HTTP request details from DIDWW.

For all fields, see HTTP IN trunk settings reference.

Delivery and retries#

If your endpoint does not respond with a 2xx status code, DIDWW re-attempts to deliver the message until its time to live (TTL) of 3600 seconds (1 hour) expires. See Inbound SMS technical details.

Inbound SMS logs show the delivery status of each message and the reason for a failed delivery.

Concatenated messages#

A long SMS can arrive as a concatenated message that consists of several parts. DIDWW reassembles concatenated messages using the User Data Header (UDH) before it delivers them to your endpoint. Information about fragmentation is not transmitted. The maximum size of an inbound SMS message is 64 KB. See Inbound SMS technical details.

For encoding limits, concatenation, and fragment billing, see SMS encoding reference. To compare how each trunk type delivers multipart messages, see Reassembly by transport.

Failover with SMS trunk groups#

An HTTP IN trunk delivers messages to a single Request URL. You can add the trunk to an existing SMS trunk group to enable failover, and assign the group to your DID numbers. Within the trunk group, the trunk’s Priority determines the order in which trunks will be used.

Note

The system attempts to contact the target SMS trunk with the highest-numbered priority first.