Developers
Hi Buddie! | Login | Sign Up | Messaging Solutions | BBN
Applications Tools Documentations Support

Documentation /
HTTP API Integration Guide

Download the PDF Version

Introduction

This documentation is intended for developers’ use only and contains technical terms which will be better interpreted by the target users. For an offline version of this guide, click the Download the PDF Version button above.

Alternatively, you can use BBN SMS Gateway PHP SDK for faster integration.

Document History:


Original Drafted: June 8th, 2008
Modified: August 25th, 2012
Last Modified: November 23rd, 2012

Modifications

Domain: formerly www.bbnsms.com is now sms.bbnplace.com

Basic API:

http://sms.bbnplace.com/bulksms/

Secure API:

https://www.bbnplace.com/sms/bulksms/

 

Purpose of Documentation


The purpose of this documentation is to provide third party integrators and users a comprehensive guide on how to connect their web portals and service applications to the BBN SMS Gateway over HTTP connection.

User Authentication

When an API request is submitted to BBN SMS Gateway, the first process that occurs is User Authentication (which BBN plans to upgrade to Connection authentication). User Authentication process checks the requesting username and password parameters pair for validity. The parameters could be sent either over GET or POST method. Upon successful user authentication, the API continues with the rest of the process.

Basic Request:

http://sms.bbnplace.com/bulksms/login.php?username=$username&password=$password

Secure Request:

https://www.bbnplace.com/sms/bulksms/login.php?username=$username&password=$password

Response

This URL will return string true for valid username and password combination or false if either the username or password is incorrect.

 

Checking Balance

To check your account balance over API , BBN SMS Gateway requires user authentication parameters: username and password.

Basic Request

http://sms.bbnplace.com/bulksms/acctbals.php?username=$username&password=$password

Secure Request

https://www.bbnplace.com/sms/bulksms/acctbals.php?username=$username&password=$password

Response

The connection returns a two point float value of the account balance for the requesting account.

 

Sending Text Message

For sending text messages, the BBN SMS Gateway requires to be sent various parameters including username & password for user authentication purposes. All the parameters need to be sent via HTTP protocol using the GET or POST methods.

Basic Request:

http://sms.bbnplace.com/bulksms/bulksms.php?username=$username&password=$password&sender=$sender&message=$text&mobile=$mobiles

Secure Request:

https://www.bbnplace.com/sms/bulksms/bulksms.php?username=$username&password=$password&sender=$sender&message=$text&mobile=$mobiles

New Messaging Interface with DLR Support

http://gateway.sms.bbnplace.com/api/sendtext.php?username=$username&password=$password&appid=$appid&sender=$sender&message=$text&mobile=$mobiles&callback=1

See Table 2.1 for definition of messaging parameters.

Response

The API will return string 1801 if message was successfully sent. See Table 2.2 for the complete list of error reports.

If callback parameter is set to 1 during the messaging api call without specifying messageids, the response will follow the pattern:

responsecode:recipient:messageid|responsecode:recipient:messageid...

Sample
1801:2348xxxxxxxxxx:2d5ec52-4ecde-39f48822ebdfb5f8d69b|1801:2348xxxxxxxxx:7d54ad4-1bff4-a608e4dee8ae9eda6699

 

Scheduling a Message

To schedule sms for later broadcast using the BBN SMS HTTP API, the following additional parameters are required:

Basic Request:

http://sms.bbnplace.com/bulksms/bulksms.php?username=$username&password=$password&sender=$sender&message=$text&mobile=$mobiles&schedule=1&broadcast_time=$broadcast_timestamp&schedule_name=$schedname&schedule_notification=0

Secure Request:

https://www.bbnplace.com/sms/bulksms/bulksms.php?username=$username&password=$password&sender=$sender&message=$text&mobile=$mobiles&schedule=1&broadcast_time=$broadcast_timestamp&schedule_name=$schedname&schedule_notification=0

See Table 2.1 for definition of scheduling parameters

Response


The API will return string 1901 if schedule was successfully saved. See Table 2.2 for the complete list of error reports.

CAUTION:

  • Mobile phone numbers should be prefixed with the destination country code. e.g. Nigeria (234xxxxxxxxxx), Ghana (233xxxxxxxxxx)
  • Multiple mobile phone numbers should be comma delimited. e.g. (234xxxxxxxxxxx,234xxxxxxxxx,….)
  • To avoid breaking or failed message, the total URI length of GET method API connection  must not exceed 1024 characters

 

Delivery Reports

BBN offers two options for retrieving delivery reports DLR. Viz: PUSH and PULL. The suitability of an option depends on the nature of the app you are developing. Web apps are better with PUSH method while desktop apps are better with the PULL method. Reports are forwarded in either of XML, JSON or CSV format.

PUSH

When you setup your app to Require DLR, provide us a dedicated Delivery Report URL and set the callback value to 1 in your messaging parameter you are requesting that we PUSH delivery reports to your app.

PULL

On the other hand, when you setup your app to receive DLR and set callback value to 0 (or omit callback in your messaging parameter), BBN expects you to PULL your delivery report using the gateway's dedicated DLR URL

 

