HTTP Specification

SMS IN

SMS via HTTP

HTTP Trunk supports both encrypted (HTTPS) and non-encrypted (HTTP) connection types for SMS data exchange. Supported HTTP Methods: PUT, POST, GET

Note

DIDWW will send the SMS from IP address 46.19.209.214

Available variables for Path, Headers, and Request Body:

{SMS_UUID} - The ID of the received message.
{SMS_SRC_ADDR} - Source number of SMS sender. RFC 3986 encoded.
{SMS_DST_ADDR} - Destination number to which SMS is received. RFC 3986 encoded.
{SMS_TEXT} - The SMS Message body raw format.
{SMS_TEXT_BASE64_ENCODED} - The SMS Message body. Encrypted using Base 64 encoding.
{SMS_TIME} - Message receive date and time. RFC 1123 encoded.

The Request Body may be delivered using the following HTTP methods:

RAW - the request body will be sent to customers system without changes.
JSON - the request body will be sent to customers system in JSON format.
HTML URL encoded - the request body will be sent to customers system in HTML URL Encoded format.
HTML Multipart - the request body will be sent to customers system in HTML Multipart format.

Failover

DIDWW will re-attempt to deliver the SMS message until TTL expires. TTL Expiration is set to 3600 seconds.

Concatenated Messages

The maximum size of the SMS message is 64 KB. Concatenated messages will be assembled using User Data Header (UDH). Information about fragmentation will not be transmitted.

Incoming SMS Restrictions

If you are unable to receive the incoming SMS to your DID numbers, please review the following:

Local Traffic - the DID numbers are optimized to receive the SMS within the country. International message delivery may be influenced by factors such as:

Local country restrictions for international SMS Traffic.

The origination network routing database is out of date with the numbering plan of the destination country.

A2P - the DID numbers are designed for two-way communication. Certain in-country regulations may restrict A2P traffic to DID numbers.

Important

A2P messages may also be subjected to number validation tools by the originator to reduce costs. The number validation database may be unaware of DID number prefix and consider it an invalid number for messaging.

Important

The use of the DID numbers for SMS verification purposes is not recommended. The same DID number can be obtained by other parties who will gain access to your personal data.

If the above reasons were excluded already, please contact the DIDWW Technical Support with the following data:

Date&Time UTC - when SMS was sent.

Originating Number - the number that SMS was sent from.

Destination DID - the DID number that SMS was sent to.

SMS OUT

Introduction

DIDWW offers Person-to-Person (P2P) and Application-to-Person (A2P) type messaging for SMS supported countries. P2P is generally described as the exchange of text messages between end-users, usually characterised as low-volume and two-way communications. Where as A2P allows businesses to send high volume of automated SMS to a group of people.

The DIDWW Outbound SMS API is a fully compliant implementation of the JSON API specification.

The DIDWW Outbound SMPP SMS is a fully compliant implementation of SMPP specifications.

HTTP SMS Specification

This document assumes that you are familiar with web programming concepts, web data formats and with JSON:API specification. Any additional information about JSON:API is available on their official website.

Headers

All JSON API data MUST be sent with the header Content-Type: application/vnd.api+json without any media type parameters.

Authentication

This section shows you how to allow REST clients to authenticate themselves using basic authentication with a username and password provided as part of the Outgoing Trunk credentials.

Basic authentication

Basic authentication is defined in RFC 2617, HTTP Authentication: Basic and Digest Access Authentication.

Whitelisting an IP address

Whitelisting an IP Address is a security feature that allows you to control who can access the API based on their IP address. After whitelisting an IP address, you can only access the API if you are connecting from a whitelisted IP address. Any access attempts from non-authorised IPs will be blocked. This security tool can help you prevent malicious activity on your account.

Simple example

Most client software provides a simple mechanism for supplying a username and password which it then uses to build the required authentication headers automatically. For example, you can specify the -u argument with cURL as follows:

curl \
    -u username:password \
    -X POST \
    -H "Content-Type: application/vnd.api+json" \
    https://sms-out.didww.com/outbound_messages

Supplying basic auth headers

If you need to, you may construct and send basic auth headers yourself. To do this you need to perform the following steps:

