RCS Delivery and Read Receipt Parameters and Examples

This page describes the parameters returned in OpenMarket's RCS delivery and read receipts, as well as examples. For information on how RCS processes delivery and read receipts, see RCS Delivery and Read Receipts.

Important: In February 2021 we will release a new version of the logic for delivery and read receipts. You will receive an announcement about the specific changes, which include: removing the failureReason field and replacing it with errorDetails, and adding new status codes that provide more precise information about the status of a message.

Delivery and read receipt parameters

Receipt parameters

Parameter

Description

receipt

Receipt message wrapper indicating delivery and read receipts. It's composed of the parameters described below.

version

Used to indicate OpenMarket's RCS delivery and read receipts version.

Type: string

Multiple allowed?: No

Default value: None

Required: Yes, but the only supported value is 3.
campaignId

Unique identifier for a global campaign. It must be associated with the accountID.

Type: Case-insensitive alphanumeric string.

Multiple allowed?: No

Default value: None

Required: Yes. Must have a minimum of one character and maximum of 32.
customerAccountId

The customer's IDS Account ID.

Type: Case-insensitive alphanumeric string.

Multiple allowed?: No

Default value: None

Required: Yes. Hyphens (-) and underscores (_) are allowed. Must have a minimum of one character and maximum of 17.
requestId

The identifier created when the RCS message API was invoked. This identifies the messages sent within a single RCS transmission.

Type: string

Multiple allowed?: No

Required: Yes

rootMessageId

MessageID identifying the entire group of messages sent within the request. The rootMessageId prevents multiple copies of delivery or read receipts being sent for a single transmission.

Type: string

Multiple allowed?: No

Default value: None

Required: Yes, even if there is only one message type sent.
sourceAddress

The string or number associated with the message sender. If a number, it must use an international format but without a leading + symbol. For example, 447700900765 (UK) or 12515550100 (US).

Type: string

Multiple allowed?: No

Default value: None

Required: Yes.

destinationAddress

The RCS-capable phone number to which a message (MT) was sent. This must be in international format but without a leading + symbol. For example, 447700900765 (UK) or 12515550100 (US).

Type: string,

Multiple allowed?: No

Default value: None

Required: Yes. Must be a minimum of six characters and a maximum of 20.
done

Indicates the status of all messages in the array, which will be TRUE or FALSE. TRUE means that all messages reached a terminal state (either SUCCEEDED, FAILED, TIMED_OUT, or CAP_CHECK_FAILED), while FALSE means that one or more of the messages is in a PENDING state.

Type: boolean

Multiple allowed?: No

Default value: None

Required: Yes. Must be one of:

  • TRUE
  • FALSE

messages

messages is an array of message objects that returns information about messages sent when the API was invoked. Because one request can include multiple messages, delivery receipts and read receipts are delivered together. Currently, RCS does not segment text-only messages, so each message in the array will include a unique messageId. The messages array is composed of the following elements.
endUserEventDate

The time and date that the receipt event occurred on the end user's handset. If the message is PENDING, the date will be NULL as the event has yet to occur.

Type: string

Multiple allowed?: No

Default value: None

Required: No. Must use the UTC format YYYY-MM-DDTHH:MM:SS.SZ. For example, 2018-01-01T12:34:56.012Z.
messageId

OpenMarket's unique identifier for the RCS message.

Type: string.

Multiple allowed?: No

Default value: None

Required: Yes. Alphanumeric characters, with a minimum of one and a maximum of 64. Underscores (_) and hyphens (-) are allowed.
status

Indicates the status of the message.

 

Type: string

Multiple allowed?: No

Default value: None

Required: Yes. Must be one of the following:

  • SUCCEEDED: OpenMarket received a callback from the provider indicating the message was delivered and/or read.
  • PENDING: The message was submitted successfully to the provider, but OpenMarket has not yet received a delivery receipt or read receipt from them.
  • FAILED: The message could not be submitted successfully to the provider.
  • TIMED_OUT: No response was received back from the provider about the status of the message, so the request timed out. The default time to receive a response is 72 hours. PENDING messages that aren't delivered or failed to deliver time out at this time.
messageType

Indicates the type of RCS message.

 

Type: string

Multiple allowed?: No

Default value: None

Required: Yes. Must be one of the following:

  • TEXT: The sent message was text.
  • MEDIA: The sent message was a media file.
  • RICHCARD: The sent message was a rich card.

errorDetails

Object returned containing details about any messages that fails to deliver. Typically there will be one error per message, but this array supports multiple message errors. It's composed of the errorCode, errorDescription, and retryable.
errorCode

Code returned for the failed message. For a list of codes, see Capability and Delivery Response Error Codes.

Type: integer

Multiple allowed?: No

Default value: None

Required: Yes
errorDescription

