Apple Messages for Business REST API Messages Received

Incoming Messages

Your Messaging Service Provider (MSP) platform can receive an incoming message sent by a user through Apple Messages for Business, by implementing the /message endpoint. In the implementation, you can setup your MSP platform to validate the message (see Validating a Message) and deliver it to the business identified by the destinationId field (see Routing and Prioritizing Messages).

Request

POST https://msp.example.com/message

Parameters

The request body is a JSON dictionary that, in addition to the HTTP Body parameters, contains the following fields:

Name	Description
`body`	REQUIRED. The message text. This field is required when the type is `text`. There is no predetermined maximum for this field, but there may be a maximum size for the payload. This field supports the Basic Multilingual Plane of unicode. For more information, see `TextMessage`.
`interactiveData`	A dictionary representing the properties of an interactive message. For more information, see `BaseInteractiveData` dictionary for more information.
`interactiveDataRef`	A dictionary containing a reference to the interactive data dictionary. Apple Messages for Business includes this field, instead of interactiveData, when the interactive data dictionary is larger than 10 KB. For more information, see Receiving an Interactive Message.

Message Type Values

When a user sends a text message to a business, the Messaging service receives and forwards the message to the MSP platform by calling the MSPs platform /message endpoint. The message type is set to text.

The MSP platform validates the incoming message as described in Validating a Message. The /message endpoint then returns the appropriate response code to Apple Messages for Business. For a list of possible codes, see the Response Codes section in Common Specifications.

The possible string values for the message type field are:

Name	Description
`text`	REQUIRED. Indicates that this is a text message, with or without attachments.
`interactive`	REQUIRED. Indicates that this is an interactive message. This could be a list picker, time picker, or any other interactive message. For more information, see Interactive Message Types
`typing_start`	REQUIRED. Indicates that the user is actively entering text in Messages.
`typing_end`	REQUIRED. Indicates that the user cleared the text they were entering.
`close`	REQUIRED. Indicates that the user closed the chat. Only a user can close a chat. The MSP platform should not send a message with the type set to `close`. For more information, see Receiving Closed Conversation Messages.

Sample Message Received

This is a user communication sent from the Apple Messages for Business service to an MSP platform.

Request

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9. <truncated>
Content-Length: 300
Destination-Id: a884eddf-<truncated>
Content-Encoding: gzip
Capability-List: AUTH,LIST,TIME,QUICK
X-Http2-Scheme: https
Host: http://msp.messagesforbusinessendpoint.com:443
Source-Id: urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG/ <truncated>
Content-Type: application/json
Id: 27167455-1f53-4ddc-a797-318ad85cb28e
{
    "body": "Hi",
    "sourceId": "urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG/ <truncated>",
    "locale": "en_US",
    "destinationId": "a884eddf-<truncated>",
    "v": 1,
    "type": "text",
    "id": "27167455-1f53-4ddc-a797-318ad85cb28e"
}

Response

HTTP/1.1 200 OK
Date: Fri, 05 Apr 2019 20:43:49 GMT
Server: Apache/2.4.7 (Ubuntu)
Content-Length: 0
Content-Type: text/html; charset=utf-8

Validating a Message

When the MSP platform receives a message, you must use the MSP platform secret to validate the message by performing the following checks:

Verify that the destination-id field in the HTTP request header matches a valid business ID. If the MSP platform is multitenant, verify that the business exists within the MSP platform system and can accept incoming messages from Apple Messages for Business.
Validate the Authorization header field using the MSP platform secret. For more information, see Authorizing Messages.
Check for required HTTP request header fields. For more information, see the HTTP Headers section in Common Specifications.
Verify that the HTTP body is a valid GZIP formatted object and reverse the compression ("gunzip") to reveal the JSON payload.
Verify that the resulting text resolves to a valid JSON data payload.

Routing and Prioritising Messages

Each incoming message includes a list of fields useful for routing and prioritizing messages. When the MSP platform sends a message to Apple Messages for Business that includes any of these fields, Apple Messages for Business returns the fields in the user’s reply:

