Skip to main content
Version: main (4.5)

SMS API

Since 4.5

The SMS API lets you send SMS messages using configured gateways, fetch messages that were previously sent, and check on their status.

Sending an SMS​

Messages can be sent using the send() method of the SMS Manager class, which should be fetched using Dependency Injection, for example:

Sending a message
$message = \core\di::get(\core_sms\manager::class)
    ->send(
        recipientnumber: '+61987654321',
        content: 'This is the content of the message',
        component: 'mod_example',
        messagetype: 'demonstrationmessage',
        recipientuserid: $user->id,
        issensitive: false,
        async: false,
    );
Message lengths

A single SMS sent by the API may consist of up to 480 UTF-8 characters. It is up to the message gateway plugin to determine how this message is sent to the recipient.

Any message longer than the maximum length will be immediately rejected.

Sending messages containing sensitive information​

When sending a message containing something like a 2FA login token, you should make use of the issensitive flag.

Passing this flag prevents the SMS subsystem from storing the content of the message in the message log.

The send() method return an instance of \core_sms\message which can be used to check on the message status.

Fetching messages​

Every sent message is stored in the database for subsequent reporting, and to check statuses.

Messages can be fetched from the database by calling the \core_sms\manager::get_message() and \core_sms\manager::get_messages() methods and supplying a filter.

Fetching messages
$message = \core\di::get(\core_sms\manager::class)
    ->get_message(['id' => $id]);

$messages = \core\di::get(\core_sms\manager::class)
    ->get_messages(['recipientuserid' => $userid]);
Sensitive content

If the message was sent with the issensitive flag the message body will not be stored.

Checking the status of a message​

Once a message is sent, a status is recorded against it. This can be used to determine whether the message was sent successfully.

info

The level of status information available will depend on individual message gateways and recipient regions. In some regions delivery status may be available, but not in others.

Message status can be checked using the \core_sms\message::$status property.

Statuses are represented by a PHP Enum object with each status having a translatable description, and methods to determine whether the message was sent, is failed, or still in-progress.

Checking the status of a message
$message = \core\di::get(\core_sms\manager::class)
    ->get_message(['id' => $id]);

// Check if the message is failed.
$message->is_failed();

// Check if the message is still in transit.
$message->is_in_progress();

// Check if the message is sent.
$message->is_sent();

// Get the description of the state.
$message->description();