Outgoing Messages

When a business replies to a user’s text message, the Messaging Service Provider (MSP) platform prepares the message for delivery and sends a POST request to the /message endpoint hosted by Apple Messages for Business. Messages for Business validates the message, returns a response code to the MSP platform, and delivers the message to the user’s device.

“MSP
Communicate with users using Messages for Business

Sending Messages to Messages for Business Service

You can send messages to a user by using the POST /message request method to the Messages for Business service. Messages for Business delivers the message to the user’s device. Unless otherwise noted, all text fields support Basic Multilingual Plane of Unicode. For information about sending interactive messages, see iMessage App (Custom InteractiveData).

In addition to the dictionaries listed below, sending a message also includes keys from the Attachment dictionary.

Request

POST https://mspgw.push.apple.com/v1/message

Parameters

In addition to the keys from HTTP Body, use the following keys:

Name Type Description
body string REQUIRED. The message text. Required when the type is text.
interactiveData A dictionary representing the properties of an interactive message. See BaseInteractiveMessage dictionary.
type string REQUIRED. A string that identifies the message type. For the list of possible values, see Message Type Values.

Response

The response includes a status code listed in the Response Codes section of Integration.

The body of the response is empty unless the message sent is of type interactive and its JSON is larger than 10 KB. To reuse an asset, use the asset reference when creating a new interactive data JSON. For more information, see Receiving an Interactive Message.

Example of a Text Message

Request

Destination-Id: "urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG/<truncated>",
Source-Id: "a884eddf-<truncated>",
Content-Type: "application/json",
id: "0c316beb-<truncated>",
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<truncated>"
{
    "body": "Hi",
    "sourceId": "a884eddf-<truncated>",
    "locale": "en_US",
    "destinationId": "urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG/<truncated>",
    "v": 1,
    "type": "text",
    "id": "0c316beb-<truncated>"
}

Response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 0
strict-transport-security: max-age=31536000
x-frame-options: DENY

Sequencing Messages

Due to its distributed nature, Messaging server may not deliver messages in the same order they are sent. If it’s essential for the user to receive messages in a particular order, the MSP platform should wait after sending a message to receive a 200 - OK response code from Messages for Business before sending the next message. This guarantees that the user’s device displays the messages in the correct order.

This sequence is useful when the MSP platform needs to send a typing indicator message before a text message. Send the typing indicator message first, then wait for the 200 - OK response code before sending the text message. If the MSP platform doesn’t wait, the text message might appear on the user’s device before the typing indicator.

Message Attachments

You can send a text message with attachments from the business to a user.

Sending Messages with Attachments

A message can include one or more attachments with a message type of text. An attachment can be an image, PDF, or other file type, and it must be smaller than 100 MB.

Messages for Business ensures that each attachment is available to the user for 30 days. If, within that 30-day period, the MSP platform sends a new message that includes a reference to an existing attachment, Messages for Business extends the attachment’s availability for another 30 days. If the user’s device is offline for 30 days or more, the device retrieves only attachments sent in the previous 30 days.

Get the Attachment Reference

An attachment sent by the MSP platform isn't included in the message JSON. Instead, the MSP platform adds a reference to the attachment in the Attachment dictionary.

To get the attachment reference, do the following:

  1. Encrypt the attachment (see Encrypting an Attachment).
  2. Authorize the attachment for upload by calling /preUpload with a GET request, passing in the size of the encrypted file attachment (see Authorizing an Attachment for Upload). This endpoint returns the upload-url and metadata about the attachment.
  3. Upload the encrypted file by sending a POST request to the upload-url, which returns a file checksum for the uploaded file (see Uploading an Attachment).
  4. Use the metadata about the attachment and the file checksum to create an Attachment dictionary, which represents the attachment reference that you include in the message JSON (see Adding Attachment Metadata to a Message).

Repeat these steps for each attachment in the array, as shown below, prior to sending the message.

“Flow
Steps for retrieving an attachment from a message

Encrypting an Attachment

