This repository contains the open source PHP client for BSG's REST API. With this API, you can send both single SMS and bulk SMS messages, Viber messages, and verify phone numbers by sending HLR requests. The API is free to use, there are no connection fees or monthly payments. You only pay for the messages sent on a Pay-as-you-Go basis.
Prices for sending messages can be found here: Prices
- Sign up for a free account
- Get api key here
- Go through the API documentation
Download and use files from "src" directory. No installation needed. Composer used only for phpunit tests.
Bsg class provide access to the hlr/sms/viber clients
Parameters
apiKey (string) Api key from bsg.world. Required.
sender (string) Sender name for sms
viberSender (string) Sender name for viber (alpha name)
tariff (int) Tariff that should be used for this session
api source (string) Name of your application (not required)
$apiKey = 'test_8zWaPwOaHDPRFmgIldhl'
$bsg = new BSG($apiKey, 'originator', 'aplhaname', 3, 'Bitrix-24')
BSG provides an API to get the balance information of your account.
$apikey = 'test_8zWaPwOaHDPRFmgIldhl';
$api = new BSG($apikey);
$client = $api->getSmsClient(); //get one of the clients
$balance = $client->getBalance();
$balance = array(5) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["amount"]=>
string(10) "-4.0999333"
["currency"]=>
string(3) "EUR"
["limit"]=>
string(1) "7"
}
Number Lookup helps you keep your mobile numbers database up to date.
Mobile subscribers often change numbers, go into roaming and change providers while retaining their original phone number. Knowing which mobile numbers are in use and available, or which network your client is currently using can greatly improve accuracy and cost effectiveness for many types of businesses. With Number Lookup, you can determine:
- which numbers are currently active
- is the mobile number in roaming
- is the mobile number ported
Parameters
msisdn (int) The telephone number. Required.
reference (string) A client reference. Required.
tariff (int) Tariff code of a price grid. Use value from BSG class if it empty. Use default value from bsg cabinet if it wasn't set at all
$hlr = $bsg->getHLRClient();
$responce = $hlr->sendHLR('+380501111111', (string)time());
Example response:
$response = array(3) {
["result"]=>
array(1) {
[0]=>
array(9) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["msisdn"]=>
string(12) "380501111111"
["reference"]=>
string(10) "1488536778"
["tariff_code"]=>
string(1) "0"
["callback_url"]=>
string(0) ""
["price"]=>
float(0.0025)
["currency"]=>
string(3) "EUR"
["id"]=>
string(6) "174568"
}
}
["total_price"]=>
float(0.0025)
["currency"]=>
string(3) "EUR"
}
Send multiple hlr queries in one time.
Exaple:
$response = $hlr->sendHLRS(
[
[
"msisdn"=>"380501111111", //required
"reference"=>"extid1", //required
"tariff"=>"0",
],
[
"msisdn"=>"380501111112",
"reference"=>"extid2",
"tariff"=>"0",
]
]
)
Example response:
$response = {array(3) {
["result"]=>
array(2) {
[0]=>
array(8) {
["error"]=>
int(0)
["msisdn"]=>
string(12) "380501111111"
["reference"]=>
string(14) "extid1"
["tariff_code"]=>
string(1) "0"
["callback_url"]=>
string(0) ""
["price"]=>
float(0.0025)
["currency"]=>
string(3) "EUR"
["id"]=>
string(6) "174573"
}
[1]=>
array(8) {
["error"]=>
int(0)
["msisdn"]=>
string(12) "380501111112"
["reference"]=>
string(14) "extid2"
["tariff_code"]=>
string(1) "0"
["callback_url"]=>
string(0) ""
["price"]=>
float(0.0025)
["currency"]=>
string(3) "EUR"
["id"]=>
string(6) "174574"
}
}
["total_price"]=>
float(0.005)
["currency"]=>
string(3) "EUR"
}
Retrieves the information of an existing HLR. You only need to supply the unique message reference that was set upon creation.
$response = $hlr->getStatusByReference('ref1);
Example response:
$response = array(14) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["name_ru"]=>
string(14) "Украина"
["name_en"]=>
string(7) "Ukraine"
["brand"]=>
string(3) "MTS"
["name"]=>
string(11) "MTS Ukraine"
["msisdn"]=>
string(12) "380501111111"
["id"]=>
string(12) "380501111111"
["reference"]=>
string(12) "su1488546296"
["network"]=>
string(5) "25501"
["status"]=>
string(6) "failed"
["details"]=>
NULL
["createdDatetime"]=>
string(25) "2017-03-03T13:04:56+00:00"
["statusDatetime"]=>
string(25) "2017-03-03T13:04:56+00:00"
}
Retrieves the information of an existing HLR. You only need to supply the unique message id that was returned upon creation or receiving.
Example:
$response = $hlr->getStatusById('1);
Example response:
$response = array(14) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["name_ru"]=>
string(14) "Украина"
["name_en"]=>
string(7) "Ukraine"
["brand"]=>
string(3) "MTS"
["name"]=>
string(11) "MTS Ukraine"
["msisdn"]=>
string(12) "380501111111"
["id"]=>
string(12) "380501111111"
["reference"]=>
string(12) "su1488546296"
["network"]=>
string(5) "25501"
["status"]=>
string(6) "failed"
["details"]=>
NULL
["createdDatetime"]=>
string(25) "2017-03-03T13:04:56+00:00"
["statusDatetime"]=>
string(25) "2017-03-03T13:04:56+00:00"
}
BSG provides an API to send SMS messages to any country across the world.
BSG are identified by a unique random ID. And with this ID you can always check the status of the message through the provided endpoint.
Creates a new message object. BSG returns the created message object with each request. Per request, a max of 50 phones can be entered.
Parameters
msisdn (string) The telephone number. Required
body (string) The body of the SMS message. Required
reference (string) A client reference. Required
validity (int) The amount of seconds that the message is valid.
tariff (int) Tariff code of a price grid.
originator (string) The sender of the message. This can be a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters. Uses value from BSG if it was set. In all other cases - required
$smsClient = $BSG->getSmsClient();
$smsClient->sendSms(
'380501111111',
'test',
'successSend' . (string)time()
);
$smsclient->$answer = $this->smsClient->sendSmsMulti([
['msisdn' => 380501111111, 'body' =>'test', 'reference' => 'successSendM' . (string)time()],
['msisdn' => 380501111112, 'body' =>'tes2', 'reference' => 'successSendM1' . (string)time()],
]);
Example response:
$answer = array(3) {
["result"]=>
array(2) {
[0]=>
array(6) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["reference"]=>
string(22) "successSendM1488547867"
["id"]=>
string(6) "174584"
["price"]=>
float(0.1)
["currency"]=>
string(3) "EUR"
}
[1]=>
array(6) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["reference"]=>
string(23) "successSendM11488547867"
["id"]=>
string(6) "174585"
["price"]=>
float(0.1)
["currency"]=>
string(3) "EUR"
}
}
["total_price"]=>
float(0.2)
["currency"]=>
string(3) "EUR"
}
$response = $smsClient->getStatusById(214);
$response = $smsClient->getStatusByReference(ref1);
$response = $smsClient->getTaskStatus(214);
Example response:
array(11) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["id"]=>
string(12) "380501111111"
["msisdn"]=>
string(12) "380501111111"
["reference"]=>
string(21) "successSend1488548141"
["time_in"]=>
string(19) "2017-03-03 13:35:42"
["time_sent"]=>
string(19) "2017-03-03 13:35:42"
["time_dr"]=>
string(19) "2017-03-03 13:35:42"
["status"]=>
string(7) "unknown"
["price"]=>
int(0)
["currency"]=>
string(3) "EUR"
}
###TASK SMS RESPONSE
array(10) {
["originator"]=>
string(4) "name"
["body"]=>
string(4) "body"
["validity"]=>
int(72)
["totalprice"]=>
float(0.1)
["currency"]=>
string(3) "EUR"
["sent"]=>
int(1)
["delivered"]=>
int(1)
["expired"]=>
int(0)
["undeliverable"]=>
int(0)
["unknown"]=>
int(0)
}
VIBER provides an API to send VIBER messages to any country across the world.
BSG are identified by a unique random ID. And with this ID you can always check the status of the message through the provided endpoint.
Add a VIBER message into queue
Parameters
to (array) The array of recipients msisdn's & reference's. Required
messages (string) Viber message. Required.
options: (hash) An hash with VIBER options.
alpha_name (string) The sender of the message. Uses the value of "viber sender name" from BSG class if not setted. Required if it is empty
is_promotional (bool) Set is this message promotional. Default is true
callback_url (string) Link for delivery reports. Reference id is required in message arrray
$viberClient = $bsg->getViberClient();
$response = $viberClient->addMessage([['msisdn' => 380501111111]], 'test');
Add image and link to the message:
$viberClient->addMessage([['msisdn' => msisdn' => 380501111111]], 'test', [
"img" => "http://my-cool-webpage.com/logo.png",
"caption" => "Join us!",
"action" => "http://my-cool-webpage.com"
]);
Return: Void
Send all messages from queue
Parameters
validity (int) The amount of seconds that the message is valid.
tariff (int) Tariff code of a price grid.
$viberClient = $bsg->sendMessages();
Example of response:
$response = array(3) {
["result"]=>
array(1) {
[0]=>
array(5) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["id"]=>
string(6) "174592"
["price"]=>
int(0)
["currency"]=>
string(3) "EUR"
}
}
["currency"]=>
string(3) "EUR"
["total_price"]=>
int(0)
}
Retrieves the information of an existing message. This message can be a sent or a received message. You only need to supply the unique message id that was returned upon creation or receiving.
$response = $viberClient->getStatusById(216);
or by reference
$response = $api->getStatusByReference("ext_id_19");
Example response:
$response = array(11) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["id"]=>
string(12) "380501111111"
["msisdn"]=>
string(12) "380501111111"
["reference"]=>
string(25) "38050111111158b977704621d"
["time_in"]=>
string(19) "2017-03-03 14:02:24"
["time_sent"]=>
string(19) "2017-03-03 14:02:24"
["time_dr"]=>
string(19) "2017-03-03 14:02:24"
["status"]=>
string(7) "expired"
["price"]=>
int(0)
["currency"]=>
string(3) "EUR"
}
BSG provides an API to get the price information of your account.
Return chosen tariff prices
Parameters
tariff (int) The type of message campaign
$response = $hlrClient->getPrices();
$response = $smsClient->getPrices();
$response = $viberClient->getPrices();
Example response:
$response = array(3) {
["error"]=>
int(0)
["errorDescription"]=>
string(9) "No errors"
["prices"]=>
array(191) {
[0]=>
array(6) {
["type"]=>
string(3) "hlr"
["country"]=>
string(0) ""
["country_name"]=>
string(15) "Other countries"
["mcc"]=>
string(0) ""
["price"]=>
string(9) "0.0034000"
["currency"]=>
string(3) "EUR"
}
[1]=>
array(6) {
["type"]=>
string(3) "hlr"
["country"]=>
string(2) "AB"
["country_name"]=>
string(8) "Abkhazia"
["mcc"]=>
string(3) "289"
["price"]=>
string(9) "0.0050000"
["currency"]=>
string(3) "EUR"
}
[2]=>
array(6) {
["type"]=>
string(3) "hlr"
["country"]=>
string(2) "AD"
["country_name"]=>
string(7) "Andorra"
["mcc"]=>
string(3) "213"
["price"]=>
string(9) "0.0025000"
["currency"]=>
string(3) "EUR"
}
}
}
###Tests
This sdk also contain phpunit tests with for all functions our API (with checking errors). To start them, check "/tests/TestConfig.php" and change value of api key, sender name and viber sender name. After that, just use:
$ phpunit -c tests/