Developer API

SMS Brana exposes its sending and reporting functionality three ways: MCP tools (for AI agents/assistants), Craft/Yii events (to react to sends or add new send triggers), and a plain PHP service API for use from your own plugin or module code.

MCP tools

If the yui/mcp plugin is installed, SMS Brana registers three tools:

Tool	Permission	Purpose
sms_send	write	Send an SMS to one or more phone numbers (comma-separated). Logged with source mcp.
sms_get_stats	—	Get total/success/failed/today counts and success rate. Optionally include a daily breakdown for up to 31 days.
sms_list_messages	—	List logged messages, filterable by status, q (text/number search), number, from/to date range, and source.

sms_send arguments:

{
  "phone_number": "+421900123456",
  "message": "Your order has shipped."
}

sms_get_stats arguments (all optional):

{ "days": 7 }

sms_list_messages arguments (all optional):

{
  "limit": 50,
  "status": 1,
  "source": "order-status",
  "from": "2026-07-01",
  "to": "2026-07-28"
}

sms_list_messages returns a count plus messages. Each message includes id, number, message, status, source, and dateCreated.

Events

SMS Brana listens for these events from other plugins to trigger sends — you don't subscribe to SMS Brana events yourself, but you can reuse the same pattern to add a new trigger:

• yui\craft\services\CheckoutService::EVENT_AFTER_PURCHASE_SUCCESS — sends the "pending" order status message right after checkout.
• yui\craft\services\OrdersService::EVENT_AFTER_ORDER_STATUS_CHANGE — sends the message configured for the new order status.
• Yui\BookingHub\services\ReservationService::EVENT_AFTER_RESERVATION_REMINDER_SENT — sends the configured reminder message, with placeholder substitution.

These listeners are only registered when the corresponding setting (sendOnOrderStatusChange, sendOnReservationReminder) is enabled, and (for order status) only when yui/craft is installed.

When an order-status send succeeds or fails at provider level, SMS Brana still writes the order comment saying an SMS was sent, because the comment records that the notification flow ran for that order. Use the SMS Brana log status to check the provider outcome.

PHP service API

Use Yui\SmsBrana\Plugin::getInstance()->getSms() to get the SmsBranaService instance.

Sending a message

use Yui\SmsBrana\Plugin;
use Yui\SmsBrana\services\SmsBranaService;

$success = Plugin::getInstance()
    ->getSms()
    ->sendSms(
        phoneNumber: '+421900123456,+421900654321', // comma-separated for multiple recipients
        message: 'Your order has shipped.',
        options: [],
        source: SmsBranaService::SOURCE_SYSTEM,
        sendAt: null, // optional \DateTimeInterface, see below
    );

The log row is only created once the API actually responds. If globalPause is on, or the request never gets a response (client/credentials setup failure, or an exception), sendSms() returns false without an exception and no log row is written. Once a response comes back, both a successful send and an API-reported error are logged.

sendSms() takes an optional sendAt parameter (\DateTimeInterface|null, default null). When given, the message is not sent immediately — it's queued for delayed delivery through SmsConnect's bulk queue API instead of the normal immediate-send endpoint:

$success = Plugin::getInstance()
    ->getSms()
    ->sendSms(
        phoneNumber: '+421900123456',
        message: 'Reminder: your appointment is tomorrow.',
        options: [],
        source: SmsBranaService::SOURCE_SYSTEM,
        sendAt: new \DateTime('+1 day'),
    );

The log entry's success message reflects the scheduled time ("SMS was scheduled for ...") rather than an immediate-send confirmation. This is the same mechanism used by the CP settings page's manual test-send form when a future date/time is set.

Built-in source constants: SOURCE_SYSTEM, SOURCE_MANUAL_TEST, SOURCE_ORDER_STATUS, SOURCE_RESERVATION_REMINDER, SOURCE_MCP. Unknown source strings are normalized to system, so use one of these constants if you want dashboard filters and MCP results to group messages predictably.

Reading logged messages and stats

$sms = Plugin::getInstance()->getSms();

$sms->getDashboardStats();        // ['totalCount', 'successCount', 'failedCount', 'todayCount', 'successRate']
$sms->getDailyStats(7);           // daily breakdown for the last N days
$sms->getRecentMessages(20);      // last 20 SmsBranaRecord rows
$sms->getMessages([
    'status' => 1,
    'source' => 'order-status',
    'from' => '2026-07-01',
    'to' => '2026-07-28',
], 200);                          // filtered SmsBranaRecord[] (max 200 by default)
$sms->getAvailableSources();      // known + actually-used source strings, for filter dropdowns

getMessages() orders newest first. CP logs call it with a limit of 500, CSV export with 5000, and the MCP list tool defaults to 20 with a maximum of 200.

Looking up configured message text

$sms->getOrderStatusMessage('shipped', $siteId);      // returns the configured text or null
$sms->getBookingReminderMessage('event', true);       // true = randomize placeholder values (useful for previews)

Notes for integrators

• Phone numbers are normalized with a SK default country prefix before sending; pass numbers in local SK format or already E.164-formatted.
• sandboxMode swaps the configured credentials for SmsConnect's fixed sandbox test account (user / passwd) — useful for CI/staging without a real balance.
• CP routes: smsbrana/dashboard, smsbrana/logs, smsbrana/logs/export, smsbrana/settings. License-related routes live under smsbrana/license/*.
• Provider error codes are mapped to human-readable activity log messages for common cases such as invalid credentials, disallowed remote IP, no credit, invalid recipient number, empty text, and text that is too long.
• This page is based on SMS Brana v1.6.0, the latest stable release tag checked for this documentation update.