Associated description of the error code.

Type: string

Multiple allowed?: No

Default value: None

Required: Yes
retryable

Indicates whether you can retry sending the failed message.

Type: boolean

Multiple allowed?: No

Default value: None

Required: Yes
requestStatus

Indicates the overall status of a group of messages in a single transmission.

Type: string

Multiple allowed?: No

Default value: None. Possible values are:

  • PENDING: At least one of the sent messages is waiting for a response.
  • SUCCESS/FAILURE: All messages in the group either succeeded or failed.
  • PARTIAL_FAILURE: At least one message in the group timed out or failed, but the others were sent successfully.
  • CAP_CHECK_FAILED: Either the capabilities required did not match those on the device, or we could not identify the capabilities of the device. You can check the Result element in the capabilityDetails object for more details about the capability check failure.

Required: Yes
provider

The provider to whom the message was sent. This field is useful when troubleshooting why messages might not have been delivered.

Type: string

Multiple allowed?: No

Default value: None

Required: Yes.

receiptType

Indicates whether the receipt is a delivery receipt or a read receipt.

Type: string

Multiple allowed?: No

Default value: None

Required: Yes. Must be one of:

  • DELIVERY
  • READ

capabilityDetails

This object is returned only when the capabilities being sent either do not match the capabilities supported on the end user's phone or if we receive an error when sending the capabilities. It's composed of capabilitiesFound, capabilitiesRequired, and result. This object is returned only when the requestStatus is CAP_CHECK_FAILED. Otherwise, it will not be returned. Only one of this object is allowed.
capabilitiesFound

This is an array composed of the capabilities found for the device.

Required: Yes.

capabilitiesRequired

This is the list of required capabilities sent in the original MT message.

Type: string

Multiple allowed?: Yes

Default value: None

Required: Yes. Must be at least one of the following:

  • CHAT
  • IMAGE
  • VIDEO
  • CHATBOT
  • FILE_TRANSFER
  • GEOLOCATION
  • CALENDAR_EVENT
  • DIAL_NUMBER
  • OPEN_URL
  • REVOCATION
  • RICHCARD_STANDALONE
  • RICHCARD_CAROUSEL
result

Indicates whether or not the capability check failed for one of two reasons: either the capabilities did not match or there was an error.

Type: string

Multiple allowed?: No

Default value: None

Required: Yes. The value must be one of the following:

  • NO_MATCH: The capabilitiesRequired sent in the message did not match the supported capabilities on the end user's phone.
  • ERROR: An error was encountered when trying to retrieve the supported capabilities on the end user's phone. If this value is returned, then an errorDetails object is also also provided in the response.

 

failureReason

 This field has been deprecated and replaced by errorDetails, described above. Note that while failureReason has been deprecated, it has not been removed from code and might still be returned in a delivery receipt
sourceAddress

The string or number associated with the message sender. If a number, it must use an international format but without a leading + symbol. For example, 447700900765 (UK) or 12515550100 (US).

Type: string

Multiple allowed?: No

Default value: None

Required: Yes
destinationAddress

The RCS-capable phone number to which a message (MT) was sent. This must be in international format but without a leading + symbol. For example, 447700900765 (UK) or 12515550100 (US).

Type:string

Multiple allowed?: No

Default value: None

Required: Yes, must be a minimum of 6 characters and maximum of 20.

done

Indicates the status of all messages in the array, which will be TRUE or FALSE. TRUE means that all messages reached a terminal state (either SUCCEEDED, FAILED, TIMED_OUT, or CAP_CHECK_FAILED), while FALSE means that one or more of the messages is in a PENDING state.

Type:boolean

Multiple allowed?: No

Default value: None

Required: Yes, must be one of:

  • True
  • False

Example delivery and read receipt messages

RCS message receipt with text type showing Succeeded status

In this example, an RCS message is sent that contains two types, text and media. The delivery receipt was returned with SUCCEEDED for one type, but at the time the delivery receipt was sent, the second type was undelivered; therefore, the delivery receipt returns a status of PENDING for that type. Because the final status of all messages is still undetermined, delivery is considered incomplete, or FALSE.

Delivery receipt showing one successful message and one pending message

Copy 
{
    "receipt":{
        "version":"2",
        "campaignId":"CAMPGN1",
        "customerAccountId":"000-000-000-0000",
        "requestId":"5431824e-533f-4857-91e0-f240c5e6003c",
        "rootMessageId":"63da8dd5-e18a-4e36-9140-49e3250b587f",
            "messages":[
                {
                "endUserEventDate":"2017-05-01T12:34:56.012Z",
                "messageId":"6d4c74d8-f0fb-4697-9920-20f976ef7ed1",
                "status":"SUCCEEDED",
                "messageType":"MEDIA"   
                },
                {
                "endUserEventDate":"2017-05-01T12:35:56.012Z",
                "messageId":"6d4c74d8-f0fb-4697-9920-20f976ef7ed2",
                "status":"PENDING",
                "messageType":"TEXT"
                   }
                   ],
        "requestStatus":"PENDING",
        "provider":"GOOGLE",
        "receiptType":"DELIVERY",
        "sourceAddress":"12065551212",
        "destinationAddress":"18001234567",
        "done":false
       }
}

 

