Delivery receipts from gateways

So, this would define a common set of status codes. The integers in the below code would be better for identifying ranges:

/**
 * Callback for incoming message receipts. Allows gateways modules to pass
 * message receipts in a standard format for processing, and provides a cut-down
 * set of status codes for common code handling.
 *
 * Allowed status codes. The receipt receiver function must map the gateway
 * status to one of these codes. The idea of numbering is so that you can match
 * all statuses above or below a certain integer.
 * <ul>
 *   <li>1 - Delivered</li>
 *   <li>2 - Queued</li>
 *   <li>11 - Invalid message</li>
 *   <li>12 - Delivery timed out</li>
 *   <li>13 - Gateway or routing error</li>
 *   <li>20 - Unknown error</li>
 * </ul>
 * The gateway code and string may also be provided in the $options array as
 * gateway_status and gateway_status_text.
 *
 * @param string $number
 *   The sender's mobile number.
 *
 * @param string $status
 *   An SMS Framework receipt status code. See comment above.
 *
 * @param array $options
 *   Extended options passed by the receipt receiver.
 */
function sms_receipt($number, $status, $options = array()) {
  // Execute three phases
  module_invoke_all('sms_receipt', 'pre process', $number, $status, $options);
  module_invoke_all('sms_receipt', 'process', $number, $status, $options);
  module_invoke_all('sms_receipt', 'post process', $number, $status, $options);
}

Here is an example of a gateway module implementing this:

/**
 * Receive a message send receipt from Clickatell
 *
 * Will generate an $options array with the following variables:
 * <ul>
 *   <li>reference - A message reference code, if set on message send.</li>
 *   <li>gateway_status - A Clickatell message status code.</li>
 *   <li>gateway_status_text - A text string associated with the gateway_status.</li>
 *   <li>receiver - The destination MSISDN number. Clickatell param: 'to'</li>
 *   <li>api_id - Your Clicaktell API ID. Clickatell param: 'api_id'</li>
 *   <li>charge - A credit amount that is charged. Decimal value. Clickatell param: 'charge'</li>
 *   <li>cliMsgId - Same as reference. Clickatell param: 'cliMsgId'</li>
 *   <li>moMsgId - The message ID code that refers to a message originally sent with the 'expectreply' or 'mo' parameter. Clickatell param: 'moMsgId'</li>
 * </ul>
 */
function sms_clickatell_receive_receipt() {
  $number = $_REQUEST['from'];
  $gateway_status = $_REQUEST['status'];

  $gateway_status_codes = sms_clickatell_message_status_codes();
  $gateway_status_text = $gateway_status_codes[$gateway_status];

  // SMS Framework status code (format gateway status to framework status code)
  switch ($gateway_status) {
    case '003':
    case '004':
      $status = 1;
      break;
    case '002':
    case '011':
      $status = 2;
      break;
    case '005':
      $status = 11;
      break;
    case '010':
      $status = 12;
      break;
    case '001':
    case '006':
    case '007':
    case '009':
    case '012':
      $status = 13;
      break;
    default:
      $status = 20;
      break;
  }

  // Message reference tag
  $reference = (array_key_exists('cliMsgId',$_REQUEST)) ? $_REQUEST['cliMsgId'] : NULL;

  // Gateway-specific variables
  $options = array();
  $options['reference'] = $reference;
  $options['gateway_status'] = $gateway_status;
  $options['gateway_status_text'] = $gateway_status_text;
  if (array_key_exists('to', $_REQUEST) && !empty($_REQUEST['to'])) {
    $options['receiver'] = $_REQUEST['to'];
  }
  if (array_key_exists('api_id', $_REQUEST) && !empty($_REQUEST['api_id'])) {
    $options['api_id'] = $_REQUEST['api_id'];
  }
  if (array_key_exists('moMsgId', $_REQUEST) && !empty($_REQUEST['moMsgId'])) {
    $options['msg_id'] = $_REQUEST['moMsgId'];
  }
  if (array_key_exists('charge', $_REQUEST) && !empty($_REQUEST['charge'])) {
    $options['charge'] = $_REQUEST['charge'];
  }
  if (array_key_exists('cliMsgId', $_REQUEST) && !empty($_REQUEST['cliMsgId'])) {
    $options['cliMsgId'] = $_REQUEST['cliMsgId'];
  }
  
  // Invoke the SMS Framework receipt handler
  sms_receipt($number, $status, $options);
}