Outbound SMS trunk credentials. Details at Outbound SMS Trunk Creation and Configuration
Build a string of the form username:password.
BASE64 encode the string.
Supply an Authorization header with content Basic followed by the encoded string. For example, the string john:doe encodes to am9objpkb2U= in base64, so you would make the request as follows:

curl \
    -X POST \
    -H "Authorization: Basic am9objpkb2U=" \
    -H "Content-Type: application/vnd.api+json" \
    https://sms-out.didww.com/outbound_messages

Handling exceptions

401 unauthorized

Provided Authorization header is not correct or the request was sent from unauthorized (not allowed) IP address. Refer to Authentication

{
    "errors": [
        {
            "title": "Unauthorized",
            "detail": "Authorization failed",
            "code": "401",
            "status": "401"
        }
    ]
}

400 Bad Request

Request data has incorrect structure. Refer to JSON API specification.

{
    "errors": [
        {
            "title": "Bad Request",
            "detail": "Invalid request",
            "code": "400",
            "status": "400"
        }
    ]
}

Request Format

Post request payload:

{
    "data": {
    "type": "outbound_messages",
    "attributes": {
        "destination": "37041654321",
        "source": "37041123456",
        "content": "Hello World!"
        }
    }
}

Outbound message attributes

destination required

data type: string or Array<string> if used with bulk_outbound_messages type.

Destination number that SMS message is being sent to. Format this number in E.164 format (Country Code + Area Code + Subscriber’s Number, e.g. 123456789). The destinations are limited to a maximum of 1000 numbers in array.

Please note that in case Country Code or Area Code cannot be processed because of its absence in your price list, callback with code_id 2 will be sent. Details on Callback status codes

source optional

data type: string

Source number that message is being sent from. This is your DID number. Format this number in E.164 format (Country Code + Area Code + Subscriber’s Number e.g. 123456789)

Please note that only numbers from the list configured in Outbound SMS Trunk are accepted, otherwise callback with code_id 8 will be sent. Details on Callback status codes

content required

data type: string

this parameter includes full text of the message that you will send. A single message is 160 characters in length. support encoding is UTF8

campaign_id optional

data type: string

this parameters includes the campaign ID of the registered A2P campaign.

Status Callbacks

You can receive events related to your message processing status using the Callback mechanism. See Callback URL configuration of your Outbound SMS trunk.

Callback request

Notification payload is sent by using HTTP POST method:

{
    "data": {
        "type": "outbound_message_callbacks",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "attributes": {
            "time_start": "1997-07-16T19:20:30.45Z",
            "end_time": "2001-07-16T19:20:30.45Z",
            "destination": "37041654321",
            "source": "37041123456",
            "status": "Success",
            "code_id": null,
            "fragments_sent": 7
        }
    }
}

Outbound message callback attributes

time_start

data type: string

Time message was accepted for routing. Formatted in ISO 8601

time_end

data type: string

Time message was sent or time processing finished. Formatted in ISO 8601

source

data type: string

Source number that message is being sent from.

destination

data type: string

Destination number that message is being sent to.

status

data type: string

Current message processing status. Available values: Success, Routing Error, Failed

fragments_sent

data type: integer

Quantity of fragments your message content was split to.

code_id

data type: integer

Error code ID. List of available values at Callback error codes

Callback error codes

Error code	Error meaning
null	Message was sent successfully
1	No routes found
2	No rate found
3	No routes found
4	Internal Error
5	SMS trunk is blocked
6	Internal error
7	Origination account is blocked
8	SMS source address is not allowed
9	SMS destination address is not allowed
10	SMS Campaign not found
11	SMS Campaign blocked
100	No balance available during TTL
101	All termination attempts failed during TTL
102	No encoding available
103	Max balance attempts reached
104	Message defragmentation failed
105	Routing failed

Single SMS example

Single SMS should be sent to the following endpoints of your choice:

Main endpoint: https://sms-out.didww.com/outbound_messages

Additional single SMS endpoints

https://us.sms-out.didww.com/outbound_messages

https://nyc.us.sms-out.didww.com/outbound_messages

https://mia.us.sms-out.didww.com/outbound_messages