Once the status of the second message changes, an updated delivery receipt is returned indicating the new status. In this example, message delivery could not be completed within the 72 hours for an unknown reason, so the status of the second type changes to FAILED. Because FAILED is considered a completed action, the done status of all messages under that requestID is considered completed, or TRUE. At this point no more delivery receipts will be returned for this requestId.

Delivery receipt with one successful message and one failed

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

 

Finally, if your account is configure to receive read receipts, a third, read receipt message is returned. Because the second message failed to deliver, the status of the read receipt for that message is considered to have also failed as SUCCEEDED and FAILED are considered end states. The done status returns TRUE, and no more read receipts will be returned.

Receipt with one succeeded message, one failed message, and one failed read receipt

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

However, once the status of the second message changes, an updated delivery receipt is returned indicating the new status. In this example, message delivery could not be completed within the 72 hours for an unknown reason, so the status of the second type changes to FAILED. Because FAILED is considered a completed action, the done status of all messages under that requestID is considered completed, or TRUE. At this point no more delivery receipts will be returned for this requestId.

RCS message receipts with text, media, and richCard types showing Succeeded, Pending, and Failed

In this example, an RCS message is sent containing three types, text, media, and richCard. The delivery receipt was returned with SUCCEEDED for two types, but at the time the delivery receipt was sent, the third type failed. Because SUCCEEDED and FAILED are considered final statuses, delivery is considered complete, or TRUE. No further delivery receipts are sent

Done: Two Succeeded and One Failed Delivery Receipt

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

 

Because read receipts were provisioned, a second message returns the status of the read receipts. In this example.

  • The first type is SUCCEEDED because the end user read the message.
  • The second type is undetermined, or PENDING, as the end user has not yet opened the delivered message. It remains in this status until the message is accessed or a timeout occurs.
  • The third type is FAILED, as delivery of that type was unsuccessful.

Because of the PENDING status, the final done status cannot be determined, and is therefore set to FALSE.

Done: One Succeeded, one Pending, and One Failed Read Receipt

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

 

Within the 72-hour timeframe before the status of the second type changes to TIMED_OUT, the end user reads the second message type. A new read receipt is returned with the status of that type now set to SUCCEEDED. The final status changes to TRUE. No further read receipts will be sent.

Done: Two Succeeded and One Failed Read Receipt

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

Example capabilityDetails response messages

The following two examples show the use of the capabilityDetails object. This object is returned only when the requestStatus is CAP_CHECK_FAILED. Otherwise, this object will not be returned.

capabilityDetails: NO_MATCH

NO_MATCH is returned when the required capabilities sent in the message do not match the supported capabilities on the end user's phone.

Copy 
{
    "receipt": {
        "version": "2",
        "requestStatus": "CAP_CHECK_FAILED",
        "campaignId": "CAMUEMXZ5M",
        "customerAccountId": "000-000-115-00842",
        "requestId": "test-req-id-1205-11",
        "receiptType": "DELIVERY",
        "destinationAddress": "441234567890",
        "sourceAddress": "447786209907",
        "provider": "GOOGLE",
        "capabilityDetails": {
            "capabilitiesFound": [],
            "capabilitiesRequired": [
                "CHAT",
                "FILE_TRANSFER"
                ],
            "result": "NO_MATCH"
        },
        "done": true
    }
}

capabilityDetails: ERROR

ERROR is returned when we cannot determine whether or not the end user's phone supports the required capabilities or for some other error. When the capability check returns an ERROR, errorDetails are also included that include additional error information.

Copy 
{
    "receipt": {
        "version": "2",
        "requestStatus": "CAP_CHECK_FAILED",
        "campaignId": "CAMUEMXZ5M",
        "customerAccountId": "000-000-115-00842",
        "requestId": "test-req-id-1205-11",
        "receiptType": "DELIVERY",
        "destinationAddress": "441234567890",
        "sourceAddress": "447786209907",
        "provider": "GOOGLE",
        "capabilityDetails": {
            "capabilitiesFound": [],
            "capabilitiesRequired": [
            "CHAT",
            "FILE_TRANSFER"
            ],
            "result": "ERROR",
            "errorDetails": {
                "errorCode" : "2000",
                "errorDescription": "Capability check: provider not RCS supported",
                "retryable": false
            }
        },
        "done": true
    }
}