I have tested this, and it works pretty well.

Anyway, let me know what you think. Thanks!
~ap

Hi Roger, thanks for the feedback - I like your thinking! I'll address your message in two parts. Part one:

After reviewing the link you sent, I agree that constants are the way to go. The SMS Framework doesn't currently define any constant sets, so we would probably need clearance from the maintainers before this would get in - they might suggest that sms_receipt() should be in a separate module.

Anyway, in the spirit of good doc here are my initial definitions: (it seems that this post is removing my indents...!)

/**
 * Message delivered
 * 
 * The SMS message has been delivered successfully.
 */
define('SMS_RECEIPT_STATUS_DELIVERED', 1);

/**
 * Message queued for delivery
 *
 * The message is in a delivery queue - it may have been delayed by gateway issues
 * or the target MSISDN may be unable to receive SMS (device off, no signal, etc).
 * If the message stays in the queue for too long then it might time out.
 */
define('SMS_RECEIPT_STATUS_QUEUED', 2);

/**
 * Invalid or malformed message
 *
 * The gateway rejected the message because a part of the message is invalid -
 * this could be the headers or the body text.
 */
define('SMS_RECEIPT_STATUS_INVALID_MESSAGE', 11);

/**
 * Message delivery timeout
 *
 * The message could not be delivered within the time limit - the gateway has had
 * the message in a delivery queue and has been retrying periodically. It may have
 * been delayed by gateway issues or the target MSISDN may be unable to receive SMS
 * (device off, no signal, etc).
 */
define('SMS_RECEIPT_STATUS_DELIVERY_TIMEOUT', 12);

/**
 * Message routing error
 *
 * The message could not be delivered because the MSISDN is invalid or the gateway
 * cannot send to the required mobile network.
 */
define('SMS_RECEIPT_STATUS_ROUTING_ERROR', 13);

/**
 * Other error
 *
 * There was an undefined error when trying to send the message. Feel free to define
 * more of these error constants/codes if you need to handle other specific errors,
 * and please feed back to the SMS Framework group.
 */
define('SMS_RECEIPT_STATUS_ERROR', 20);

Let me know if you (or anyone else) thinks of any other codes that we should add as default.
~ap

Hi again Roger. This is part deux of my reply (about message-receipt matching):

I had the same thought about the usefulness of sms_receipt() without the ability of matching messages to receipts. My conclusion is that you usually need to be able to link the receipts to messages - otherwise sms_receipt() just gives you blind statistics! So I think that I will work on the message-receipt matching module, which will be completely optional and will have to implement a DB table.

About using watchdog, good idea, but I think that it would be considered bad form to update existing records of a logging table, and also the single timestamp issue that you wrote about would negate the usefulness of this. However, we could write the message reference in receipt records sent to watchdog, which the user could then search to view the lifecycle of the message (sent, queued, delivered). This would require a patch to sms_send_log() to write a message ID.

I will get to work on that module, but let me know if you have any other thoughts on this. Thanks Roger!
~ap

Hi again, I have been at work on the message delivery tracking module, when I realised that the receipts hasn't really been accepted in the SMS Framework yet.

Will, it would be great to have some input from you about integrating receipts into sms.module. I also have need for an extra hook in sms_send(), just before the return, so that I can capture the message send status from the gateway response.

Roger, is this module something that you would like to use? If so then I will continue.

Thanks guys,
~ap

Ok @RogerSaner, I don't have any particular desire to keep working on it. But if there was a need I would have happily done so.

Marked as postponed :-)

PS. I haven't figured out how to get email updates for these issues at all, so apologies for the late reply.

@RogerSaner, FYI I just found that in the Issues for SMS Framework page there is a Subscribe link, where you can subscribe to All or My issues. It works for me - I am now getting immediate updates by email.

Hi @walterheck,

Take a look at the 6.x-1.x-dev release. You will find that receipts are implemented in the modules there, and sms.module provides a hook that you can implement for processing receipts.

I was hoping to have a message tracker module ready by now (that would process receipts for you) but I haven't had time to iron out the kinks just yet.

Let me know if you need any info about how it works. I haven't written any wiki docs, but the code documentation should be good enough to help you implement this feature.