You must encrypt an attachment before uploading it to Messages for Business. To encrypt an attachment, do the following:

  1. Encrypt the attachment using the AES/CTR/NoPadding algorithm with an all-zero, 16-byte initialization vector (IV).
  2. Generate a single-use 256-bit AES decryption key using a cryptographically-secure random number generator, and not a weak source like rand().
  3. Store the key as a hex-encoded string, prefixed with 00, in the key field of the Attachment dictionary in the message JSON.

Authorizing an Attachment for Upload

Get the URL needed to upload the file by authorizing the attachment for upload to Messages for Business.

Before uploading an attachment to Messages for Business, authorize the file for upload by sending a GET request to /preUpload, passing the header fields listed in the HTTP Headers section. This call returns the URL that you use to upload the encrypted file to Messages for Business.

URL

GET https://mspgw.push.apple.com/v1/preUpload

HTTP Headers

For more information, see the HTTP Headers in Common Specifications.

Response Codes

You can find the full list of Response Codes in Common Specifications.

Code Description
200 OK
preUploadResponseBody
The request was successful. See above for more information. Content-Type: application/json

Uploading an Attachment

To upload the encrypted attachment to Messages for Business, send a POST request to the URL returned by the /preUpload call (see Authorizing an Attachment for Upload), with the attachment in the body of the request.

Messages for Business returns a JSON dictionary containing the fileChecksum field. Store the value from this field in the signature-base64 key in the Attachment dictionary.

When using Server Name Indication (SNI) (RFC 6066), upload the request in a secured TLS connection to the returned upload URL. The TLS client should set the TLS server hostname from the extracted hostname for the upload URL.

Sample Attachment Upload

Request

POST [upload-url]
content-length: upload-size-in-bytes
{content is bytes of the encrypted attachment}

Response

HTTP/1.1 200 OK
content-type: application/json
{
    "singleFile": {
        "fileChecksum": "file-signature-base64-encoded"
    }
}

Adding Attachment Metadata to a Message

A text message may contain one or more attachments. To attach a file, the MSP platform uploads each attachment to the Messaging service. After uploading the attachment, the MSP platform creates the Attachment dictionary, which contains metadata representing the attachment.

The message text must have one Unicode object replacement character (\uFFFC) for each attachment in the attachments array. For example, if the message includes two attachments, the message text must contain two Unicode object replacement characters. Extra replacement characters or attachment array items are ignored.

Including the \uFFFC replacement character tells Messages where to place the attachment when the user sees the message on their device. The order of the replacement character within the text corresponds to the order of attachments in the attachment array. Messages displays the first attachment at the first replacement character, the second attachment in the array at the second replacement character, and so on.

To include an attachment in a message:

  1. Place a Unicode object replacement character (\uFFFC) at the text position where the attachment should appear in the message text.
  2. Add the Attachment dictionary to the attachments array.

Example Attachment

Request

{
    "body": "\uFFFc",
    "attachments": [{
        "name": "picture.png",
        "size": "67497",
        "mimeType": "image/png",
        "signature-base64": "AThQ82TySl <truncated>",
        "key": "005269B32EF12645D <truncated>",
        "url": "https://p54-content.icloud.com",
        "owner": "M61383834656464662d6 <truncated>"
    }],
    "sourceId": "a884eddf-<truncated>",
    "destinationId": "urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG/ <truncated>",
    "v": 1,
    "type": "text",
    "id": "9143ac3c-<truncated>"
}

Response

{The response body is empty.}

preUploadResponseBody

The response body for /preUpload is a JSON dictionary containing the following keys.

Key Type Description
upload-url string In URL format, used to upload the encrypted attachment data. For more information, see Uploading an Attachment.
url string In URL format, that identifies the attachment; assigned by Messages for Business. Use this value when setting the url key in the Attachment dictionary.
owner string The attachment owner's ID in URL format, used when setting the owner key in the Attachment dictionary.

Declaration

object preUploadResponseBody

Tutorial Exercise

For more help or guidance, see our Tutorial: Sending and Receiving Messages.