Changes to Delivery Receipts

Overview

This release included:

  • A new object, errorDetails, contains more detail about why a particular message failed delivery. With this addition, the failureReason field is now deprecated and no longer used. See errorDetails added to delivery receipts below. Note that while failureReason has been deprecated, it has not been removed from code and might still be returned in a delivery receipt.
  • A new value, CAP_CHECK_FAILED, added to the list of requestStatus values indicates that either the end user's phone did not support the sent capabilities, or it could not be determined whether or not the mobile device supported the sent capabilities. See requestStatus updated to include a capability check failure below.
  • A capabilityDetails object returns information about why an RCS message could not be delivered to an end user's phone if the requestStatus is CAP_CHECK_FAILED. See capabilityDetails object added below.
  • We now have a list of capability check and delivery failure error codes. These codes are returned when there's either a capability check or delivery failure. For a list of the codes, see Capability and Delivery Response Error Codes.

These changes are backwards-compatible as long as your system allows new and/or unrecognized JSON fields.

Details

errorDetails added to delivery receipts

errorDetails is a new object added to the messages field in delivery receipt and designed to provide more detail about a failed message rather than just returning a failureReason. errorDetails is composed of errorCode, errorDescription, and retryable. These fields describe the returned code for the failed message, the associated error code description, and whether or not the message is retryable. For more information about the new elements and examples of their use, see RCS Delivery and Read Receipt Parameters and Examples.

Example Delivery Receipt changes

Current Delivery Receipt

 
{
	"receipt": {
		"version": "2",
		"requestStatus": "FAILURE",
		"campaignId": "CAMPGN1",
		"customerAccountId": "000-000-000-0000",
		"requestId": "5431824e-533f-4857-91e0-f240c5e6003c",
		"rootMessageId":"63da8dd5-e18a-4e36-9140-49e3250b587f",									
			"messages": [
			{
				"messageId": "6d4c74d8-f0fb-4697-9920-20f976ef7ed2",
				"endUserEventDate": "2017-05-01T12:37:56.012Z",
				"status": "FAILED",
				"failureReason": "41006 Session terminated,
				"messageType": "RICHCARD"
			}
						],
		"receiptType": "DELIVERY",
		"destinationAddress": "18001234567",
		"sourceAddress": "12065551212",
		"provider": "GOOGLE",
		"done": true,
	"rootMessageId": "ca80d8ee"
									}
							}

New Delivery Receipt

 
{
	"receipt": {
		"version": "2",
		"requestStatus": "FAILURE",
		"campaignId": "CAMPGN1",
		"customerAccountId": "000-000-000-0000",
		"requestId": "5431824e-533f-4857-91e0-f240c5e6003c",
		"rootMessageId":"63da8dd5-e18a-4e36-9140-49e3250b587f",		
			"messages": [
			{
			"endUserEventDate": "2017-05-01T12:37:56.012Z",
			"messageId": "6d4c74d8-f0fb-4697-9920-20f976ef7ed2",
			"status": "FAILED",
			"messageType": "RICHCARD",
			"errorDetails":[
				{"errorCode":"5000",
 				 "errorDescription":"Send message:error calling provider",
				 "retryable":false
				}
				],
		"receiptType": "DELIVERY",
		"destinationAddress": "18001234567",
		"sourceAddress": "12065551212",
		"provider": "GOOGLE",
		"done": true,
		"rootMessageId": "ca80d8ee"			
			}
			]
		}			
}

requestStatus updated to include a capability check failure

requestStatus includes a new status, CAP_CHECK_FAILED. This new status indicates that a message failed to send because the end user's phone did not support the required RCS capabilities being sent in the message or that it could not be determined if the phone supported the capabilities being sent. When returned, a capabilityDetails object, described below, is included. That object lists the reason for the capability check failure.

Supported requestStatus values are now:

  • PENDING: One or more of the sent messages are waiting for a response.
  • SUCCESS/FAILURE: 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.
  • CAP_CHECK_FAILED: The end user's phone did not support the sent RCS capabilities, or it could not be determined whether or not the phone supported the sent RCS capabilities . The result element in capabilityDetails lets you know the reason.

For more information, see RCS Delivery and Read Receipt Parameters and Examples for descriptions of receipt fields as well as different examples.

capabilityDetails object added

If a message fails to send because the capabilities sent in the message don't match those on the phone, or we couldn't determine if the phone supports the sent capabilities, a new capabilityDetails object is returned. In this object we'll let you know which of those two failure results applies.

capabilityDetails is composed of:

  • capabilitiesFound: This is composed of capabilitiesRequired and result.
  • capabilitiesRequired: These are the capabilities being sent in the message. See the "Delivery and read receipt parameters" section of RCS Delivery and Read Receipt Parameters and Examples for a list of supported RCS capabilities.
  • result: If the capabilities found on the end user's phone do not match the capabilities being sent, we return NO_MATCH. If we are unable to determine the capabilities on the end user's phone, ERROR is returned. If the result is ERROR, we also include an errorDetails object describing the reason for the failure. This object is composed of errorCode, errorDescription, and retryable.

capabilityDetails

This shows sample formatting of the capabilityDetails object. errorDetails are returned only if the result is ERROR. If the result is NO_MATCH, the errorDetails object is not returned. For parameter descriptions and examples see RCS Delivery and Read Receipt Parameters and Examples

{
"capabilityDetails": {
	"capabilitiesFound": [],
		"capabilitiesRequired": [
			"<List of RCS capabilities sent in the message>"
		 ],
		"result":"<NO_MATCH or ERROR>",
		"errorDetails": {
			"errorCode": "<error code>",
			"errorDescription": "<error message>",
			"retryable": true or false
		}
	}
}