Apple Messages for Business

Our business messaging API supports sending and receiving Apple Messenger for Business messages.

Being able to send Apple Messenger for Business direct messages requires requesting access via the Channels portal. Without onboarding Apple Messenger for Business via the portal, you can not make use of this part of the API.

Fact Sheet

Feature	Support	Remarks
delivery notification	yes	Occurs when your message is delivered to the Apple platform. Delivery notifications are sent to the status report webhooks.
text messages	yes	The maximum length of a message is 4096 characters and it must be UTF-8 encoded.
media	yes	Media name attribute should end in the proper file extension. Only one media file is allowed per message; when sending multiple files, each file will be sent in its own message. When the linked media doesn't exist/can't be found, the message will not be sent at all. The provided text message is sent in a separate message.
media: images	yes	Maximum file size for an uploaded image is 100 MB.
media: gif	yes	Maximum file size for an uploaded gif is 100 MB.
media: audio	yes	Maximum file size for an uploaded audio file is 100 MB.
media: video	yes	Maximum file size for an uploaded video file is 100 MB.
media: documents	yes	Maximum file size for an uploaded file is 100 MB.
reply suggestions	yes	Max 5 reply suggestions
list picker	yes	Will be converted to quick replies when no media is provided.
time picker	yes
app extension	yes	Requires details about iMessage app.
form message	yes
authentication message	yes	Requires 3rd party OAuth 2.0 supplier.
payment message	yes	Requires payment integration.

Business rules

Sending Apple Messages for Business using the CM Business Messaging API also requires you to adhere to the Apple Messages for Business channel policies.

Considerations

The only way to have an Apple Messages for Business conversation with end-users is when the end-user starts the conversation by sending you an initial message.

Sending messages

Unlike other channels, Apple Messages for Business does not use telephone numbers as identifiers for sender (from) and recipient (to.number).
Instead, it uses a so-called "Conversation ID" for the recipient and a "Business Account ID" for the sender.

Text

The example below will send a simple text-only Apple Messages for Business message.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "body": {
          "type": "auto",
          "content": "Be part of it."
        }
      }
    ]
  }
}

URL previews

Any URLs present in the message text of an 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.

For privacy reasons, the preview is only generated after the consumer clicks "Tap to load Preview".

In order to have a preview image (or a 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.

Display order

If you send a message including both an image and some text, Apple Messages for Business will display these as separate messages; typically the text will be the first message.

Direct message with text and image

In the example below we send a simple rich content message that contains both text and an image that Apple Messages for Business will display as two separate messages.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "richContent": {
          "conversation": [
            {
              "text": "Be part of it.",
              "media": {
                "mediaName": "cm.png",
                "mediaUri": "https://www.cm.com/cdn/cm/cm.png",
                "mimeType": "image/png"
              }
            }
          ]
        }
      }
    ]
  }
}

Quick replies

Quick replies provide a way to suggest quick answers beneath your message for users to reply with.
A minimum of 2 quick replies is required up to a maximum of 5 quick replies. Quick replies only support plain text.

🚧
Note
Quick replies via suggestions like other channels is not supported as of yet.
Use list picker property to provide the quick reply options.

Direct message with quick reply suggestions

