budgetsms / budgetsms-php
Official PHP client for the BudgetSMS HTTP API: send SMS worldwide, test calls, check credit, number portability and HLR lookups, delivery status and pricing.
Requires
- php: >=7.4
- ext-json: *
Requires (Dev)
None
Suggests
- ext-curl: Used for the HTTP requests when available (falls back to file_get_contents)
Provides
None
Conflicts
None
Replaces
None
README
Official PHP client for the BudgetSMS HTTP API: send SMS to 900+ operators worldwide, test calls without sending, check your credit, look up the network of a number (NP and HLR), fetch delivery statuses and your pricing.
- PHP 7.4 or newer, no dependencies (uses cURL when available,
file_get_contentsotherwise) - One class, typed results, an exception with the API error code
Install
composer require budgetsms/budgetsms-php
Use
use BudgetSMS\Client; use BudgetSMS\ApiException; $sms = new Client('USERNAME', 'USERID', 'HANDLE'); // from the control panel, API details try { $result = $sms->sendSms('31612345678', 'Your verification code is 482913', 'MyCompany'); echo "sent, message id {$result->smsId}, price {$result->price} for {$result->parts} part(s), credit left {$result->credit}\n"; } catch (ApiException $e) { echo $e->getMessage(), "\n"; // "BudgetSMS error 1001: Not enough credit" echo $e->apiCode, "\n"; // "1001" }
While developing, use testSms() with the same arguments. It is a simulator: your credentials are checked and the result has the same shape, but no SMS is sent and nothing is charged, the message id and price are random, and about one in five calls throws a random 2xxx error so you can test your error handling. Real prices come from pricing().
$test = $sms->testSms('31612345678', 'Hello', 'MyCompany'); $credit = $sms->checkCredit(); // 123.455 $network = $sms->np('31612345678'); // current network, also for ported numbers echo $network->mcc, ' ', $network->mnc, ' ', $network->price; $hlr = $sms->hlr('31612345678', 3); // like np, plus reachability; a result up to 3 days old from the cache costs half $status = $sms->dlrStatus($result->smsId); // 1 = delivered, see https://www.budgetsms.net/sms-http-api/dlr-status/ foreach ($sms->pricing() as $operatorId => $row) { echo $row['countryname'], ' ', $row['operatorname'], ' ', $row['price'], "\n"; }
Numbers are written in international format without a leading + or 00: 31612345678. The sender is an alphanumeric name of at most 11 characters or a number of at most 16 digits; some countries require registration of alphanumeric senders, see the country pages on budgetsms.net.
Delivery reports
Prefer Push DLR: enter a URL in the control panel and BudgetSMS calls it (GET) with to, id, status, date and, when you used one, customid on every status change. The URL may contain your own query string. Requests come from 188.240.53.76 (IPv4) or 2a01:7c8:bb04:2c:5054:ff:fe60:d620 (IPv6). dlrStatus() is the pull variant for an occasional check.
Errors
ApiException carries the API error code in $e->apiCode and a readable message. The full list is at https://www.budgetsms.net/sms-http-api/error-code/. Transport problems use the code transport.
License
MIT