{
  1. Introduction
    1. Prerequisites
    2. Channels
  2. Integration
    1. SDKs
    2. API endpoints
    3. Authentication
    4. Encryption
    5. Receiving messages
  3. Shared Features
    1. Sending messages
    2. Batching
    3. Channel fallback
    4. Validity period
    5. Rich content
    6. Responses & Errors
  4. SMS
    1. Unicode
    2. Multipart
  5. WhatsApp
    1. Encryption
    2. Sending messages
    3. Text message
    4. URL previews
    5. Template message
    6. Media message
    7. Location message
    8. Contact message
    9. Interactive message
  6. Twitter
    1. Fact sheet
    2. Onboarding
    3. Business rules
    4. Considerations
    5. Sending messages
    6. Receiving messages
    7. Examples
  7. Facebook Messenger
    1. Fact sheet
    2. Onboarding
    3. Business rules
    4. Considerations
    5. Sending messages
    6. Receiving messages
    7. Examples
  8. Instagram Messaging
    1. Fact sheet
    2. Prerequisites
    3. Onboarding
    4. Business rules
    5. Considerations
    6. Sending messages
    7. Handover protocol
    8. Receiving messages
    9. Examples
  9. Google Business Messages
    1. Fact sheet
    2. Onboarding
    3. Business rules
    4. Considerations
    5. Sending messages
    6. Receiving messages
    7. Examples
  10. Apple Business Chat
    1. Sending messages
    2. Text message
    3. URL previews
    4. Media message
    5. Suggestions
  11. RCS
  12. Viber
  13. Push
    1. Fact sheet
    2. Notifire
    3. Onboarding
    4. Integration
    5. Business rules
    6. Considerations
    7. Migrating from Hybrid Push
    8. Sending messages
    9. Receiving messages
    10. Examples
  14. Status Reports
  15. SMPP
  16. XML
  17. Http Get-requests
  18. Glossary
  19. Conversion API

Apple Business Chat

This chapter of our API Documentation is designed for customers who have been granted access to Apple Business Chat (ABC). 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 Business Chat has a considerable set of 'business rules' that you might have to take into account when using Apple Business Chat.)

Note: since Apple Business Chat 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 Business Chat 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 ABC-identifier value.

An ABC-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": "ABC-identifier"
            }],
            "from": "TestSender",
            "allowedChannels": ["Apple Business Chat"]
        }]
    }
}

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 Business Chat 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 Business Chat 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 Business Chat supports all media types that the 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 iPhone does not natively support might not directly usable by recipients

Media object contains the following fields:

Term Description
MediaName The filename of the file, including file extension
MediaUri The location of the image, audio or video.
MimeType The 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 Business Chat Channel are: OpenUrl, Pick, Payment.

Suggestions for Apple Business Chat 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 Business Chat"],
                "to": [
                    { "number": "ABC-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.

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 Business Chat 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 Business Chat integrations than this is possible as well. Again, please contact our support team.