In the example below we send 2 rich content messages that contain a text and some reply suggestions.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "text": "Which product would you like more info about?",
              "listpicker": {
                "options": [
                  {
                    "label": "Communication Platform as a Service"
                  },
                  {
                    "label": "Mobile Marketing Cloud (MMC)"
                  },
                  {
                    "label": "Mobile Service Cloud (MSC)"
                  },
                  {
                    "label": "Conversational AI Cloud"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

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.

Direct message with open URL

In the example below we send 2 rich content messages that contain a text and open URL suggestion.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "text": "Visit our website",
              "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"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

List picker

Allow the end-user to choose from a list of items. The end-user can choose one or more items that can contain an optional image and description.

Sending a list picker requires the usage of a preview message, a message the end-user first needs to press in order to open the list picker. Please use text which makes it clear the end-user needs to press the message.

List picker definition

Field	Required	Remarks
label	yes	Title of list picker page.
multipleSelection	no	Flag indicating if the end-user can select multiple options.
media	no	Media to use in list picker preview message.
options	yes	List of options. See definition for option down below.

Option definition

Field	Required	Remarks
label	yes	Title of option.
media	no	Media to use for option.

Direct message with list picker

In the example below we send a rich content message that contains text for a preview message and details for a list picker.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "text": "Magic trick",
              "listpicker": {
                "label": "Please, pick a card",
                "multipleSelection": true,
                "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"
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

Time picker

Allow the end-user to pick a time slot when scheduling a meeting or appointment. When location information is included, the end-user can choose afterwards to get directions to the location or add the event to their local calendar. Note that the dates must always be in the future.

Sending a time picker requires the usage of a preview message, a message the end-user first needs to press in order to open the time picker. Please use text which makes it clear the end-user needs to press the message.

Time picker definition

Field	Required	Remarks
label	yes	Title of time picker page.
media	no	Media to use in time picker preview message.
location	no	Location details. See definition down below.
options	yes	List of time options. See definition down below.

Location definition

Field	Required	Remarks
label	yes	Title of location.
longitude	yes	A double representing the longitude of the location.
latitude	yes	A double representing the latitude of the location.
radius	no	Location radius. Default: 1 meter

Option definition

Field	Required	Remarks
startTime	yes	Start time of time slot in UTC format.
endTime	yes	End date of time slot in UTC format.

Direct message with time picker

In the example below we send a rich content message that contains text for a preview message and details for a time picker with location information.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "text": "Click here to pick a time.",
              "timePicker": {
                "label": "Appointment at CM HQ",
                "media": {
                  "mediaUri": "https://static.thenounproject.com/png/393234-200.png"
                },
                "location": {
                  "latitude": "51.603802",
                  "longitude": "4.770821",
                  "label": "CM HQ"
                },
                "options": [
                  {
                    "startTime": "2023-04-21T09:00Z",
                    "endTime": "2023-04-21T10:00Z"
                  },
                  {
                    "startTime": "2023-04-22T09:00Z",
                    "endTime": "2023-04-22T10:00Z"
                  },
                  {
                    "startTime": "2023-04-23T09:00Z",
                    "endTime": "2023-04-23T10:00Z"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

App extension

An app extension allows you to send an interactive message that opens an iMessage app or extension.

In order to make use of an app extension, you'll need to provide the Team ID and Extension/App ID of the iMessage app.

App extension definition

Field	Required	Remarks
teamId	yes	The Team ID is a unique 10-character string generated by Apple that’s assigned to your team. To find your Team ID, sign in to your Apple developer account and click “Membership details.”
extensionId	yes	Identifier of iMessage extension/app

Direct message with app extension

In the example below we send a rich content message that contains text and details of an iMessage app.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "text": "Play Tic-Tac-Toe",
              "appExtension": {
                "teamId": "CQK2JTBXXJ",
                "extensionId": "nz.co.daru.morpion.Extension"
              }
            }
          ]
        }
      }
    ]
  }
}

Form message

A form message allows you to create rich, multipage questionnaire for users. A form can consist out of a splash page and requires 1 or more pages that contain a question.

There are 4 different kinds of pages possible:

Select - Page where the end-user can select 1 or multiple predefined answers with support for images.
Picker - Page where the end-user can select 1 predefined answer that doesn't support images.
Date picker - Page where the end-user can select a date in a calendar view.
Input - Page where the end-user can leave a custom answer.

It is advised to use less complicated use cases that provide quick answers.

Sending a form message requires the usage of a preview message, a message the end-user first needs to press in order to open the form message. Please use text which makes it clear the end-user needs to press the message.

Form definition

Field	Required	Remarks
splash	no	Splash screen of form. See definition down below.
showSummary	no	Flag indicating if a summary should be shown to the end-user after all the sections have been made within the form. Defaults to `false`.
pages	yes	List of pages to show. See definition down below.

Splash definition

Field	Required	Remarks
header	no	Title of page in bold underneath the image.
splashtext	yes	Text to display in the splash screen.
buttonTitle	yes	Text on the button that starts the form.
media	no	Image to show in splash screen.

