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.