Name	Type	Description
`body`	string	A text field that prepopulates the message body. It can be overwritten and changed by the user.
`capability-list`	string	A string list that identifies Apple Messages for Business features supported by the customer’s device. The list items are case insensitive and separated by commas. When a customer sends a message, the MSP platform can obtain the customer device capabilities to compose an appropriate response for that device. Possible values are: - `QUICK` for Quick Reply Message support - `LIST` for List Picker Messsage support - `TIME` for Time Picker Messsage support - `AUTH` for Authenticate Message support - `AUTH2` for New Authentication Message Message support - `FORM` for Forms Message support
`destinationId`	string	The identifier for the message recipient. When the MSP platform receives a message from Apple Messages for Business, the value is the business ID. When the MSP platform sends a reply to Apple Messages for Business, the value is the user’s opaque ID.
`group`	string	The group identifier for the message as specified by the business, such as the department name. For more information, see About Intent, Group, and Body Values. This field is optional.
`intent`	string	The intention, or purpose, of the chat as specified by the business, such as `account_question`. For more information, see About Intent, Group, and Body Values. This field is optional.
`locale`	string	The user's device locale settings. For example, `en_AU` specifies the language as English and the region as Australia.
`sourceId`	string	The identifier for the message sender. When the MSP platform receives a message from Apple Messages for Business, the value is the user’s opaque ID. When the MSP platform sends a reply to Apple Messages for Business, the value is the business ID.
`capabilities`	string	(Deprecated March 2022) A string list that identifies Apple Messages for Business features supported by the user’s device. The list items are case insensitive and separated by commas. When a user sends a message, the MSP platform can obtain the user device capabilities to compose an appropriate response message for that device. Possible value is auth for authenticate message support.

Receiving a Closed Conversation

Users can opt out of receiving any further messages from a brand. This is also known as closing a conversation.

A user closes a conversation by going to the tray view in Messages and left swipe a conversation. This action reveals two buttons: a mute icon and a delete icon. The user clicks the delete icon, agrees to delete the conversation, and confirms that they would you like to stop receiving messages from the business. This action sends a “close” message for an Apple Messages for Business conversation. Apple refers to this action as “delete” on the user's device, and the MSP and brand receive a “close” conversation from the standpoint of the brand and MSP.

Note that when the user deletes the conversation and does not ask to stop receiving messages from the business, no “close” message is sent to the MSP.

iPhone showing how to stop receiving messages — Communicate with users using Apple Messages for Business

When a user closes a conversation, Apple Messages for Business sends a message of type close to your MSP platform, and your platform must block any agent, virtual or live, to send any further messages to this user. If you try to send a message to this user, Apple Messages for Business sends an HTTP 410 | Gone response. We require MSPs to keep a table of closed conversations and prevent brands from sending messages to users who have opted out.

The user can re-initiate the conversation. They can resume the conversation from any valid entry-point for the brand. When they do, they will return with the same opaque user ID as before.

If the user chooses to stop receiving messages, Apple Messages for Business considers the conversation closed and sends a message of type close to the MSP platform.

{
    "id": "UUID-IDENTIFIER-FOR-MESSAGE",
    "sourceId": "OPAQUE-USER-ID",
    "destinationId": "BUSINESS-ID",
    "type": "close",
    "v": 1
}

You can send and receive message attachments when conversing with users.

Receiving a Text Message with an Attachment

An incoming text message may include one or more attachments. The MSP platform should process the message as described in TextMessage, but with the additional step of downloading the attachments. If the attachment size is larger than 10 KB, see Receiving an Interactive Message.

Any file type that can be sent as a binary can be sent by Apple Messages for Business. Binary files are considered successfully sent and viewable if the end device has the Messages app installed and can use the file.

Check the Incoming Message for Attachments

Always check for and download attachments after returning a response code to Apple Messages for Business. Check for attachments by inspecting the attachments array, which contains a list of Attachment dictionary objects, such as the url, signature-hex (hex-encoded signature), owner, and key. (A library converts the hex-encoded signature into a Base64-encoded signature.) Download each attachment by doing the following:

