How to set expiry date on messages using SCG Messaging API

Specification v1.0, July 2022

 

Introduction

The SCG messaging API provides a way to set the “expiry date” on a message request so that the message will not be sent for any reason after a specific datetime. This can be used to prevent delivery of time-sensitive messages that have been queued for a long time.

Purpose of this document

This document describes how to use the SCG message_requests API method, specifically the field "expiry_time" on the request body schema to set the expiry time for a SMS message. This field value format type is: epoch time. For more information on epoch follow the link  https://www.epochconverter.com/

Requesting a SMS with expiry time

In the SCG Messaging API: The field " expiry_time" can be set using the epoch timestamp format. This can be used to prevent messages being sent after a specific datetime. This can be set as shown in this example:

  • Example use case: we need to guarantee an SMS will not be sent after 5pm on July 1st, 2022
  • The epoch time is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT).
  • SCG Messaging API require 13 or 16 digits epoch.
  • the date command to convert from human date to epoch is:

$ date +%s -d"Jul 1, 2022 17:00:00 EST"

1656716400

 

Let’s use 1656716400000 as expiry time date (note we complete to 13 digits with zeros).

The Curl command to request a SMS to be sent before Jul 1, 2022 17:00:00 EST is

curl -L -X POST https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests -H "Content-Type: application/json" -H "Authorization: Bearer [TOKEN]" -d "{\"from\":\"channel:Bxn9SHBYhl89KnuDllO2L4\",\"expiry_time\": 1656716400000, \"to\":[\"+5066173XXXX\"],\"body\":\" Test message with expiry time with 13 digit\"}"

 

We can retrieve the message status with messaging/message_requests/{MessageRequest_ID}

{

    "application_id": 11407,

    "company_id": [company_id],

    "created_date": 1656707803863,

    "last_updated_date": 1656707807918,

    "version_number": 3,

    "id": "TpqMgm9HouKouMmUnCaT6",

    "from": "channel:Bxn9SHBYhl89KnuDllO2L4",

    "to": [

        "+5066173XXXX"

    ],

    "consent_requirement": "NONE",

    "attachments": [],

    "body": " Test message with expiry time with 13 digit",

    "expiry_time": 1656716400000,

    "state": "DELIVERED",

    "channel_id": "Bxn9SHBYhl89KnuDllO2L4",

    "sender_id_sort_criteria": [],

    "contact_delivery_address_priority": [],

    "mediaURL_attachIds": [],

    "message_type": "SMS"

}

 

Also, when subscribed, a DR is delivered:

{

  "topic": "SCG-Message",

  "attempt": 1,

  "event": {

    "fld-val-list": {

      "previous_state": "SENT",

      "message_request_id": "TpqMgm9HouKouMmUnCaT6",

      "message_id": "TpqMgm9HouKouMmUnCaT6",

      "to_address": "+5066173XXXX",

      "has_attachment": false,

      "reason_description": "SUCCESS",

      "application_id": 11407,

      "reason_code": "200",

      "sender_id_alias": "FVwXNFWghnXyBazsR1HxQ3",

      "company-id": [company_id],

      "sender_id_id": "FVwXNFWghnXyBazsR1HxQ3",

      "external_message_request_id": "",

      "new_state": "DELIVERED",

      "fragments_count": 1,

      "from_address": "7777",

      "mt_price": 0.024

    },

    "evt-tp": "message_state_change",

    "timestamp": "2022-07-01T20:36:48.042Z"

  },

  "event-id": "uQJyo2VaS6Sr7jop2yXf8Q"

}

Expired SMS sample

In this example, we are going to set an expiry_time in the past, Friday, July 1, 2022 12:00:00 PM EST, and see the resulting status and DR.

The 13 digits epoch is 1656698400000   =   July 1, 2022 12:00:00 PM EST

 

curl -L -X POST https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests -H "Content-Type: application/json" -H "Authorization: Bearer [TOKEN]" -d "{\"from\":\"channel:Bxn9SHBYhl89KnuDllO2L4\",\"expiry_time\": 1656698400000, \"to\":[\"+5066173XXXX\"],\"body\":\" Test message with expiry time with 13 digit\"}"

 

Retrieving the message, we can see the state as FAILED, failure details "Message Expired".

{

    "application_id": 11407,

    "company_id": [company_id],

    "created_date": 1656709784723,

    "last_updated_date": 1656709784834,

    "version_number": 2,

    "id": "INrbgQjtWcBVqz8p2gSrg4",

    "from": "channel:Bxn9SHBYhl89KnuDllO2L4",

    "to": [

        "+5066173XXXX"

    ],

    "consent_requirement": "NONE",

    "attachments": [],

    "body": " Test message with expiry time with 13 digit",

    "expiry_time": 1656698400000,

    "state": "FAILED",

    "failure_code": 1007,

    "failure_details": "Message Expired",

    "channel_id": "Bxn9SHBYhl89KnuDllO2L4",

    "sender_id_sort_criteria": [],

    "contact_delivery_address_priority": [],

    "mediaURL_attachIds": [],

    "message_type": "SMS"

}

The DR shows FAILED and the reason: "Message Expired - Message could not be sent within the expiry time defined. Please resent the message" as shown in the next figure:

{

  "topic": "SCG-Message",

  "attempt": 1,

  "event": {

    "fld-val-list": {

      "previous_state": "QUEUED",

      "message_request_id": "INrbgQjtWcBVqz8p2gSrg4",

      "message_id": "INrbgQjtWcBVqz8p2gSrg4",

      "to_address": "+5066173XXXX",

      "has_attachment": false,

      "reason_description": "Message Expired - Message could not be sent within the expiry time defined. Please resent the message",

      "application_id": 11407,

      "reason_code": "1007",

      "sender_id_alias": "FVwXNFWghnXyBazsR1HxQ3",

      "company-id": [company_id],

      "sender_id_id": "FVwXNFWghnXyBazsR1HxQ3",

      "external_message_request_id": "",

      "new_state": "FAILED",

      "fragments_count": 1,

      "from_address": "7777",

      "mt_price": 0

    },

    "evt-tp": "message_state_change",

    "timestamp": "2022-07-01T21:09:44.831Z"

  },

  "event-id": "sXp8gS3pRDKB1V0kLb49xA"

}

 

Note the DR’s timestamp is 2022-07-01T21:09:44.831Z   =   July 1, 2022 03:09:44 PM EST is the time we run the curl command to send the message, long after the expiry time we set.

The message was not sent due to the expiration date.

 

Was this article helpful?
0 out of 0 found this helpful

0 Comments

Please sign in to leave a comment.