Querying the Delivery Report Interface

If you have configured delivery report for your app, you can use can query the delivery report interface periodically until you receive the final delivery status.

Precision Request Interface:

http://gateway.sms.bbnplace.com/api/dlreport.php?username=$username&password=$password&appid=$appid&messageid=$messageid&format=[xml|json|csv]

For precise request, specify messageid for the recipient you are about to receive. To query for reports of message with multiple id, seperate each message id with a comma

Multi-Report Request Interface:

http://gateway.sms.bbnplace.com/api/dlreport.php?username=$username&password=$password&appid=$appid&format=[xml|json|csv]

To receive reports for a particular app in bulk

 

Delivery Report Formats

The message delivery reports from BBN SMS Gateway interface are delivered in three (3) standard formats: xml, json and csv. Sample report from each format is displayed below:

GET

Your API will receive the following as hit on your server. GET method only applies for PUSH.

http://www.yourdlrdomain.com/dlrpg?messageid=AA19087983438&recipient=2348050209037&status=DELIVERED&done_date=2012/11/23 11:37:58

XML

<reports>
 <report>
  <messageid>AA19087983438</messageid>
  <recipient>2348050209037</recipient>
  <status>DELIVERED</status>
  <doneDate>2012/11/23 11:37:58</doneDate>
 </report>
 ...
</reports>

JSON

{"reports":[{"messageid":"AA23743","recipient":"2836487283","status":"DELIVERED","doneDate":"2012/11/23 11:37:58"},{"messageid":"AA23745","recipient":"2836487289","status":"DELIVERED","doneDate":"123468374"}]}

CSV

Delivery report will for matted in the order messageid,recipient,status,done_date one per line.
AA23743,2836487283,DELIVERED,2012/11/23 11:37:58
AA23744,2836487287,DELIVERED,2012/11/23 11:37:58

 

API Parameters

Parameter Relevance Definition

username

Required

Your BBN username is usually an email

password

Required

Your BBN alphanumeric password

appid

Optional

System generated IP address for the app.

callback

Optional

Set value to 1 to get delivery report forwarded to your app. callback will forward reports to the Delivery Report URL you provided while registering the app

messageid

Optional

If generated by your app, gateway will use your Message ID. If IDs are not provided by your system, Gateway will generate and return message IDs. Require DLR must be set to Yes in App Settings for this feature to work.

sender

Required

A 14 digit number or 11 characters alphanumeric text

message

Required

The content of the text which is targeted at the recipient

mobile

Required

The mobile phone numbers of the recipients. Multiple phone numbers are separated with comma. Each number must be prefixed with the country code.

flash

Optional

Default 0. Set to 1 if you want the message to pop on recipient’s mobile instead of delivering in their inbox

schedule

Optional

Default 0. Set to 1 if you want the message to be scheduled for later delivery

broadcast_time

Optional

Used together with schedule, is the UNIX timestamp value of the date-time when message should be broadcasted. The default time-zone is WAT (GMT +1). Note:  If schedule is not set to 1 when using broadcast_time system will return an error code

schedule_name

Optional

A 16 character alphanumeric name that will be used to uniquely identify the schedule.

schedule_notification

Optional

Default 0. Set to 1 if you want to receive sms notification when scheduled a message has been broadcast.

Table 2.1 – Messaging Parameters

 

API Responses

Responses from BBN SMS Gateway API lets you know, at runtime, the situation report with the API request. Table 2.2 contains a list of API response values and their definitions.

Response Code Definition

1800

Request timeout

1801

Message successfully sent

1802

Invalid username

1803

Incorrect password

1804

Insufficient credit

1805

Invalid url submission

1806

Invalid mobile

1807

Invalid sender id

1808

Message too long

1809

Empty Message

1901

Schedule was successfully saved

1902

Scheduled broadcast time cannot be earlier than current time

1903

Invalid broadcast time

1904

Schedule name is too long. Maximum of 16 alphanumeric characters allowed

1905

Invalid value for notify me. 0 or 1 expected

1906

Incorrect Schedule Name. Schedule name may contain special character

2001

App ID does not exist

2002

Invalid APP Id

2003

IP Lock Violation

3001

Recipient - Message ID mismatch. Number of recipients does not correlate with provided message ids

Table 2.2 - API Response Codes and their definition

 

Delivery Statuses

Status Interpretation

DELIVERED

Recipient has received the message

NOT_DELIVERED

Message could not be terminated to the destination mobile

EXPIRED

Message could not be sent

REJECTED

SMSC refused to teminate the message

ACCEPTED

SMSC has received the message

DELETED

Message has been purged from gateway

Table 2.3 - Delivery Status and their interpretation

 

  • HTTP API Integration Guide

HTTP API Resources

  • Introduction
  • User Authentication
  • Checking Balance
  • Sending Text Message
  • Scheduling a Message
  • API Parameters
  • API Responses
  • Delivery Reports
  • Querying DLR Interface
  • Delivery Report Formats

Technical Support

For integration issues, send the details including how to replicate the fault in an email to lab@bbnplace.com