Apple Messages for Business REST API Common Specifications

Common Specifications

The following specifications, such as HTTP headers, HTTP body, and other similar fields, are common to all messages. This includes specialized messages such as rich links and pickers. Differences are pointed out in their respective section.

URL

Implement the /message endpoint to send and receive messages.

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

HTTP Headers

Name	Type	Description
`Authorization`	string	REQUIRED. Credentials used to authenticate the request. See Authorizing Messagess.
`auto-reply`	string	A Boolean that determines whether the reply is sent by a person or an automated agent (bot). Set the value to `true` when a bot sends the reply.
`capability-list`	string	REQUIRED. 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 must obtain the customer device capabilities to compose an appropriate response for that device. The agent console should not permit sending a payload to a user that is not supported by the user's device. Bots should use these values to automatically determine which payload type to send. 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. Apple Pay, Rich Links are supported on all devices type and version. iMessage apps and Forms are only supported on iPhone and iPad.
`destination-id`	string	REQUIRED. A string that identifies the message recipient. When a user sends a message, the `destination-id` is the business ID. When a business sends a reply to the user, the value is the user’s opaque ID.
`id`	`uuid`	REQUIRED. A UUID string that identifies the message.
`msp-agent`	string	A string that identifies the agent or system sending the request. The MSP platform should set the field to a string value that is meaningful to the business. Apple Messages for Business logs up to the first 64 characters of the string.
`source-id`	string	REQUIRED. A string that identifies the message sender. When a user sends a message, the `source-id` is the user’s opaque ID. When a business sends a reply to the user, the `source-id` is the business ID.
`accept-encoding`	string	Applicable to Interactive Message Type. A string value, set to `gzip, deflate`, advertising which content encoding, usually a compression algorithm, the client understands.
`accept`	string	Applicable to Interactive Message Type. A string value, set to `/`, advertising which MIME types the client understands.
`content-type`	string	Applicable to Interactive Message Type. A string value, set to `application/octet-stream`, advertising that the content is a generic binary data.
`owner`	string	Applicable to Getting Attachment URL. REQUIRED. The owner of the attachment. Retrieve this field's value from the owner field in the Attachment dictionary.
`signature`	byte	Applicable to Getting Attachment URL. REQUIRED. A Base64-encoded string containing the file checksum.
`url`	string	Applicable to Getting Attachment URL. REQUIRED. The URL, provided by Apple Messages for Business, that identifies the attachment.
`size`	integer	Applicable to Authorizing an Attachment for Upload. REQUIRED. An integer representing the size, in bytes, of the encrypted attachment.

HTTP Body

All messages, except the /preUpload and /preDownload messages, include the fields from the HTTP Body dictionary.

Properties

