Welcome

The HTTP API has been replaced with our new RESTful API. It runs on the same hardware but is not actively developed, and therefore does not have newer features.
If you're in the beginning of integrating our services you should take a look at our RESTful API instead

Introduction

Before you integrate with this API, make sure your account manager has flagged your account as a v1-connection or the responses will be formatted according to our RESTful API standard.

Item Value
Host api.beepsend.com
Port 80 or 443
Protocol HTTP or HTTPS
Authentification Connection Name & Password only
Features Sens SMS, Binary Messages, Scheduled Messages, Flash SMS, Price lists, Current Balance, Statistics, MO messaging
Administrator Page https://connect.beepsend.com

Questions

I've just signed up. I have a username and password. What now?

First and foremost we recommend you checking out our RESTful API, it has more features and is actively maintained. This API is only offering basic functionality for messaging. You can find it http://api.beepsend.com/docs.html

If you still want to use this API, you need to retrieve your account name and password by contacting your account manager as well as tell us that you will be using HTTP API as this is a special flag we must set on your account.

Can I use user tokens?

Nopes, this API was built right around the time the Romans built Rome and as such it dont support such fancy features. Please try out our new RESTful API instead, located at http://api.beepsend.com/docs.html

Do I need a callback URL

Technically "no", but we strongly recommend it to get your delivery receipts.

Where do I set my callback URL

You do that in our customer portal, under "Connections" which you can find at https://connect.beepsend.com/. You log in using your email and a password you should have received in your mail inbox (or just request a new by pressing "forgot password").

This API seems easier than the RESTful one, should I not just stick with this?

We strongly recommend you to use the RESTful API instead. We are here to help you with any questions you might have and though it might seem intimidating at first, once you get the hang of it it really becomes quite easy.

API access is granted by use of Account username and password.

Each request must be accompanied by a account username and password as request parameters.

To find your account username and password, visit the Beepsend Customer Portal or contact your account manager.

The credentials in Querystring

Add your accounts username and password in the request as POST or in querystring if using GET.

Parameter: user, pass

Example

/2/accounts/me?user=abc123&pass=foobar

The endpoint for sending messages is:

GET/POST /gateway.php
Parameter Type Description
to
Required
string The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array. Ex: 46736007500
message
Required
string Message body. If using international characters, You will need to URL encode the message.
from
Optional
string Sender id. If not provided your registered number will be used. encoding
Optional | string | UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is ISO-8859-15. The unicode uses the UCS2 standard UTF16-BE.
msgtype
Optional
string flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters.

The following formats are allowed for from.

* Alphanumeric signs with small characters or capitals (a-z, A-Z, 0-9). The maximum allowed characters are 11.<br/>
* MSISDN numbers, international format. Minimum 9 chars, max 17 chars.<br/>
* Short numbers / codes, national format. Maximum length 7 chars.<br/>

Local restrictions apply. Check with your account-representative for the destinations you aim to send to for details.

Request body

{
    "to": "46736007518",
    "message": "Hello World! 你好世界!",
    "from": "Beepsend",
    "encoding": "UTF-8",
    "msgtype": "flash"
}

Response

When you send SMS using Beepsend web-services you will receive either a unique numeric message id(this is referred to as msg_id in other parts of this document) as acknowledgement of a delivery or a error-message if something was wrong. Error code means that message was rejected by Beepsend and the error-code map http://api.beepsend.com/httpdocs.html#http-errorcodes can guide you to what the error mean. If this happens and you are unsure of the solution, please contact Beepsend support. If you instead receive a message id you can be sure that we have verified the message and accepted it for delivery.

07595980013893439611559146736007518
Key Type Description
return id string Unique Beepsend generated ID. If the SMS got rejected error code is returned

Encoding

For the message body we support either 160 characters using a subset of iso-8859-15 (conforms to GSM7-standard) or all possible characters using the UTF-8 encoding standard. To send characters outside the normal character encoding every character have to be url-encoded. Encoding format: percent sign % and 1 hex code.

UTF-8 example: letter A can be send as: A or %41, letter Å as %C3%85 Unicode example: letter A can be send as: %00%41, letter Å as %00%C5

Since we make a conversion of iso8859-15 into GSM7, the encoding standard for messages to handsets we are not able to send characters not present in GSM7. As such we only support a subset of iso-8859-15. If you have any questions about this, please contact our support. The characters we support in iso-8859-15 are: @£$¥èéùìòÇØøÅå_ÆæßÉ!"#%&'()*+,-./0123456789:;<=>? ¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà^{}[~]|€

