Documentation /
HTTP API Integration Guide

Introduction

This documentation is intended for developers’ use only and contains technical terms which will be better interpreted by the target users.

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

Document History:

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

Most Recent Modifications:

Sub-domain: Former gateway.sms.bbnplace.com is now smsgateway.bbnplace.com

Basic API:

Secure API:

 

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:

Secure Request:

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

Secure Request

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:

Secure Request:

New Messaging Interface with DLR Support

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:

 

Scheduling a Message

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

Basic Request:

Secure Request:

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:

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:

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.

XML

JSON

CSV

Delivery report will for matted in the order messageid,recipient,status,done_date one per line.

 

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

 

Technical Support