Adding incoming SMS features to Gateway plugins

The page outlines how to add feature to your gateway plugin in order for your site to handle SMS messages sent by mobile clients to your site. Unlike the send method, adding incoming functionality is optional.

Create a plugin #

Create a gateway plugin. Add plugin annotation properties 'incoming' and 'incoming_route' both with values of TRUE.

Example:

/**
 * @SmsGateway(
 *   [...]
 *   incoming = TRUE,
 *   incoming_route = TRUE,
 * )

Add incoming request method to plugin #

Create a processIncoming method in your gateway plugin. The method is a controller callback, so you are free to choose the arguments you like.

public function processIncoming() {}

Some common arguments to add are for the current request and the gateway the route is responding to:

public function processIncoming(\Symfony\Component\HttpFoundation\Request $request, \Drupal\sms\Entity\SmsGatewayInterface $sms_gateway) {
}

Transform request into message objects #

It is then your task to verify, validate, and transform the incoming request data into SMS messages. In the end you should be constructing your own SmsMessage objects. A message is created with:

$message = \Drupal\sms\Entity\SmsMessage::create();

The following properties must be set on a SmsMessage object in order to be considered valid by the queuing system.

$message 
  ->setDirection(\Drupal\sms\Direction::INCOMING)
  ->setMessage('The incoming message')
  ->addRecipients(['+123456789']); // A phone number, usually one representing the site.
  ->setGateway($sms_gateway);

Result and reports #

A result must be attached to each message. And a report for each recipient must be created for each recipient of the message.

$result = new \Drupal\sms\Message\SmsMessageResult()
$report = (new \Drupal\sms\Message\SmsDeliveryReport())
  ->setRecipient('+123456789')
  ->setStatus(\Drupal\sms\Message\SmsMessageReportStatus::CODE)
  ->setMessageId('abc-def-ghi-jkl'); // An optional unique message ID.
$result->addReport($report);
$message->setResult($result);

Report status codes can be found in the report codes documentation.

Return object #

The processIncoming method must return a \Drupal\sms\SmsProcessingResponse object. This object contains the incoming messages that were found in the HTTP request, and the response to return to the calling HTTP request.

function processIncoming() {
  // Create some messages out of the HTTP request.
  $messages = [];

  // ...
  // Create some messages here. See section "Transform request into message objects" above.

  $response = new \Symfony\Component\HttpFoundation\Response('', 204)
  $task = (new \Drupal\sms\SmsProcessingResponse())
    ->setResponse($response)
    ->setMessages($messages);
  return $task;
}