Send SMS with PHP
Plain PHP, no libraries: one small function that calls any endpoint of the API, checks the OK or ERR answer and gives you the result. Works with PHP 7.4 and newer.
Official client
Prefer a ready-made client? The official package budgetsms/budgetsms-php (PHP 7.4 or newer, no dependencies, MIT) wraps every call in one class and throws an exception that carries the API error code:
composer require budgetsms/budgetsms-php
use BudgetSMS\Client;
$sms = new Client('USERNAME', 'USERID', 'HANDLE');
$result = $sms->sendSms('31612345678', 'Your verification code is 482913', 'MyCompany');
echo $result->smsId, ' ', $result->price, ' ', $result->credit;
The rest of this page shows how the API works without any library.
The helper
<?php
// budgetsms.php - keep the credentials out of your code, for example in environment variables
const BUDGETSMS = ['username' => 'USERNAME', 'userid' => 'USERID', 'handle' => 'HANDLE'];
/**
* Calls an endpoint of the BudgetSMS HTTP API (sendsms, testsms, checkcredit, np, hlr, checksms, getpricing).
* Returns the text after "OK " (for getpricing the raw JSON); throws on "ERR <code>" or a network problem.
*/
function budgetsms(string $call, array $params = []): string
{
$url = 'https://api.budgetsms.net/' . $call . '/?' . http_build_query(BUDGETSMS + $params);
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 20]);
$body = curl_exec($ch);
if ($body === false) {
throw new RuntimeException('BudgetSMS unreachable: ' . curl_error($ch));
}
$body = trim((string) $body);
if ($call === 'getpricing') {
return $body;
}
if (strpos($body, 'OK') !== 0) {
throw new RuntimeException('BudgetSMS error ' . $body); // for example "ERR 1001": see the error code list
}
return trim(substr($body, 2));
}
Send an SMS
<?php
require 'budgetsms.php';
try {
$result = budgetsms('sendsms', ['from' => 'BudgetSMS', 'to' => '31612345678', 'msg' => 'Hello from BudgetSMS']);
$smsId = (int) strtok($result, ' '); // "64354593" - keep it for the delivery report
echo "Sent, message id $smsId\n";
} catch (RuntimeException $e) {
echo $e->getMessage(), "\n";
}
Use testsms instead of sendsms while developing: same parameters and answer format, but it is a simulator: no SMS is sent and nothing is charged, the message id and price in the answer are random, and about one in five calls returns a random ERR 2xxx so your error handling gets exercised (the destination number is not checked). Add 'price' => 1 to get the price and the number of parts back, 'mccmnc' => 1 for the network of the receiver and 'credit' => 1 for your remaining credit; the values follow the message id, separated by spaces.
Credit, number lookup and delivery status
<?php
$credit = (float) budgetsms('checkcredit'); // 123.455
[$mcc, $mnc, $price] = explode(' ', budgetsms('np', ['to' => '31612345678'])); // "204", "08", "0.0640"
$status = (int) budgetsms('checksms', ['smsid' => 64354593]); // 1 = delivered, see the DLR status list
$pricing = json_decode(budgetsms('getpricing'), true); // operator id => [countryname, operatorname, mcc, mnc, price, ...]
Receive delivery reports (Push DLR)
Enter the URL of this script in the control panel under Push DLR. We call it with GET on every status update of a message you sent.
<?php
// dlr.php - the URL you enter in the control panel, for example https://example.com/dlr.php
$smsId = (int) ($_GET['id'] ?? 0); // the message id from the sendsms response
$status = (int) ($_GET['status'] ?? -1); // 1 = delivered, 2 and 3 = failed, 0 = no status yet; full list: DLR status
$date = (int) ($_GET['date'] ?? 0); // unix timestamp of the status
// update your own records here, for example:
// $pdo->prepare('UPDATE sms SET status = ?, status_at = ? WHERE sms_id = ?')->execute([$status, date('Y-m-d H:i:s', $date), $smsId]);
http_response_code(200);
echo 'OK';
Answer with HTTP 200 quickly and do any heavy work afterwards; if your server does not answer, the report is retried later.