Notifications about Catapush messages can be received via HTTP callbacks. Every callback has the User-Agent header set to Catapush.
Callbacks for outgoing messages can be configured to be sent in three forms:
GET with a query string.
POST with an application/x-www-form-urlencoded body.
POST with an application/json body.
For each outgoing message lifecycle events Catapush sends a callback request with the information about the specific event, encoded in the query string or the request body as a set of key-value pairs described in the following table.
|
Key name |
Value type |
Constraints |
Description |
|
type |
String |
Mandatory |
Always set to MessageStatus |
|
timestamp |
String (ISO-8601 UTC) |
Mandatory |
Date and time of the message event. |
|
applicationId |
String |
Mandatory |
Identifies the application that sent the message. |
|
messageId |
String (UUID) |
Mandatory |
Identifies the message in the context of Catapush. |
|
recipient |
String |
Mandatory |
Identifies the recipient of the message. |
|
status |
String |
Mandatory |
Describes the current status of the message. |
|
messageRef |
String |
Optional |
External, application specific, identifier for the message. |
|
recipientRef |
String |
Optional |
External, application specific, identifier for the recipient of the message. |
|
fallbackRef |
String |
Optional |
The mobile number of the recipient for the fallback message. |
The status key specifies one of the following possible message lifecycle events.
|
Notification status value |
Description |
|
enqueued |
The message has been sent enqueued in the Catapush system, but it may have not yet been delivered. |
|
delivered |
The message has been successfully delivered to the recipient’s device, but it may have not yet been read by the recipient. |
|
read |
The message has been read by the recipient. |
|
expired |
The message was sent, but it has not been delivered before the specified expire time to the recipient’s device. |
|
fallbackOnUndelivered |
A fallback message is necessary, because the catapush message was not delivered before the specified fallback time to the recipient’s device. |
|
fallbackOnUnread |
A fallback message is necessary, because the catapush message was delivered to the recipient’s device but not read before the specified fallback time. |
|
fallbackSent |
A fallback message (SMS) has been sent to the recipient’s mobile number, but it may not have been delivered yet. |
|
fallbackDelivered |
A fallback message (SMS) has been delivered to the recipient’s mobile number. |
|
fallbackExpired |
The SMS carrier could not deliver the fallback message in time. |
|
fallbackInvalidNumber |
The SMS carrier could not deliver the fallback message because the recipient’s mobile number is invalid. |
|
fallbackPhoneError |
The SMS carrier could not deliver the fallback message because the recipient’s mobile phone cannot receive SMS (it usually happens if the phone SMS memory is full). |
|
fallbackOperatorError |
The SMS carrier is not currently available to send messages. |
|
iOSError |
Catapush tried to send an Apple push notification to the recipient’s device but there was an error. It usually happens when there’s a wrong configuration of the Apple push integration. |
|
iOSErrorInvalidToken |
Catapush can’t send an Apple push notification to the recipient’s device because the specified device push token in invalid. It usually happens if the user uninstalls the app. |
|
AndroidError |
Catapush tried to send a Google push notification to the recipient’s device but there was an error. It usually happens when there’s a wrong configuration of the Google push integration. |
|
AndroidErrorInvalidToken |
Catapush can’t send a Google push notification to the recipient’s device because the specified device push token in invalid. It usually happens if the user uninstalls the app. |
|
PushSent |
A push message has been successfully sent to the recipient’s device. |
|
IdentifierNotFound |
The message was not delivered because the recipient does not exists |
