Developer API

Profi SMS exposes its sending functionality two ways: an MCP tool (for AI agents/assistants) and a plain PHP service API for use from your own plugin or module code. It also reacts to events from other plugins to trigger sends.

MCP tools

If the yui/mcp plugin is installed, Profi SMS registers one tool:

Tool	Permission	Purpose
profisms_send	write	Send an SMS to one or more phone numbers (comma-separated). The send is logged the same way as any other outgoing message.

profisms_send arguments:

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

message should stay within 160 characters for a single SMS segment.

Events

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

• yui\craft\services\OrdersService::EVENT_AFTER_ORDER_STATUS_CHANGE — sends the message configured for the new order status to the order's shipping phone number, and adds a comment to the order.
• Yui\BookingHub\services\ReservationService::EVENT_AFTER_RESERVATION_REMINDER_SENT — sends the configured reminder message to the reservation's phone number, with placeholder substitution.

Both listeners are only registered when the corresponding setting (sendOnOrderStatusChange, sendOnReservationReminder) is enabled.

PHP service API

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

Sending a message

use Yui\ProfiSms\Plugin;

$success = Plugin::getInstance()
    ->getSms()
    ->sendSms(
        phoneNumber: '+421900123456,+421900654321', // comma-separated for multiple recipients
        message: 'Your order has shipped.',
        options: [], // extra params merged into the profisms.cz API request, e.g. ['senddate' => $dateTime]
    );

Recipient numbers are normalized with an SK (Slovakia) default country prefix before sending — pass numbers in local SK format or already in a recognized international format. If an admin notification number is configured, it's automatically appended to the recipient list.

sendSms() returns true only when the send succeeded (no API error and the log record saved). Every attempt, successful or not, is written to the Profi SMS log via Yui\ProfiSms\records\ProfiSmsRecord.

Looking up configured message text

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

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

Checking the account balance

use Yui\ProfiSms\Plugin;

$balanceInEur = Plugin::getInstance()->getApi()->getBalance();

getApi() returns the ApiService instance, which wraps authenticated requests to the profisms.cz API (sendRequest(string $method, array $data = [])) if you need to call another endpoint directly.

Notes for integrators

• sandbox_mode (settings model property) swaps the configured credentials for profisms.cz's fixed sandbox test account (user / passwd) — useful for CI/staging without touching the real balance.
• The message text sent to the profisms.cz API keeps emoji as-is. Emoji are stripped only from the copy stored in the Profi SMS log record (ProfiSmsRecord::message) after the send, so emoji will still reach the recipient's phone even though the log shows a cleaned version.
• CP routes: profisms/dashboard, profisms/dashboard/save-layout, profisms/settings, profisms/settings/save-settings. License-related routes live under profisms/license/*.
• There is no dedicated log-listing page or public method for querying past messages from PHP; sent/failed data is only surfaced through the CP Dashboard widgets.