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.

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.

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

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.

• Data
• Description

07595980013893439611559146736007518

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 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.

• ISO-8859-1
• UTF-16 (UCS2)

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.

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.

• Data
• Description

07595980013893439611559146736007518

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:

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

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

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

Response

• Data
• Description

{
    "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"
        }]
    }
}

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

Response

• Data
• Description

{
    "id": "08087780013866630151559112345",
    "mcc": "402",
    "mnc": "02",
    "imsi": "423908420357320517301",
    "ported": "1"
}

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

• Data
• Description

{
    "error": [],
    "result": {
        "smsCount": 234122,
        "price": "123.4212" 
    }
}

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

• Data
• Description

{
  "result": [
    {
      "price": "0.02",
      "operator": "Aquafon",
      "mccmnc": "28967",
      "mcc": "Aquafon",
      "mnc": "67",
      "country": "Abkhazia",          
      "comment": "Aquafon",
    }
  ]
}

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.