Page definition

Field	Required	Remarks
type	yes	Page type, can only be one of the following:`select`, `picker`, `datepicker` or `input`
title	no	Bold title of page.
subtitle	yes	Question of the page.
multipleSelection	no	Flag indicating if the end-user can select multiple options. Only applies to page type `select`
items	yes	Items to select from. See definition down below. Only applies to page types `select` & `picker`
options	yes	Page options. See definition down below. Only applies to page types `datepicker` and `input`

Item definition

Field	Required	Remarks
title	yes	Title item
value	yes	Postback data.
media	no	Only possible for page type `select`

Options definition

Field	Required	Remarks
minimumDate	yes	Minimum date of date range as ISO 8601. Only applies to page types `datepicker`.
startDate	yes	Default date to display in date range as ISO 8601. Only applies to page types `datepicker`.
maximumDate	yes	Maximum date of date range as ISO 8601. Only applies to page types `datepicker`.
dateFormat	no	Date format of the selected date. Default to `MM/dd/yyyy`. Only applies to page type `datepicker`.
labelText	no	Text to be shown next to date/input field. Defaults to text `Date` for page type`datepicker`.
required	no	End-user is required to fill in an answer to continue. Only applies to page types `input`.
placeholder	no	Placeholder text for input text field when it's empty. Only applies to page types `input`.
inputType	no	Type of input field, either `singleline` or `multiline`. Defaults to `singleline`Only applies to page types `input`.
maximumCharacterCount	no	Input field size in characters. Default to 30 for `singleline` and 300 for `multiline`. Only applies to page types `input`.

Direct message with form

In the example below we send a rich content message that contains text for a preview message and details for a form with several pages.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "header": "CM survey",
              "text": "Tap to open.",
              "form": {
                "splash": {
                  "header": "CM survey",
                  "splashtext": "Please help us improve our service",
                  "buttonTitle": "Fill in questionnaire",
                  "media": {
                    "mediaUri": "https://www.cm.com/cdn/cm/cm-com.png"
                  }
                },
                "pages": [
                  {
                    "type": "select",
                    "subtitle": "Which of the following product do you like?",
                    "multipleSelection": true,
                    "items": [
                      {
                        "title": "WhatsApp",
                        "value": "WA",
                        "media": {
                          "mediaUri": "https://cdn-icons-png.flaticon.com/512/1384/1384055.png"
                        }
                      },
                      {
                        "title": "Apple Messages for Business",
                        "value": "AMB",
                        "media": {
                          "mediaUri": "https://cdn-icons-png.flaticon.com/512/668/668287.png"
                        }
                      },
                      {
                        "title": "Facebook Messenger",
                        "value": "FBM",
                        "media": {
                          "mediaUri": "https://cdn-icons-png.flaticon.com/512/5968/5968771.png"
                        }
                      },
                      {
                        "title": "Instagram Messaging",
                        "value": "INSTA",
                        "media": {
                          "mediaUri": "https://cdn-icons-png.flaticon.com/512/1409/1409946.png "
                        }
                      },
                      {
                        "title": "Google Business Messages",
                        "value": "GBM",
                        "media": {
                          "mediaUri": "https://cdn-icons-png.flaticon.com/512/281/281764.png"
                        }
                      }
                    ]
                  },
                  {
                    "type": "picker",
                    "subtitle": "Where are your from?",
                    "items": [
                      {
                        "title": "Europe",
                        "value": "EU"
                      },
                      {
                        "title": "Asia",
                        "value": "AS"
                      },
                      {
                        "title": "Africa",
                        "value": "AF"
                      },
                      {
                        "title": "North America",
                        "value": "NA"
                      },
                      {
                        "title": "South America",
                        "value": "SA"
                      },
                      {
                        "title": "Oceania",
                        "value": "OC"
                      }
                    ]
                  },
                  {
                    "type": "datePicker",
                    "subtitle": "When did you arive?",
                    "options": {
                      "minimumDate": "2023-05-01",
                      "startDate": "2023-05-20",
                      "maximumDate": "2023-05-31"
                    }
                  },
                  {
                    "type": "input",
                    "subtitle": "What would you like to see added?",
                    "options": {
                      "required": "true"
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

Authentication

An authentication message enables you to ask the end user to start an authorization flow within a conversation. Using the OAuth 2 authentication prompt, you can ask a user to log in via a 3rd party website.

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

Direct message with OAuth 2.0 request

In the example below we send a rich content message that contains text for a preview message and details for an OAuth 2.0 request.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "header": "CM login",
              "text": "Lets Sign In",
              "oauth2": {
                "redirectUri": "YOUR REDIRECT URL",
                "scope": [
                  "openid email"
                ],
                "state": "STRING INDICATING STATE OF REQUEST"
              }
            }
          ]
        }
      }
    ]
  }
}

Payment message

A payment message enables you to ask for payment from an end-user who is purchasing goods and services through Messaging for Business via Apple Pay.

Setting up a payment message requires the usage of the CM Payments platform.

Payment definition

Field	Required	Remarks
merchantName	yes	Name of the merchant to display on the payment sheet.
description	yes	A description of the order that can be shown to the shopper.
currencyCode	yes	The order currency as ISO 4217 Alpha 3.
orderReference	no	The order reference from the merchant. Defaults to new UUID if not provided.
languageCountryCode	yes	The language of the shopper as ISO 639-1 Alpha 2. Used for the menu and emails.
recipientCountryCode	yes	The country of the shopper as ISO 639-1 Alpha 2.
recipientEmail	yes	The email address of the shopper.
billingAddressRequired	no	Flag indicating if the billing address in account settings should be used.
shippingContactRequired	no	Flag indicating if the shipping contact fields in account settings should be used.
total	yes	Total amount of the payment order.
lineItems	no	An array of line items explaining payments and additional charges. See definition down below.

Line item definition

Field	Required	Remarks
label	yes	A short, localized description of the line item.
amount	yes	The monetary amount of the line item.

Direct message with payment request

In the example below we send a rich content message that contains text for a preview message and details for a payment request.

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "from": "Your Business Account ID",
        "to": [
          {
            "number": "Conversation ID"
          }
        ],
        "body": {
          "type": "auto",
          "content": "Fallback Text"
        },
        "allowedChannels": [
          "Apple Messages for Business"
        ],
        "richContent": {
          "conversation": [
            {
              "header": "CM wear payment",
              "text": "€3.00 for CM.com wear",
              "media": {
                "mediaName": "shirt.png",
                "mediaUri": "https://api.pages.cm.com/pages/v1/resources/a783272b-df4f-46c8-b448-2a595b4ff3ec",
                "mimeType": "image/png"
              },
              "payment": {
                "merchantName": "CM.com",
                "description": "CM.com Shop",
                "currencyCode": "EUR",
                "languageCountryCode": "NL",
                "recipientCountryCode": "NL",
                "recipientEmail": "[email protected]",
                "billingAddressRequired": true,
                "shippingContactRequired": true,
                "total": 3.0,
                "lineItems": [
                  {
                    "label": "CM.com Cap",
                    "amount": 0.5
                  },
                  {
                    "label": "CM.com T-Shirt",
                    "amount": 1.0
                  },
                  {
                    "label": "CM.com Pants",
                    "amount": 1.5
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

Receiving messages / Inbound flow

Since Apple Messages for Business is used for 2-way communication (chat) it is important to also implement an Inbound flow. You can find more information about how to do this using our API documentation of the Inbound webhook. Note that for Apple Messages for Business, you need to set up your webhook API in the Channels app, not in the Gateway app.

Fact Sheet

Business rules

Considerations

Sending messages

Text

URL previews

Media messages

Display order

Direct message with text and image

Quick replies

🚧Note

Direct message with quick reply suggestions

OpenUrl

Direct message with open URL

List picker

List picker definition

Direct message with list picker

Time picker

Time picker definition

Direct message with time picker

App extension

App extension definition

Direct message with app extension

Form message

Form definition

Direct message with form

Authentication

Direct message with OAuth 2.0 request

Payment message

Payment definition

Direct message with payment request

Receiving messages / Inbound flow

🚧
Note