Long SMS

Long SMS are SMS with more than 160 characters (70 if encoded with Unicode). Long SMS are sent as concatenated SMS. The concatenation is done automatically so the only thing Beepsend client need to do is to send a a message body with more than 160 characters. The billing is done based on how many messages the full body requires for a successful delivery. One Long SMS that consists of two SMS, counts as two SMS.

Type Characters SMS Count
Ordinary SMS 0-160 1
Long SMS 161-306 2
Long SMS 307-459 3
Type Characters SMS Count
Ordinary SMS 0-70 1
Long SMS 71-132 2
Long SMS 133-198 3

Request Examples

Basic Example with message text “Testing”

http://api.beepsend.com/gateway.php?user=yourusername&pass=yourpassword&to=46701119030&message=Testing

Basic Example with message text “Testing åäö”

http://api.beepsend.com/gateway.php?user=yourusername&pass=yourpassword&to=46701119030&message=Testing%20%e4%e5%f6

Sender ID / message origin

http://api.beepsend.com/gateway.php?user=yourusername&pass=yourpassword&to=34701119030&message=Testing&from=yourcompany

Flash SMS

http://api.beepsend.com/gateway.php?user=yourusername&pass=yourpassword&to=34701119030&message=Testing&from=yourcompany&msgtype=flash

UTF-8:

http://api.beepsend.com/gateway.php?user=yourusername&pass=yourpassword&to=34701119030&message=Testing&from=yourcompany&encoding=UTF-8

Unicode

http://api.beepsend.com/gateway.php?user=yourusername&pass=yourpassword&from=yourcompany&to=34701119030&encoding=Unicode&message=%88%23%88%56%61%1f%8c%22%60%a8

The endpoint for sending binary messages is:

GET/POST /gateway.php

If your system rather sends the messages using binary content we offer a service for this. The combined length of a binary message and UDH can not be longer than 140 bytes (280 hex characters), if you want to send concatenated messages you have to do this by sending a sequence of messages with the appropriate UDH. By changing the UDH-parameter you can send concatenated or Wap Push messages.

Parameter Type Description
to
Required
string The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array. Ex: 46736007500
message
Required
string Binary message, hex encoded.
from
Optional
string Sender id. If not provided your registered number will be used. msgtype
Required | string | Must be set to binary. If omitted, a normal message will be sent.
udh
Optional
string Binary hex-encoded User Data Header
dcs
Optional
integer Data coding setting according to SMPP standard.

The following formats are allowed for from.

* Alphanumeric signs with small characters or capitals (a-z, A-Z, 0-9). The maximum allowed characters are 11.<br/>
* MSISDN numbers, international format. Minimum 9 chars, max 17 chars.<br/>
* Short numbers / codes, national format. Maximum length 7 chars.<br/>

Local restrictions apply. Check with your account-representative for the destinations you aim to send to for details.

Request body

{
    "to": "46736007518",
    "message": "00480065006C006C006F",
    "from": "Beepsend",
    "encoding": "UTF-8",
    "msgtype": "binary",
    "dcs": 8
}

Response

When you send SMS using Beepsend web-services you will receive either a unique numeric message id(this is referred to as msg_id in other parts of this document) as acknowledgement of a delivery or a error-message if something was wrong. Error code means that message was rejected by Beepsend and the error-code map http://api.beepsend.com/httpdocs.html#http-errorcodes can guide you to what the error mean. If this happens and you are unsure of the solution, please contact Beepsend support. If you instead receive a message id you can be sure that we have verified the message and accepted it for delivery.

07595980013893439611559146736007518
Key Type Description
return id string Unique Beepsend generated ID. If the SMS got rejected error code is returned

Request Examples

Example with for sending "Hello" in unicode using binary message

http://api.beepsend.com/gateway.php?user=yourusername&pass=yourpassword&to=34701119030&msgtype=binary&message=00480065006C006C006F&dcs=8

When a text message is received by the Beepsend SMS Gateway, you will receive a delivery report (also called DR, DN or DLR) once we have attempted delivery. The DLR is sent to your specified callback URL by HTTP GET. This message passing procedure is called callback and gives you statistics for if and when a message was delivered. If you don't want delivery notifications you should leave the callback URL-field empty. The first thing to do is specifying the callback URL for your connection. It could be similar to:

Example 1: http://www.youraddress.com/callback
Example 2: http://www.youraddress.com/file.php
Example 3: http://www.youraddress.com/test.asp

