MOs, Read Receipts and Delivery Receipts

Overview

This release included:

  • A fix to a defect where the rcsMoMessage wrapper field was not being returned for read and delivery receipts, and for MO messages.
  • Changes to improve the information contained in MO messages, read receipts and delivery receipts.

These changes are not backwards-compatible.

Details

Changes to MO messages

MO messages provide information back to you about the actions end users take when they receive your RCS message. For example, an MO can include information indicating that the end user clicked a link to your website.

A few changes were made to MO messages to make it easier for you to understand how the different message parts relate to the whole message.

  • An MOs with postback data has a new field, mtRequestId, which helps you identify which MT request the MO postback is associated with.
  • The messageId field was renamed to moMessageId to distinguish it from MT message IDs.
  • The value of the version field changed to "2", indicating that there were enough changes to MOs to warrant updating the version number.

For more information, see

Example MO with content

Current MO New MO 
{
   "version": "1",
   "campaignId": "MYCAMPAIGN",
   "customerAccountId": "123-123-121-17890",
   "submittedDate": "2019-11-11T10:43:48Z",
   "messageId": "4d3ceea4-cf17-4655-87a5-136382abd3d3",
   "sourceAddress": "441234501234",
   "destinationAddress": "207788990011",
   "content": "Demo Test"
}

 
{
   "rcsMoMessage":{
      "version": "2",
      "campaignId": "MYCAMPAIGN",
      "customerAccountId": "123-123-121-17890",
      "submittedDate": "2019-11-11T10:43:48.000Z",
      "moMessageId": "4d3ceea4-cf17-4655-87a5-136382abd3d3",
      "sourceAddress": "441234501234",
      "destinationAddress": "207788990011",
      "content": "Demo Test"
   }
}

Example MO with postback

Current MO New MO 
{
   "version": "1",
   "campaignId": "MYCAMPAIGN",
   "customerAccountId": "123-123-121-17890",
   "submittedDate": "2019-11-11T11:48:02Z",
   "messageId":"869549e0-59a4-428b-b83f-9dc74449e924",
   "sourceAddress":"441234501234",
   "destinationAddress":"207788990011",
   "postBack":{
      "customerData":"UserClickOnWebsite"
   }
}


 
{
   "rcsMoMessage":{
      "version":"2",
      "campaignId":"MYCAMPAIGN",
      "customerAccountId":"123-123-121-17890",
      "submittedDate":"2019-11-11T11:48:02.000Z",
      "moMessageId":"869549e0-59a4-428b-b83f-9dc74449e924",
      "sourceAddress":"441234501234",
      "destinationAddress":"207788990011",
      "postBack":{
         "mtRequestId":"012-W030J-0DL8R-10201-JWS24-PSI",
         "customerData":"UserClickOnWebsite"
      }
   }
}

Changes to delivery and read receipts

For delivery and read receipts, we added the following new fields:

  • rootMessageId. Since multiple messages can be sent in a single request, delivery and read receipts can contain receipt information for multiple messages. The rootMessageId identifies which specific message triggered this receipt.

    For example, if a receipt body contains two messages (e.g., a text message and a media message), and this receipt was caused by the first message, then the rootMessageId value would be the same as the value of messageId of the first message in the list. This prevents duplicates by showing which message this receipt is associated with.

  • requestStatus. This field indicates the overall status of a group of sent messages in a single transmission, as opposed to the status of a single message within the transmission. Possible statuses are:

    • PENDING: One or more of the sent messages are waiting for a response.
    • SUCCESS/FAILED: Indicates that all sent messages either succeeded or failed.
    • PARTIAL_FAILURE: At least one of the sent messages failed or timed-out, while the others were sent successfully.
  • provider. To make troubleshooting delivery receipts easier, this field was added showing the name of the provider to whom the message was sent.
  • messageType. This field indicates the type of message. Possible values for the messageType are:
    • TEXT: The message was text.
    • MEDIA: The message was a media file.
    • RICHCARD: The message was a rich card.

In addition, the value of the version field changed to "2", indicating that there were enough changes to delivery and read receipts to warrant updating the version number.

For more information, see

Example receipt

Current New 

{
    "version":"1",
    "campaignId":"MYCAMPAIGN",
    "customerAccountId":"123-123-121-17890",
    "requestId":"012-W030J-0DL8R-10201-JWS24-PSI",
    "messages":[
     {
        "messageId":"572b198f-134d-4b90-9971-1f7f297085d1",
        "endUserEventDate":"2019-11-11T21:13:44.775Z",
        "status":"SUCCEEDED"
     },
     {
        "messageId":"63da8dd5-e18a-4e36-9140-49e3250b587f",
        "endUserEventDate":"2019-11-11T20:32:32.878Z",
        "status":"FAILED",
        "failureReason":"41006 Session terminated"
     }
    ],
    "receiptType":"DELIVERY",
    "sourceAddress":"18005555555",
    "destinationAddress":"12065551212",
    "done":true
}

{
   "receipt":{
        "version":"2",
        "campaignId":"MYCAMPAIGN",
        "customerAccountId":"123-123-121-17890",
        "requestId":"012-W030J-0DL8R-10201-JWS24-PSI",
        "rootMessageId":"63da8dd5-e18a-4e36-9140-49e3250b587f",
        "messages":[
         {
            "messageId":"572b198f-134d-4b90-9971-1f7f297085d1",
            "endUserEventDate":"2019-11-11T21:13:44.775Z",
            "status": "SUCCEEDED",
	        "messageType": "MEDIA"
         },
         {
            "messageId":"63da8dd5-e18a-4e36-9140-49e3250b587f",
            "endUserEventDate":"2019-11-11T20:32:32.878Z",
	        "status": "FAILED",
	        "messageType": "TEXT",
            "failureReason":"41006 Session terminated"
         }
        ],
	 "requestStatus":"PARTIAL_FAILURE",
	 "provider":"GOOGLE",
        "receiptType":"DELIVERY",
        "sourceAddress":"18005555555",
        "destinationAddress":"12065551212",
        "done":true
   }
}