Text Message Type

When a customer sends a simple text message to a business, the Messaging service receives and forwards the message to the Messaging Service Provider (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 Integrating with Apple Messages for Business.

In addition to the Common Specifications, the following Dictionary keys are also used for sending and receiving messages.

Properties

Name Type Description
body string REQUIRED. The message body

Attachments

By default Apple Messages for Business supports file attachments up to 100MB between your platform and the user. Apple Messages for Business supports commonly known file types, such as .doc, .xls, .xlsx, .pdf, and .ics.

In addition, the following specialized file types are supported.

Extension Definition MIME Type
.caf Voice audio recording, usually sent from end user device audio/x-caf
.pkpass Wallet pass for events, loyalty, or NFC pass application/vnd.apple.pkpass
.usdz Augmented Reality object, common on iOS, which can be sent by an agent or automation to end user vnd.usdz+zip

You can find demo files for these types as follow:

Apple Messages for Business doesn't reject messages due to the MIME type. The messaging platform determines which mime type to support and validate for the business. For more information about adding an attachment to a message, see Adding Attachment Metadata to a Message

In addition to the Common Specifications, the following Dictionary keys are also used for sending and receiving messages with attachments.

Properties

Name Type Description
key binary The single-use, 256-bit AES key represented as a hex-encoded string. To decrypt a downloaded attachment file using key, remove the 00 prefix from the hex-encoded string, then decode the string into its original value. Use the decoded key value to decrypt the downloaded attachment file.
mimeType string The MIME type
name string The name of the file
owner integer The owner of the attachment
signature binary The file checksum, represented as a hex-encoded string.
signature-base64 byte The file checksum, represented as a Base64-encoded string..
size integer The size of the encrypted attachment, in bytes..
url string A URL assigned by Messages for Business to identify the attachment.

Sending Text Messages

When a business replies to a user’s message, the MSP platform first sends the message to the /v1/message endpoint. Messages for Business then validates the incoming message and returns the appropriate response code (see the "Response Codes" section in Common Specifications). Next, the Messaging service delivers the text message to the user’s device.

“Text
Text message type received on a device

You can ensure a quick and responsive experience by setting the timeout for the HTTP request to 30 seconds. If Messages for Business doesn’t return a response code within that time, cancel the request and try again later.

Sample Text Message Payload without Attachments

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

Tutorial Exercise

For more help or guidance, see our Tutorial: Exercise: Sending a Text Message.