Please contact your Account manager to set the callback URL when you're using the HTTP API. Setting it via the customer portal will not work
The delivery-notification you will receive after each sent message contains these parameters:

Parameter Type Description
msg_id string Unique Message ID
status string Message Status - See table below
dlrDate string Delivery Date, format yymmddHHii
dlrStat string Status text. Can be EXPIRED, REJECTD, DELIVRD, UNKNOWN, UNDELIV, FAILED
errorCode string Error Code
mcc
Optional
string Destination Country Code
mnc
Optional
string Destination Operator Code
price
Optional
string SMS Price

Your Response

After a message has been posted, and you have received the message id and the status, you need to send out OK:msg_id in plain text. If you have requested DLR Retry mechanism from your account manager the Beepsend platform will attempt sending the DR with a six minutes interval, until it has received an OK:msg_id from you. Your response to the DR must be: OK:msg_id (in plain text) By specifying that you have received a notification on a given Id we can flag the transaction complete. If you have not requested DLR retry the system will only attempt sending the DR once.

You always have to respond for DR with plain text 'OK:msg_id' (msg_id is the same id that you get as a response to a correctly sent sms). The ErrorCode field in the DLR will contain an error code describing the reason that the message failed to deliver.

Status Code Description
0 Message sent, but no further information has yet been received
1 Message delivered to the mobile handset
2 Message queued in the gateway, will be sent as soon as possible
3 Message failed to be delivered to the mobile handset

Request Examples

The callback URL: http://www.youraddress.com/gateway.php is specified.

You call with:

http://api.beepsend.com/gateway.php?user=testUser&pass=testPass&to=49504700112&message=testMessage&from=testFrom

And get the response "01349291929" (without the quotes). When the message is delivered, we will call this url:

http://www.youraddress.com/gateway.php?status=1&msg_id=01349291929&dlrDate=1007011213&dlrStat=DELIVRD&errorCode=000
<?php

if (!empty($_GET['msg_id']) && !empty($_GET['status'])) {
   //save to database or process $_GET['msg_id'], $_GET['status'], $_GET['dlrDate'], $_GET['errorCode']
   echo 'OK:'.$_GET['msg_id'];
} else echo 'ERROR';

?>

Your balance is updated in real-time and uses a different end point which is:

GET/POST gwparam.php

Issue the string below to see your remaining SMS credits for your account. Replace the USERNAME and PASSWORD with the login information associated with your actual account:

http://api.beepsend.com/gwparam.php?user=USERNAME&pass=PASSWORD&param=sms_count

Mobile Originated sms is sent by end user phone to registered shortcode or longcode. Then mobile operator send it to Beepsend platform. After that Beepsend SMS Gateway will send it your specified callback URL by HTTP GET.

Callback URL

The first thing to do is specifying the callback URL for your connection. It could be similar to:

Example 1: http://www.youraddress.com/callback
Example 2: http://www.youraddress.com/file.php
Example 3: http://www.youraddress.com/test.asp

Please contact your Account manager to set the callback URL when you're using the HTTP API. Setting it via the customer portal will not work

Parameter Type Description
id string Message Id.
timestamps.sms.in int When MO sms reached Beepsend.
to string Destination short- or long-code
message string MO sms body, plain text urlencoded
from string Sender phone number
encoding string Message encoding: ‘Windows-1252’ if possible. If message contain non latin chars then ‘Unicode’ (UTF-16 BE)
mcc
Optional
string Mobile Country Code
mnc
Optional
string Mobile Operator Code
price
Optional
float MO SMS Price in eur.

Response

After you have received the MO sms, you need to send out OK:from in plain text. By specifying that you have received MO sms we can flag the transaction complete.

<?php

if (!empty($_GET['from']) && !empty($_GET['message'])) {
   //save to database or process
$_GET['id'], $_GET['timestamps.sms.in'], $_GET['from'], $_GET['to'], $_GET['message'], $_GET['encoding']
   echo 'OK:'.$_GET['from'];
} else echo 'ERROR';

?>

The API can be utilized to get details of any message sent through Beepsend no matter if you submitted it via SMPP or HTTP.

GET https://api.beepsend.com/1/sms/{smsid}?user=username&pass=password
Parameter Type Description
smsid string The unique message ID returned by Beepsend upon message submission
user string Your account user name
pass string Your account password

Response

