You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
SMS gateway plugins allow you to create SMS gateway providers.
12
+
Providers are an interface between the [SMS API](/apis/subsystems/sms/index.md) and an external SMS provider (for example Amazon Web Services).
13
+
This allows for the sending of SMS notifications to users from your Moodle instance.
14
+
15
+
:::info Example
16
+
17
+
You can set up Multi-Factor Authentication (MFA)) in Moodle and choose 'AWS' as your SMS gateway provider.
18
+
19
+
This enables users to receive SMS notifications as part of the authentication process.
20
+
21
+
:::
22
+
23
+
## File structure
24
+
25
+
SMS gateway plugins are located in the `/sms/gateway` directory. A plugin should not include any custom files outside its own plugin folder.
26
+
27
+
Each plugin is placed in a separate subdirectory and consists of a number of mandatory files and any other files the developer is going to use. See the [common plugin files](/apis/commonfiles/index.mdx) documentation for other files which may be useful in your plugin.
28
+
29
+
<details>
30
+
<summary>The directory layout for the `smsgateway` plugin.</summary>
31
+
32
+
```console
33
+
sms/gateway/example
34
+
├── classes
35
+
│ ├── gateway.php
36
+
│ ├── hook_listener.php
37
+
│ └── privacy
38
+
│ └── provider.php
39
+
├── db
40
+
│ └── hooks.php
41
+
├── lang
42
+
│ └── en
43
+
│ └── smsgateway_example.php
44
+
├── settings.php
45
+
└── version.php
46
+
```
47
+
48
+
</details>
49
+
50
+
## Key files
51
+
52
+
There are a number of key files within the SMS gateway plugin which will need to be configured for correct functionality.
53
+
54
+
-`gateway.php`
55
+
-`hook_listener.php`
56
+
57
+
### gateway.php
58
+
59
+
Each plugin must create a class called `gateway` which extends the `\core_sms\gateway` class.
60
+
The SMS API will use the extended methods from this class.
61
+
62
+
```php title="Implementing the base SMS gateway"
63
+
<?php
64
+
namespace smsgateway_aws;
65
+
66
+
use smsgateway_aws\local\service\aws_sns;
67
+
68
+
class gateway extends \core_sms\gateway {
69
+
#[\Override]
70
+
public function send(
71
+
message $message,
72
+
): message {
73
+
// Sample code to send an SMS message.
74
+
$config = (object) json_decode(
75
+
$awsconfig,
76
+
true,
77
+
512,
78
+
JSON_THROW_ON_ERROR,
79
+
);
80
+
$class = $this->get_gateway_service($config);
81
+
$recipientnumber = manager::format_number(
82
+
phonenumber: $message->recipientnumber,
83
+
countrycode: isset($config->countrycode) ?? null,
84
+
);
85
+
86
+
$status = call_user_func(
87
+
[$class, 'send_sms_message'],
88
+
$message->content,
89
+
$recipientnumber,
90
+
$config,
91
+
);
92
+
93
+
return $message->with(
94
+
status: $status,
95
+
);
96
+
}
97
+
98
+
private function get_gateway_service(\stdClass $config): string {
99
+
return match ($config->gateway) {
100
+
'aws_sns' => aws_sns::class,
101
+
default => throw new moodle_exception("Unknown Message Handler {$config->gateway}"),
102
+
};
103
+
}
104
+
105
+
#[\Override]
106
+
public function get_send_priority(message $message): int {
107
+
return 50;
108
+
}
109
+
}
110
+
111
+
```
112
+
113
+
### hook_listener.php
114
+
115
+
[Hooks](/apis/core/hooks/index.md) can be dispatched from the SMS API which the plugin can then listened to.
116
+
It is necessary for plugins developers to assess these hooks and implement accordingly.
117
+
118
+
#### after_sms_gateway_form_hook
119
+
120
+
This hook will allow plugins to add required form fields to assist users in configuring their SMS gateway.
121
+
122
+
```php title="Listener method for after_sms_gateway_form_hook"
123
+
public static function set_form_definition_for_aws_sms_gateway(after_sms_gateway_form_hook $hook): void {
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.
42
+
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.
29
43
30
44
Any message longer than the maximum length will be immediately rejected.
31
45
32
46
:::
33
47
48
+
### Parameter consideration while sending messages
49
+
50
+
When sending a message it's important to add the correct `component` (for example `tool_mfa`) and `messagetype` (for example `mfa code`) for record keeping purposes.
51
+
52
+
One component can have many different types of messages and those types should be clearly mentioned while sending the messages so that they are clear in reporting and other locations.
53
+
54
+
:::info
55
+
56
+
In future reporting will be available for messages status. See MDL-80963 for further information
57
+
58
+
:::
59
+
34
60
### Sending messages containing sensitive information
35
61
36
62
When sending a message containing something like a 2FA login token, you should make use of the `issensitive` flag.
@@ -39,9 +65,25 @@ Passing this flag prevents the SMS subsystem from storing the content of the mes
39
65
40
66
The `send()` method return an instance of `\core_sms\message` which can be used to check on the message status.
41
67
68
+
:::warning
69
+
70
+
Messages containing sensitive information cannot be sent asynchronously.
71
+
72
+
Sensitive content is not persisted to the database and is therefore not available in a separate PHP process.
73
+
74
+
:::
75
+
76
+
:::info Availability of asynchronous message handling
77
+
78
+
The ability to send messages asynchronously has not yet been implemented. The parameter is included for future compatibility.
79
+
80
+
See MDL-81015 for more information on this feature.
81
+
82
+
:::
83
+
42
84
## Fetching messages
43
85
44
-
Every sent message is stored in the database for subsequent reporting, and to check statuses.
86
+
Every sent message is stored in the database to support status checks, and for subsequent reporting.
45
87
46
88
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.
47
89
@@ -122,3 +164,47 @@ graph TD
122
164
GQ --> |Gateway failed to send the message| GF
123
165
end
124
166
```
167
+
168
+
## Getting SMS gateways
169
+
170
+
[SMS gateways](/apis/plugintypes/sms/index.md) are plugins that provide a way to interface with external SMS providers.
171
+
Once a gateway is configured, any component implementing the SMS API can get a list of gateways.
172
+
173
+
```php title="Getting the list of enabled gateways"
0 commit comments