Apple Messages for Business

This chapter of our API Documentation is designed for customers who have been granted access to Apple Messages for Business. It is important that you request access to this program via our our Channels portal. Without this approval you can not make use of this part of the API.

Apple Messages for Business has a considerable set of 'business rules' that you might have to take into account when using Apple Messages for Business.)

🚧

Note

since Apple Messages for Business is used for 2-way communication (chat) it is important to also implement the Inbound flow using our API documentation of the Inbound webhook.

Sending a Apple Messages for Business message

For service requests, users initiate a conversation and will reach out to you. To link incoming messages to your outbound messages, the from/to field is used with an Apple Messages for Business message-identifier value.

An Apple Messages for Business message-identifier or the 'Opaque user identifier' as Apple calls it, is a string of alpha numerical characters that you have received as the from address in an incoming message. This is the only information you have about a user on the Apple platform. You do not receive the name, profile image, location or anything else the user has not shared themselves within conversation.

Message example

{
    "messages": {
        "authentication": {
            "productToken": "your product token"
        },
        "msg": [{
            "body": {
                "type": "auto",
                "content": "CM.com - Be part of it."
            },
            "to": [{
                "number": "Apple Messages for Business-identifier"
            }],
            "from": "TestSender",
            "allowedChannels": ["Apple Messages for Business"]
        }]
    }
}

Text messages

Text messages are and should always be encoded in UTF-8 and do support characters like emojis. This is true for both the body field and when using a text item inside a Rich Content conversation.

There is no official maximum length of an Apple Messages for Business message bubble, but up to 4096 characters is known to work. After 1024 characters, the user has to click the message to be able to read the full contents.

URL previews