{
    "error": [],
    "result": {
        "smsid": "1234567890",
        "sms": [{
            "destAddr": "461234",
            "destTon": "1",
            "destNpi": "1",
            "srcAddr": "465678",
            "srcTon": "1",
            "srcNpi": "1",
            "protocolId": "0",
            "validityPeriod": "",
            "registeredDelivery": "0",
            "dataCoding": "8",
            "smsInTime": "2011-11-11 23:00:03",
            "smsDeliveredTime": "2011-11-11 22:00:00",
            "dlrOutTime": "2011-11-11 23:00:17",
            "dlrStat": "DELIVRD",
            "dlrErr": "000",
            "price": "0.01",
            "mcc": "240",
            "mnc": "26"
        }]
    }
}
Key Type Description
destAddr string Destination MSISDN
destTon int Destination Type of Number
destNpi int Destination Numeric Plan Indicator
srcAddr string Source MSISDN
srcTon int Source Type of Number
srcNpi int Source Numeric Plan Indicator
protocolId int SMPP PID value if present
validityPeriod string Expiry time set on the message
dataCoding int Character encoding used
smsInTime string Timestamp of when Beepsend receives the message in UTC timezone
smsDeliveredTime string Local time from the SMSC that delivered the message
dlrOutTime string Timestamp of when Beepsend returns the Delivery Recipient in UTC timezone
dlrStat string Current Delivery Receipt Status
dlrErr string Eventual Delivery Receipt error code
price float Price of the message
mcc string Mobile Country Code
mnc string Mobile Network Code

This call will give you accumulated statistics for traffic sent between two specidied dates. The call counts messages all messages submitted, indifferent if is was sent via SMPP, REST API or HTTP API.

GET https://api.beepsend.com/1/stats/cummulative?user=username&pass=password&from=2012-10-01&to=2012-10-31
Parameter Type Description
user string Your account user name
pass string Your account password
from string First date to consider according to YYYY-MM-DD
to string Last date to consider according to YYYY-MM-DD

Response

{
    "id": "08087780013866630151559112345",
    "mcc": "402",
    "mnc": "02",
    "imsi": "423908420357320517301",
    "ported": "1"
}
Key Type Description
smsCount int The number of messages processed by the given dates
price float The accumulated price for those messages in Euro (€)

Request Example

Example to get statistics for dates 2013-10-01 to 2013-10-31

GET https://api.beepsend.com/1/stats/cummulative?user=username&pass=password&from=2012-10-01&to=2012-10-31

Request Example Response

{
    "error": [],
    "result": {
        "smsCount": 234122,
        "price": "123.4212" 
    }
}
Key Type Description
error string If an error occurred it will be plain text here, [] if no error
result string json object with result data
smsCount int The number of messages processed by the given dates
price int The accumulated price for those messages in Euro (€)

This call will give you your current pricelist.

GET https://api.beepsend.com/1/pricelist?user=username&pass=password

Parameter | Type | Description ------------------------------------------------------------------|-----------------|------------ user | string | Your account user name pass | string | Your account password token | string | API token if used instead of user and password type | string | Defaults to json. Available formats: json, csv. fields | string | What fields to include in the output. Available fields: mcc, mnc, mccmnc, country, operator, price, comment delimiter | string | If CSV is requested delimiter allows you with which character we generate the CSV-file. Available delimiters: ; | : ,

Response

{
  "result": [
    {
      "price": "0.02",
      "operator": "Aquafon",
      "mccmnc": "28967",
      "mcc": "Aquafon",
      "mnc": "67",
      "country": "Abkhazia",          
      "comment": "Aquafon",
    }
  ]
}
Key Type Description
price float The accumulated price for those messages in Euro (€)
operator string The operator name
mcc string Mobile Country Code
mnc string Mobile Network Code
mccmnc string Combined MCC and MNC
country string Country name
comment string If there is any restrictions it is noted in comment

Error codes that will be returned when using our HTTP API.

Error code means that the message was rejected by Beepsend and the error-code map below can guide you to what the error means. If this happens and you are unsure of the solution, please contact Beepsend support. If you instead receive a message id you can be sure that we have verified the message and accepted it for delivery.

Status Code Description
E255 Unknown error
E1024 Out of credits
E1025 Illegal characters in message body
E1026 Message body error
E1027 No Valid Route found
E1028 Message too long
E1029 Internal server error
E1030 Invalid source address
E1031 Invalid destination address
E1032 Invalid account or password
E1033 Invalid send time
E1034 Login incorrect
E1035 Flood detected
E1036 Invalid parameter
E1037 Invalid receive dlr value