https://lac.us.sms-out.didww.com/outbound_messages

https://eu.sms-out.didww.com/outbound_messages

https://sg.sms-out.didww.com/outbound_messages

Note

When campaign_id attribute is present but source attribute is absent, the sender ID value will be assigned randomly from registered campaign.

When source attribute is present with sender ID value from the registered campaign, campaign_id attribute is not required.

http

POST /outbound_messages HTTP/1.1
Host: sms-out.didww.com
Content-Type: application/vnd.api+json
Authorization: Basic

{
    "data": {
    "type": "outbound_messages",
    "attributes": {
        "destination": "37041654321",
        "source": "37041123456",
        "content": "Hello World!"
        }
    }
}

curl

curl -i -X POST https://sms-out.didww.com/outbound_messages -H "Content-Type: application/vnd.api+json" -H "Authorization: Basic" --data-raw '{"data": {"attributes": {"content": "Hello World!", "destination": "37041654321", "source": "37041123456"}, "type": "outbound_messages"}}'

response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "outbound_messages",
        "id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

http

POST /outbound_messages HTTP/1.1
Host: sms-out.didww.com
Content-Type: application/vnd.api+json
Authorization: Basic

{
    "data": {
    "type": "outbound_messages",
    "attributes": {
        "destination": "37041654321",
        "content": "Hello World!",
        "campaign_id": "1111aaa-1a1a-a1a1-aaaa-11aaaaa1111"
        }
    }
}

curl

curl -i -X POST https://sms-out.didww.com/outbound_messages -H "Content-Type: application/vnd.api+json" -H "Authorization: Basic" --data-raw '{"data": {"attributes": {"campaign_id": "1111aaa-1a1a-a1a1-aaaa-11aaaaa1111", "content": "Hello World!", "destination": "37041654321"}, "type": "outbound_messages"}}'

response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "outbound_messages",
        "id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

Single SMS Callback example

If the user has setup callbacks on his desired endpoint, the following attributes will be visible.

../../../_images/fig162.png — **fig. 1.** Single SMS callback

Bulk SMS example

Bulk SMS should be sent to the following endpoints of your choice:

Main endpoint: https://sms-out.didww.com/bulk_outbound_messages

Additional Bulk SMS endpoints

https://us.sms-out.didww.com/bulk_outbound_messages

https://nyc.us.sms-out.didww.com/bulk_outbound_messages

https://mia.us.sms-out.didww.com/bulk_outbound_messages

https://lac.us.sms-out.didww.com/bulk_outbound_messages

https://eu.sms-out.didww.com/bulk_outbound_messages

https://sg.sms-out.didww.com/bulk_outbound_messages

http

POST /bulk_outbound_messages HTTP/1.1
Host: sms-out.didww.com
Content-Type: application/vnd.api+json
Authorization: Basic

{
    "data": {
    "type": "bulk_outbound_messages",
    "attributes": {
        "destination": ["37041654321", "37041654322"],
        "source": "37041123456",
        "content": "Hello World!"
        }
    }
}

curl

curl -i -X POST https://sms-out.didww.com/bulk_outbound_messages -H "Content-Type: application/vnd.api+json" -H "Authorization: Basic" --data-raw '{"data": {"attributes": {"content": "Hello World!", "destination": ["37041654321", "37041654322"], "source": "37041123456"}, "type": "bulk_outbound_messages"}}'

response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
   "data":{
      "type":"bulk_outbound_messages",
      "id":"2C4807D1-74E4-4639-BBC4-057402F052FF",
      "relationships":{
         "outbound_messages":{
            "data":[
               {
                  "type":"outbound_messages",
                  "id":"E34C1810-434B-4E64-AFD9-EC0568F324A9"
               },
               {
                  "type":"outbound_messages",
                  "id":"B6A48E34-3219-407D-99E6-770CF524F611"
               }
            ]
         }
      }
   }
}

Note

When sending bulk SMS, the “destination” attribute must be an Array.

Bulk SMS Callback example

When sending bulk SMS, you will receive callbacks for every single destination number with a unique ID.

../../../_images/fig247.png — **fig. 2.** Bulk SMS callback