Any URLs present in the message text of a Apple Messages for Business message will be automatically recognized by the clients as links. Additionally, if a message starts or ends with a URL (and begins with http:// or https://), the URL will be split off from the rest of the message and delivered as "preview url" bubble. A URL in the middle of a message will not generate a URL preview. The URL preview is retrieved by the software running on the device of the end user. For privacy reasons the preview is only generated after the consumer clicks "Tap to load Preview".

In order to have a preview image (or even preview video) without requiring the consumer to manually load it, make use of an OpenUrl suggestion instead.

Media messages

Apple Messages for Business supports all media types that the devices, such as an iPhone, itself supports.

Notes:

  • The maximum file size for uploaded media is 100MB.
  • The media name attribute should end in the proper file extension.
  • Stickers are not supported
  • Animated GIFs and media types that the device does not natively support might not directly usable by recipients

Media object contains the following fields:

TermDescription
MediaNameThe filename of the file, including file extension
MediaUriThe location of the image, audio or video.
MimeTypeThe mime type of the image, audio or video.
{
    "conversation": [
        {
            "media": {
                "mediaName": "conversational-commerce.jpg",
                "mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
                "mimeType": "image/jpeg"
            }
        }
    ]
}

As data usage costs might apply when the end user is not on Wifi, please be considerate when sending media messages. We strongly advise not to send files larger than 1 MB, and for a conversation not to exceed 20Mb.

Suggestions

Suggestions allow you to request the end user to take an action and you will receive the result of that action via the MO webhook.

Suggestions currently supported for our Apple Messages for Business Channel are: OpenUrl, Pick, Payment.

Suggestions for Apple Messages for Business are specific per conversation part and thus included inside the conversation item, instead of at the richContent level as with RCS and Viber.

OpenUrl

Sending a message with a Url action and a preview of the URL. With this method users do not have to click "Tap to preview". You can add text, a label, the url and media items to your conversation part.

Message example

{
    "messages": {
        "authentication": {
            "productToken": "your product token"
        },
        "msg": [
            {
                "richContent": {
                    "conversation": [{
                        "text": "CM.com - Be part of it.",
                        "suggestions": [
                            {
                                "action": "OpenUrl",
                                "label": "CM.com - Be part of it.",
                                "url": "https://www.cm.com/products/talk/",
                                "media": {
                                    "mediaName": "cm-com.png",
                                    "mediaUri": "https://www.cm.com/cdn/cm/cm-com.png",
                                    "mimeType": "image/png"
                                }
                            }
                        ]
                    }]
                },
                "body": { "content": "CM.com - Be part of it." },
                "from": "CM Test",
                "allowedChannels": ["Apple Messages for Business"],
                "to": [
                    { "number": "Apple Messages for Business-identifier" }
                ]
            }
        ]
    }
}

List picker

With a list picker you can present a button in the conversation that when clicked presents a list of options to the users. These lists can have labels and a media thumbnail.

🚧

Note

Don't send images that are exceptionally large as the download time, may influence the time it takes to present the options to the user.

When the user makes a choice the response will be sent back to you via the MO webhooks.

Message example

{
    "conversation": [
    {
        "text": "Magic trick",
        "listpicker": {
            "label": "Please, pick a card",
            "media": {
                "mediaUri": "https://static.thenounproject.com/png/393234-200.png"
            },
            "options": [
                {
                    "label": "Ace of Hearts",
                    "media": {
                        "mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Ftse1.mm.bing.net%2Fth%3Fid%3DOIP.N7zZqoCvjxZZvwp2Zi1UVwHaH6%26pid%3D15.1&f=1"
                    }
                },
                {
                    "label": "Ace of Spades",
                    "media": {
                        "mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Fcdn.pixabay.com%2Fphoto%2F2013%2F07%2F12%2F12%2F01%2Fsuit-of-spades-145116_960_720.png&f=1"
                    }
                },
                {
                    "label": "Ace of Diamonds",
                    "media": {
                        "mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Fcdn.pixabay.com%2Fphoto%2F2012%2F05%2F07%2F18%2F37%2Fsuit-48941_960_720.png&f=1"
                    }
                },
                {
                    "label": "Ace of Clubs",
                    "media": {
                        "mediaUri": "https://proxy.duckduckgo.com/iu/?u=https%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fcommons%2Fthumb%2F8%2F8a%2FSuitClubs.svg%2F709px-SuitClubs.svg.png&f=1"
                    }
                }
            ]
        }
    }
    ]
}

The text element of the message will be shown in the message, the label element in the list picker will be shown in the list picker.

Quick replies

A quick reply makes it easy for end users to select one of the options you present them.

When the user makes a choice the response will be sent back to you via the MO webhooks.

Message example

{
    "conversation": [
    {
        "listpicker": {
            "label": "a CM conversational product",
            "options": [
                {
                    "label": "Communication Platform as a Service"
                },
                {
                    "label": "Mobile Marketing Cloud (MMC)"
                },
                {
                    "label": "Mobile Service Cloud (MSC)"
                },
                {
                    "label": "Conversational AI Cloud"
                }
            ]
        }
    }
    ]
}

Time and date picker

With a time and date picker you can present a button in the conversation that when clicked presents a list of time and dates to the user to pick from. This is a good method to plan meetings and/or delivery times.

When the user makes a choice the response will be sent back to you via the MO webhooks.

In order to setup a time picker, you submit a timePicker object with an options array containing the suggested date and time slots for the user to pick from.
Optionally you can add a label and location which will be used when an end users add the appointment to the calendar.

Message example

    "conversation": [
        {
            "text": "Click here to pick a time.",            
            "timePicker": {
                "label": "Appointment at CM HQ",
                "location": {
                    "latitude": "51.603802",
                    "longitude": "4.770821",
                    "label": "CM HQ"
                },
                "options": [
                    {
                        "startTime": "2020-02-21T09:00",
                        "endTime": "2020-02-21T10:00"
                    },
                    {
                        "startTime": "2020-02-22T09:00",
                        "endTime": "2020-02-22T10:00"
                    },
                    {
                        "startTime": "2020-02-23T09:00",
                        "endTime": "2020-02-23T10:00"
                    }
                ]
            }
        }
    ]

Note that the start time must always be in the future.

Authentication

It is possible to do an OAuth 2 authentication within a conversation. Using the OAuth2 authentication prompt, you can ask a user to login via a 3th party website. Authentication results are received via the MO webhooks.

The 3th party must be configured in the Apple Messages for Business account on the Apple Business Register.

Message example

"conversation": [
    {
        "oauth2": {
            "responseType": "token",
            "state": "3a77fc39-ac33-404f-896a-e0fad171a343",
            "responseEncryptionKey": "SOME LONG ENCRYPTION KEY",
            "clientSecret": "SOME CLIENT SECRET",
            "scope": ["email","profile","openid"]
        }
    }
]

Other

It is also possible to make a payment using Apple Pay. Setting this up requires some custom work and we therefor ask you to contact our support team.

If you have your own app and want to have your own Apple Messages for Business integrations than this is possible as well. Again, please contact our support team.


Did this page help you?