Upload Message
Uploads a message to use for retention messaging.
URL
PUT https://api.storekit.apple.com/inApps/v1/messaging/message/{messageIdentifier}Sandbox URL
PUT https://api.storekit-sandbox.apple.com/inApps/v1/messaging/message/{messageIdentifier}Path Parameters
| Name | Type | Description |
|---|---|---|
messageIdentifier Required | messageIdentifier | A UUID you provide to uniquely identify the message you upload. |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK | Request succeeded. | |
| 400 | Bad Request Content-Type: application/json | (BodyTooLongError | HeaderTooLongError | AltTextTooLongError | BadRequestImageSizeError | BadRequestTooManyBulletPointsError | BadRequestBulletPointTextTooLongError | BadRequestAboveImageRequiresAnImageError) | The request is invalid and unacceptable. |
| 401 | Unauthorized | The JSON Web Token (JWT) in the authorization header is invalid. For more information, see Generating JSON Web Tokens for API requests. | |
| 403 | Forbidden Content-Type: application/json | MaximumNumberOfMessagesReachedError | The request is forbidden because the system reached the maximum number of uploaded messages. |
| 409 | Conflict Content-Type: application/json | MessageAlreadyExistsError | The message identifier already exists. |
| 429 | Content-Type: application/json | RateLimitExceededError | The request exceeded the rate limit. For more information, see Identifying rate limits. |
| 500 | Internal Server Error Content-Type: application/json | GeneralInternalError | Server error. Try again later. |
Mentioned in
Discussion
Call this endpoint to upload the text for retention messages. You provide a unique messageIdentifier to identify each message you upload. You can optionally include an image and bullet points with the message.
You define a message by providing the following strings and objects in the UploadMessageRequestBody:
The body, which contains the main text of the message.
A header, which contains text to display above the message body or above the image.
An optional UploadMessageImage that represents an image you upload with alternative text.
An optional array of BulletPoint text, along with images to use as the bullet point icons.
To change the position of the header text in a retention message, use headerPosition to indicate whether to place the header above the message body or above the image.
Each string needs to be a UTF-8-encoded value with a maximum length as indicated below:
Field | Maximum length | Related error code |
|---|---|---|
66 | ||
144 | ||
150 | ||
66 |
The maximum number of messages you can configure for each app is 2000. For example, you may choose to upload a message for a product identifier for each locale your app supports. The endpoint returns a MaximumNumberOfMessagesReachedError response if you exceed the maximum limit. Call Delete Message to delete messages.
This endpoint isn’t idempotent. If you have a previously configured message with the same messageIdentifier, the endpoint returns MessageAlreadyExistsError.
Determine whether a message is ready to display
Immediately after you upload an message, its messageState is PENDING. Apple checks the message, and sets the message state to APPROVED to indicate the system can display it in retention messaging. Call the Get Message List endpoint to check the current state of all messages. If a message includes an image, call Get Image List to check the current state of the image separately. Both the message and its image, if any, need to be in an APPROVED state before the system can display a message.
In the sandbox testing environment, the system automatically sets message and image states to APPROVED.
HTTP Body
The message text to upload.