DOCUMENT API VERSION 7.3

Path: http://bbnews.com.br/

Objective

The SMS API - Allows to automate the send process of SMS messages individually or in Batch (Multiple SMS ), it allows to consult the real status of each sent message.

We use the JSON format to Involve the parameters in a HTTP/POST request.

Access Credentials

Talk to your account manager to generate de access credentials, You will need a user name and an authentication Key.

It is a HTTP/POST request and you must pass this information in the Header.

Fields Details Type
user Access user name Text
key Acess password provided by your account manager Text

Individual sending of SMS

Allows a single SMS sending:

POST http://bbnews.com.br/bot/single-sms.php  =>  Content-Type: application/json

Request

The request body must contain a JSON object in which the information is enveloped with the following allowed fields:

* Required fields

Fields Details Type
cellphone* Recipient's cell phone containing DDD. Example: 11988887777 Text
message* Message to be sent to mobile. Text
typesms Type of SMS 1 to normal and 2 to flash SMS. Numérico
partnerId Your control id is (optional), since we already generate one identifier per message. Text

Request Examples:

Model 1:
{
	"cellphone":"11988887777",
	"message":"individual sending of sms"
}
				
Model 2:
{
	"cellphone":"11988887777",
	"message":"individual sending of sms",
	"typesms":"2",
	"partnerId":"SeuID"
}
				

Individual Send Response Format

The response body will contain a JSON object with trace information about the sent message:

Fields Details Type
id UUID generate for your SMS message Text
partnerId The same partnerId of your request. Text
JSON response example:
{
	"id":"00400001000080012017032309271099165b3e0e5c1908eabc1109ce0ac7341",
	"partnerId":"msg0001"
}
				

Request example in CURL:

			
curl -X POST \
  http://bbnews.com.br/bot/single-sms.php \
  -H 'key: key' \
  -H 'user: user' \
  -H 'content-type: application/json' \
  -d '{"cellphone": "11988887777" , "message": "linha\nquebrada"}'

Request example in PHP:

		

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://bbnews.com.br/bot/single-sms.php",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"cellphone\": \"11988887777\" , \"message\": \"linha\\nquebrada\"}",
  CURLOPT_HTTPHEADER => array(
    "key: key",
    "user: user",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

BulkSMS sending

Allows sending multiple SMS

There is a limit of 5000 SMS messages per request.

POST http://bbnews.com.br/bot/bulk-sms.php  =>  Content-Type: application/json

Request

The request body must contain a JSON object in which the information is enveloped with the following allowed fields:

* Required fields

Fields Details Type
bulk* Array of messages to be sent to the respective recipients, the same configuration as the individual sending of sms. bulk[]

BulkSMS request examples:

Model 1:
{
	"bulk":[
		{
			"cellphone":"11988887776",
			"message":"individual sms sending 001"
		},
		{
			"cellphone":"11988887777",
			"typesms":"2",
			"message":"individual sms sending 002"
		}
	]
}
				
Model 2:
{
	"bulk":[
		{
			"cellphone":"11988887776",
			"message":"individual sms sending 001",
			"partnerId":"msg001"
		},
		{
			"cellphone":"11988887777",
			"typesms":"1",
			"message":"individual sms sending 002",
			"partnerId":"msg002"
		},
		{
			"cellphone":"11988887778",
			"typesms":"2",
			"message":"individual sms sending 003",
			"partnerId":"msg003"
		}
	]
}
				

Bulk SMS Requests responses

The response body will contain a JSON object with trace information about the sent message:

Fields Details Types
id UUID generated for the submitted batch. Text
bulk This field is an array of unique SMS responses, each data contains an id and an associated ID of the sent messages. UnitSMSRespostas[]

Example Json response object:


{
	"id":"00400001000080012017032309271099165b3e0e5c1908eabc1109ce0ac7340",
	"bulk":[
		{
			"id":"00400001000080012017032309271099165b3e0e5c1908eabc1109ce0ac7341",
			"partnerId":"myid1"
		},
		{
			"id":"00400001000080012017032309271099165b3e0e5c1908eabc1109ce0ac7342",
			"partnerId":"myid2"
		}
	]
}
				

Request example in CURL:

			
curl --request POST \
  --url http://bbnews.com.br/bot/bulk-sms.php \
  --header 'user: user' \
  --header 'key: key' \
  --header 'content-type: application/json' \
  --data '{"bulk":[{"cellphone":"11988887777", "message":"message 1" }, {"cellphone":"11988887777", "message":"message 2" }, {"cellphone":"11988887777", "message":"message 3" }]}'

Request example in PHP:

		
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://bbnews.com.br/bot/bulk-sms.php",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{ \"bulk\":[{ \"cellphone\":\"11988887777\", \"message\":\"message 1\" }, { \"cellphone\":\"11988887777\", \"message\":\"message 2\" }, { \"cellphone\":\"11988887777\", \"message\":\"message 3\" }]}",
  CURLOPT_HTTPHEADER => array(
    "key: key",
    "content-type: application/json",
    "user: user"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Details of carrier

statusCarrier statusDetails Explanation
2 SCHEDULED The message is scheduled for later sending.
2 ENROUTE The message is enroute.
2 SENT The message was sent to carrier.
3 REJECTED The message was rejected to carrier.
3 UNKNOWN Unknown error to send message.

Details of confirmation

statusConfirmation confirmationDetails Explanation
4 DELIVERED The message was successfully delivered.
4 CARRIER_WAITING The message is waiting to sent to mobile by carrier.
5 UNDELIVERABLE The message was unable to delivered.

Others errors of requests.

status statusDetails Explanation
101 Authentication Error Probably the header with user and key was not sent or the credentials are not valid!
303 Request Error The request parameters are incorrect or have not been sent!
303 Request Error bulk Bulk greater than 5000 messages!
404 Transaction not found The id of the transaction was not found!
505 Insufficient funds Your account has no limit to meet the requisition!