Retrieve the URL by obtaining the URL, Base64-encoded signature, owner keys from the initial attachment receipt, and use a GET request to the /preDownload endpoint (see Getting an Attachment's URL).
Download the attachment by sending a GET download-url request to the attachment URL.
Use the key to decrypt the downloaded file (see Downloading and Decrypting an Attachment).

Repeat the steps in the loop for each attachment listed in the attachments array, as shown in the diagram below.

“Flow — Steps for retrieving an attachment from a message

Getting an Attachment’s URL

To retrieve an attachment's URL, use the information contained in the Attachment dictionary to call the /preDownload endpoint. The endpoint returns a temporary URL that you call to download an encrypted file containing the attachment.

URL

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

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` The request was successful. `Content-Type: application/json`, see preDownloadResponseBody.

Response

The response body is a JSON dictionary that contains the following key.

Key	Description
`download-url`	The URL to the file. Make a `GET` request to this URL to download the attachment.

Example of a Received Message with Attachments

The following code example contains two attachments. When there is more than one attachment, they are displayed within an array.

Request

{
    "body": "\ufffc\ufffc",
    "attachments": [{
            "mimeType": "image/png",
            "name": "IMG_2103.PNG",
            "url": "https://p50-content.icloud.com/<truncated>",
            "mime-type": "image/png",
            "owner": "Murn%3Ambid%3A33c32473476ca07d893.<truncated>",
            "key": "00A155FD83F85B008957DEB918 <truncated>",
            "signature": "81C16E7AE89C5F98F1B <truncated>",
            "size": 205883
        },
        {
            "mimeType": "image/png",
            "name": "IMG_2065.PNG",
            "url": "https://p46-content.icloud.com/<truncated>",
            "mime-type": "image/png",
            "owner": "Murn%3Ambid%3A33c32473476ca07d89 <truncated>",
            "key": "00183E442B6779E08E0425543C <truncated>",
            "signature": "814C28F63E13501B71876 <truncated>",
            "size": 233488
        }
    ],
    "sourceId": "urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG <truncated>",
    "locale": "en_US",
    "destinationId": "a884eddf-<truncated>",
    "v": 1,
    "type": "text",
    "id": "b07c4587-<truncated>"
}

Response

HTTP/1.1 200 OK
content-type: application/json
{
  "content-length": "291",
  "content-encoding": "gzip",
  "strict-transport-security": "max-age=31536000",
  "cache-control": "no-cache, no-store",
  "x-frame-options": "DENY",
  "content-type": "application/json"
}
{
  "download-url":"https://cvws.icloud-content.com/M/<truncated>"
}

Example of GET /preDownload

Request

GET   https://mspgw.push.apple.com/v1/preDownload HTTP/1.1
predownload_headers = {        
        "authorization": "Bearer %s" % get_jwt_token(),
        "source-id": BIZ_ID,
        "url": mmcs_url,
        "signature": base64_encoded_signature,
        "owner": mmcs_owner
    }
{empty body}

Response

HTTP/1.1 200 OK
content-type: application/json
{
  "download-url": "https://content.example.com/file-id"
}

Downloading and Decrypting an Attachment

Before sending an attachment to the business, the MSP platform needs to download it using an HTTP request, then decrypt it using a cypher library. After decrypting the attachment, the MSP platform can forward the message to the business.

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

First, download the attached file by sending a GET request to the URL returned by /preDownload. This request returns an encrypted file.

Then, using a cypher library, decrypt the file by using the AES/CTR/NoPadding algorithm with an all-zero, 16-byte initialization vector (IV) with the key value in the Attachment dictionary for the downloaded attachment.

Finally, forward the message with the decrypted attachment to the business.

preDownloadResponseBody

Response body should be empty.

Declaration

object preDownloadResponseBody

Tutorial Exercise

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

Incoming Messages

Request

Parameters

Message Type Values

Sample Message Received

Validating a Message

Routing and Prioritising Messages

Receiving a Closed Conversation

Message Attachments

Receiving a Text Message with an Attachment

Check the Incoming Message for Attachments

Getting an Attachment’s URL

URL

HTTP Headers

Response Codes

Response

Example of a Received Message with Attachments

Example of GET /preDownload

Downloading and Decrypting an Attachment

preDownloadResponseBody

Declaration

Tutorial Exercise