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.
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 accepts ISO timestamps and epoch time formats. 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 EST 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 ISO timestamp or 13 digits epoch.
ISO timestamp format
In this example the ISO timestamp is: "2022-07-01T17:00:00.000-06:00"
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\": "2022-07-01T17:00:00.000-06:00", \
\"to\":[\"+5066173XXXX\"], \
\"body\":\" Test message with expiry time with 13 digit\" \
}"
Epoch format
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": XXXXXX,
"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": XXXXX,
"reason_code": "200",
"sender_id_alias": "FVwXNFWghnXyBazsXXXXXX",
"company-id": [company_id],
"sender_id_id": "FVwXNFWghnXyBazsXXXXXX",
"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": XXXXX,
"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": XXXXX,
"reason_code": "1007",
"sender_id_alias": "FVwXNFWghnXyBazsXXXXXX",
"company-id": [company_id],
"sender_id_id": "FVwXNFWghnXyBazsXXXXXX",
"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.
0 Comments