SMS API Documentation

What is an SMS API?

An API (Application Programming Interface) acts as an interface between the code you write and our SMS Gateway.

This document provides a reference for all features available to you via the HTTP interface for sending SMS.
It is quick to get started (copy and paste a URL directly in your web browser to send a message!) and there is no need to understand the additional or advanced features unless you want to use them.

 

Request Parameters

SMS messages are sent by making HTTPS calls to the API. You can loop through your list of mobile numbers and make HTTPS requests to send SMS messages to them.

Parameter Required Description
Username_prefix Yes Specifies the account’s name. eg. Dreamweb_Resl
username Yes Specifies the username. It is a unique identification chosen by the client at the time of registration or sign-up. Each account detail is uniquely linked to a username and the username cannot be changed after successful creation. The user is authenticated by the username and password parameters. When you send a message, it will be sent in the name of the authenticated user. The value must be URL.
password Yes Specifies the password. The password is obtained after sign up and It should be at least 8 characters with alphanumeric text and at least a special character (e.g. @). The user is authenticated by the username and password parameters. When you send a message, it will be sent in the name of the authenticated user. The value must be URL.
type Yes Specifies the message type. It indicates whether it is a text message or a flash. The value of the type parameter is always 0 is for simple text messages, 1 is for flash messages
dlr Yes Specifies delivery report request. It has a constant value of 1 for a DLR request. It is recommended that this parameter is not modified.
source Yes Specifies the sender’s address. When the message arrives on the phone, this information will be displayed. This can be alpha text (e.g. DREAMWEB), numeric (e.g. 123), alphanumeric (e.g. dreamweb123) The maximum character length is eleven (11). Sender address with spaces in between (e.g. DREAM WEB) should be URL encoded.
destination Yes Specifies the recipient’s phone number. The message will be sent to this telephone number. The telephone number can be specified in local number format (e.g. 024113234), or in international number format (e.g. 23324113234).
message Yes Specifies the text or the data of the SMS message. The value must be encoded in UTF8 and must be URL encoded.
callback_url No Specifies the client’s URL to send a delivery report on the status of messages sent out. The response is JSON formatted.
key No specifies client’s unique key for API calls. When implemented the username and password parameter will be ignored. We recommend you url encode the auth key or url before request.
validity_period No Specifies how long the message will be valid, i.e., how long the Operator/Telco will try to send the message to the recipient. Defined in minutes. E.g a validity set to 5 means the SMS will expire within 5 minutes. This is beneficial for OTP type messages.

 

Send SMS Using Username & Password (GET)

https://app.dreamwebgroup.com/smsbackend/clientapi/Dreamweb_Resl/send-message/?username=johndoe&password=some_password&type=0&destination=233XXXXXXXXX&dlr=1&source=DREAMWEB&message=This+is+a+test+from+Mars

PARAMETERS

username: johndoe

password: some_password

type: 0

destination: 233XXXXXXXXX

dlr: 1

source: USERCODE

message: This+is+a+test+from+Mars

 

 

Send SMS Using Authentication Key (GET)

https://app.dreamwebgroup.com/smsbackend/clientapi/Dreamweb_Resl/send-message/?key={{AUTH_KEY}}&type=0&destination=233XXXXXXXXX&dlr=1&source=DREAMWEB&message=This+is+a+test+from+Mars

We recommend you url encode the auth key or url before request

PARAMETERS

key: {{AUTH_KEY}}

type: 0

destination: 233XXXXXXXXX

dlr: 1

source: DREAMWEB

message: This+is+a+test+from+Mars

 

Response Codes

1701: Success, Message Submitted Successfully, in this case you will receive the response

1701|<phone_number>|<message_ID>

The message Id can then be used later to map the delivery reports to this message.

Error Code Description
1702 Invalid URL Error, This means that one of the parameters was not
provided or left blank
1703 Invalid value in username or password field
1704 Invalid value in “type” field
1705 Invalid Message
1706 Invalid Destination
1707 Invalid Source (Sender)
1708 Invalid value for “dlr” field
1709 User validation failed
1710 Internal Error
1025 Insufficient Credit User
1026 Insufficient Credit Reseller