Name	Type	Description
`attachments`	attachments	An array of attachment dictionaries. For more information, see Attachments.
`destinationId`	string	REQUIRED. Identifies 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.
`id`	uuid	REQUIRED. A UUID string that identifies the message.
`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.
`locale`	string	User's device locale settings. For example, `en_AU` specifies the language as English and the region as Australia. For more information, see Internationalization and Localization Guide - Locale ID.
`sourceId`	string	REQUIRED. A string that identifies the message sender. When a user sends a message, the `source-id` is the user’s opaque ID. When a business sends a reply to the customer, the `source-id` is the business ID.
`type`	string	REQUIRED. A string that identifies the message type. For the list of possible values and their meanings, see Message Type Values. Possible values: `interactive`, `typing_start`, `typing_end, text`.
`v`	integer	REQUIRED. The message payload version number. This value must be 1, which is the current version of the message JSON.

About the Opaque ID

For privacy, the business doesn’t receive the user’s phone number, email address or iCloud account information. The Opaque ID is unique to the relationship between the customer's Apple ID and the business’s business ID. A customer has a different Opaque ID for every chat they have using Apple Messages for Business. The customer decides if and when to share personal identifying information with the business. For more information, see Apple Platform Security.

Response Codes

Code	Reason-Phrase
`200`	`OK` The request was successful. `Content-Type: application/json`
`400`	`Bad Request` The request lacks the required header fields, the request body isn't JSON or the JSON lacks the required fields, or the `destination-id` header field does not match the `destinationId` JSON field.
`401`	`Unauthorized` The request lacks the `Authorization header` field. Requests from Messaging service always contain the Authorization header field. If the MSP platform returns a 401 response code, the problem is either a configuration issue with Apple Messages for Business or a signal of spoofed incoming activity.
`403`	`Forbidden` The request failed to validate the `Authorization` header field. If the MSP platform sends a request to Messaging service and it responds with `403 - Forbidden`, it’s likely in response to an invalid MSP ID in the `Authorization` header field.
`404`	`Not Found` The request failed to recognize the `destination-id` or was sent to a user no longer available. These errors occur when a business messages a user during their iPhone or device upgrade cycle. The carrier has an inactivated status on the SIM card for a particular device. Our messaging systems have the user account marked as messageable and active but the error comes back from the carrier network. Once the upgrade cycle is complete, users will again receive messages without any further work for the MSP or the user. They will not, however, receive messages that were returned as 404. We recommend those be sent again or marked in your system as undelivered.
`410`	`Gone` The request failed because the user closed the conversation. For more information, see Receiving a close conversation.
`500`	`Internal Server Error` A server error occurred. An additional response could be `50x - various`. This means that the request encountered various server-side failures. The bot and/or agent needs to be notified that message delivery failed and provide an opportunity to resend the message.

Note

Only 5xx errors are retried. Apple will retry 4 times with an exponential backoff, starting with 100ms. All other errors fail immediately.

TypingIndicatorMessage

Forward indicators from Apple Messages for Business when someone is entering text in Messages.

In a conversation, typing indicators provide visual cues to let each person know when the other is entering text. When receiving messages, the Apple Messages for Business service sends the MSP platform a typing indicator each time the user starts entering text in Messages. The MSP platform receives the typing indicator as a message with the type of typing_start. After receiving the typing indicator message, the MSP platform should display the indicators to the person receiving the message.

If the user clears the text they entered, Apple Messages for Business sends a typing_end message to the MSP platform. The MSP platform should remove the visual indicator, which tells the business that the user stopped entering text and is no longer preparing to send a text message.

Likewise, when an agent, live or automated, starts or stops typing, a message of type typing_start and/or typing_end must be sent, so the user can also see the typing indicator and the experience is consistent.

The typing indicador should be displayed before any message type (text or interactive), so that the user experience is consistent. For messages sent by bots, use only a 1-second typing indicators before each message.

This behavior is not the same as a message type close. For more information, see Receiving Closed Conversation Messages.

Note

You can have a timeout for the typing indicator, if the typing_end is not received within 60 seconds.

Declaration

This object inherits from HTTP body.

object TypingIndicatorMessage

Tapback Reactions

Sometimes users respond to messages using a Tapback, such as the heart or thumbs up expressions. Following is the Tapback workflow:

Agent sends a message to the user.
User uses the Tapback feature to react to the message using the thumbs-up or laughter expressions.
Apple Messages for Business sends back a text message to the agent console that is parsable as a Tapback.

The Tapback message encloses the original message text within unicode double quote characters with the type of reaction indicated in text.

For example, an agent would see the following message in their console when responding using an expression.

Liked "Thank you, Mr. Smith."

Just show the text message received and don’t try to convert it as a tapback reaction on the agent console.

Because the reaction is both language and text direction dependent, this can make parsing the Tapback message challenging. For example, if the language on the user device is set to Japanese, the Tapback message arriving at the agent console might look like this:

"Domo arigato, Smith-san."に「いいね」と応答

Actual response example:

Liked a text

{ 
  "type": "text",
  "id": "ce5e8c7c-ade6-4495-b373-4c94f44b123c",
  "v": 1,
  "sourceId": "urrnXXXXXXXXX",
  "destinationId": "4c2deaac-b192-41a3-b5e1-1107dac55014",
  "body": "Liked “hiiiii”" 
}

Liked an image

{
 "type": "text",
 "id": "ce5e8c7c-ade6-4495-b373-4c94f44b123c",
 "v": 1,
 "sourceId": "urrnXXXXXXXXX",
 "body": "Liked an image",
 "destinationId": "4c2deaac-b192-41a3-b5e1-1107dac55014"
}

Liked a text in Japanese locale

{
  "type": "text",
  "id": "ce5e8c7c-ade6-4495-b373-4c94f44b123c",
  "v": 1,
  "sourceId": "urrnXXXXXXXXX",
  "destinationId": "4c2deaac-b192-41a3-b5e1-1107dac55014",
  "body": "“hiiiii ”に「いいね」と応答"
}

Group and Intent ID-based Routing

Businesses have the option to set up the Apple Messages button using a plain URL, web button, in-app button, QR code, or NFC, and pass three values intentID, groupID, and body.

Your platform needs to route new conversations using intentID and groupID values from an entrypoint, as well as the default body parameter. See the following documentation for more information: