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

FeatureSupportRemarks
delivery notificationyesOccurs when your message is delivered to the Apple platform. Delivery notifications are sent to the status report webhooks.
text messagesyesThe maximum length of a message is 4096 characters and it must be UTF-8 encoded.
mediayesMedia 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: imagesyesMaximum file size for an uploaded image is 100 MB.
media: gifyesMaximum file size for an uploaded gif is 100 MB.
media: audioyesMaximum file size for an uploaded audio file is 100 MB.
media: videoyesMaximum file size for an uploaded video file is 100 MB.
media: documentsyesMaximum file size for an uploaded file is 100 MB.
reply suggestionsyesMax 5 reply suggestions
list pickeryesWill be converted to quick replies when no media is provided.
time pickeryes
app extensionyesRequires details about iMessage app.
form messageyes
authentication messageyesRequires 3rd party OAuth 2.0 supplier.
payment messageyesRequires 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

FieldRequiredRemarks
labelyesTitle of list picker page.
multipleSelectionnoFlag indicating if the end-user can select multiple options.
medianoMedia to use in list picker preview message.
optionsyesList of options. See definition for option down below.

Option definition

FieldRequiredRemarks
labelyesTitle of option.
medianoMedia to use for option.

Direct message with list picker

Preview message

Preview message

List picker

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

FieldRequiredRemarks
labelyesTitle of time picker page.
medianoMedia to use in time picker preview message.
locationnoLocation details. See definition down below.
optionsyesList of time options. See definition down below.

Location definition

FieldRequiredRemarks
labelyesTitle of location.
longitudeyesA double representing the longitude of the location.
latitudeyesA double representing the latitude of the location.
radiusnoLocation radius. Default: 1 meter

Option definition

FieldRequiredRemarks
startTimeyesStart time of time slot in UTC format.
endTimeyesEnd date of time slot in UTC format.

Direct message with time picker

Preview message

Preview message

Time picker

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

FieldRequiredRemarks
teamIdyesThe 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.”
extensionIdyesIdentifier 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

FieldRequiredRemarks
splashnoSplash screen of form. See definition down below.
showSummarynoFlag indicating if a summary should be shown to the end-user after all the sections have been made within the form. Defaults to false.
pagesyesList of pages to show. See definition down below.

Splash definition

FieldRequiredRemarks
headernoTitle of page in bold underneath the image.
splashtextyesText to display in the splash screen.
buttonTitleyesText on the button that starts the form.
medianoImage to show in splash screen.

Page definition

FieldRequiredRemarks
typeyesPage type, can only be one of the following:select, picker, datepicker or input
titlenoBold title of page.
subtitleyesQuestion of the page.
multipleSelectionnoFlag indicating if the end-user can select multiple options. Only applies to page type select
itemsyesItems to select from. See definition down below. Only applies to page types select & picker
optionsyesPage options. See definition down below. Only applies to page types datepicker and input

Item definition

FieldRequiredRemarks
titleyesTitle item
valueyesPostback data.
medianoOnly possible for page type select

Options definition

FieldRequiredRemarks
minimumDateyesMinimum date of date range as ISO 8601. Only applies to page types datepicker.
startDateyesDefault date to display in date range as ISO 8601. Only applies to page types datepicker.
maximumDateyesMaximum date of date range as ISO 8601. Only applies to page types datepicker.
dateFormatnoDate format of the selected date. Default to MM/dd/yyyy. Only applies to page type datepicker.
labelTextnoText to be shown next to date/input field. Defaults to text Date for page typedatepicker.
requirednoEnd-user is required to fill in an answer to continue. Only applies to page types input.
placeholdernoPlaceholder text for input text field when it's empty. Only applies to page types input.
inputTypenoType of input field, either singleline or multiline. Defaults to singlelineOnly applies to page types input.
maximumCharacterCountnoInput field size in characters. Default to 30 for singleline and 300 for multiline. Only applies to page types input.

Direct message with form

Preview message

Preview message

Splash screen

Splash screen

Select page

Select page

Picker page

Picker page

Date picker page

Date picker page

Input page

Input page

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

FieldRequiredRemarks
merchantNameyesName of the merchant to display on the payment sheet.
descriptionyesA description of the order that can be shown to the shopper.
currencyCodeyesThe order currency as ISO 4217 Alpha 3.
orderReferencenoThe order reference from the merchant. Defaults to new UUID if not provided.
languageCountryCodeyesThe language of the shopper as ISO 639-1 Alpha 2. Used for the menu and emails.
recipientCountryCodeyesThe country of the shopper as ISO 639-1 Alpha 2.
recipientEmailyesThe email address of the shopper.
billingAddressRequirednoFlag indicating if the billing address in account settings should be used.
shippingContactRequirednoFlag indicating if the shipping contact fields in account settings should be used.
totalyesTotal amount of the payment order.
lineItemsnoAn array of line items explaining payments and additional charges. See definition down below.

Line item definition

FieldRequiredRemarks
labelyesA short, localized description of the line item.
amountyesThe 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.