Apple Messages for Business Functions
  • 09 Nov 2022
  • 22 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Apple Messages for Business Functions

  • Dark
    Light
  • PDF

Article Summary

Apple Messages for Business Features

In this part you will learn how to work with all Apple Messages for Business Functions:

  1. List Picker Message
  2. Image List Picker
  3. Time Picker Message
  4. Rich Link
  5. Quick Reply
  6. Form Message
  7. Apple Pay
  8. OAuth 2.0 Request
  9. App Extension Call

List Picker Message

Allows to create a text list of items.
Can be used as a menu, list of products / services, etc.

The official documentation of Apple Messages for Business: List Picker

List Picker

A List Picker Message Example

The task Reference in a State Diagram Attachments: textListPicker.

   {
       "abc": {    
           "type": "text_list_picker",
               "list_picker": {
                 "sections": [
                   {
                       "items": [
                             {
                               "identifier": "/textListPicker",
                               "order": 0,
                               "title": "📜 Text List Picker",
                               "subtitle": "",
                               "style": "small"
                           } 
                       ],
                       "order": 0,
                       "title": "⚙️ {{t'mainMenu}}",
                       "multipleSelection": false  
                   }
               ],
               "receivedMessage": {
                   "title": "⚙️ {{t'mainMenu}}",
                   "subtitle": "",
                   "style": "small"
               },
               "replyMessage": {
                   "title": "Ok",
                   "subtitle": "",
                   "style": "small"
               }
           }
       }
   }

List Picker Message parameters description

ParameterTypeRequiredDescription
typestring+A type of an object to send
list_pickerobject+An object in where all List Picker Message parameters are described
list_picker.sectionsarray+An array of sections - sections
list_picker.sections[].itemsarray+An array of items
list_picker.sections[].items[].titlestring+An element title - item
list_picker.sections[].items[].subtitlestringAn element subtitle - item
list_picker.sections[].items[].identifierstring+An item ID that is sent to Corezoid when it has been selected by the client
list_picker.sections[].items[].stylestringDefines an item style. The default is "icon". Available values: "icon" / "small" / "large"
list_picker.sections[].items[].orderintegerA sequence number of an item in the "items" list
list_picker.sections[].orderintegerA sequence number of a section
list_picker.sections[].titlestring+A section title
list_picker.receivedMessageobject+An object that describes a received message of a list items selection by the user
list_picker.receivedMessage.titlestring+A title that is displayed when a customer receives a message
list_picker.receivedMessage.subtitlestring+A subtitle that is displayed when a customer receives a message
list_picker.receivedMessage.stylestring+Defines an item style. The default is "icon". Available values: "icon" / "small" / "large"
list_picker.replyMessageobject+An object in where is described how to displays a message after a response
list_picker.replyMessage.titlestring+A title that is displayed when the message has been sent by the user
list_picker.replyMessage.subtitlestring+A subtitle that is displayed when the message has been sent by the user
list_picker.replyMessage.stylestring+Defines an item style. The default is "icon". Available values: "icon" / "small" / "large"

Adding an item to a List Picker Message

List Picker Element

To expand a List Picker Message with a new item the following object needs to be added to the items[] array:

{
    "identifier": "2",
    "order": 2,
    "title": "Option 2" ,
    "subtitle": "Subtitle for option 2" ,
    "style": "small"
} 

Image List Picker

Allows to create a list of elements with text and images.
The official documentation of Apple Messages for Business: List Picker

Image List Picker

An Image List Picker Example

The task Reference in a State Diagram Attachments: imageListPicker.

{
    "abc": {
        "type": "image_list_picker",
        "images": [
            {
                "identifier": "0",
                "url": "https://i5.walmartimages.com/asr/2b4a8c7c-941f-4575-b1fe-2479c8024077_1.b3c876a51211d14cbdd5fc631995809c.jpeg"
            },
            {
                "identifier": "1",
                "url": "https://i5.walmartimages.com/asr/d43233f6-920f-4b9d-9b97-80a31487901b_1.9ecb6491c6307ebd24e5426dfc9ee4e8.jpeg"

            }
        ],
        "list_picker": {
            "sections": [
                {
                    "items": [
                        {
                            "identifier": "1",
                            "imageIdentifier": "0",
                            "order": 0,
                            "title": "Gala Apples",
                            "subtitle": "Price: $1.57 / each",
                            "style": "default"
                        },
                        {
                            "identifier": "2",
                            "imageIdentifier": "1",
                            "order": 1,
                            "title": "Navel Oranges",
                            "subtitle": "Price: $0.68 / each",
                            "style": "default"
                        }
                    ],
                    "order": 0,
                    "title": "Fruit",
                    "multipleSelection": true
                }
            ],
            "receivedMessage": {
                "style": "small",
                "subtitle": "Farm fresh to you",
                "title": "✅ Select Produce"
            },
            "replyMessage": {
                "style": "small",
                "title": "✅ Selected Produce",
                "subtitle": "Selected Produce"
            }
        }
    }
}

Image List Picker parameters description

ParameterTypeRequiredDescription
typestring+A type of an object to send
imagesarrayAn array of objects with images
images[].urlstringA link to an image
images[].identifierstring+An image ID used for substitution in the array items
list_pickerobject+An object in where all Text List Picker parameters are described
list_picker.sectionsarray+An array of sections
list_picker.sections[].itemsarrayAn array of items
list_picker.sections[]items[].titlestring+An item’s title
list_picker.sections[]items[].subtitlestringAn item’s subtitle
list_picker.sections[]items[].imageIdentifierstringAn image ID value from the array “images”
list_picker.sections[]items[].identifierstring+An item ID that is sent to Corezoid when it has been selected by the client
list_picker.sections[]items[].stylestringDefines an item style. The default is "icon".Available values: "icon" / "small" / "large"
list_picker.sections[]items[].orderintegerA sequence number of an item in a list - items
list_picker.sections[].orderintegerA sequence number of a section
list_picker.sections[].titlestring+A section title
list_picker.sections[].multipleSelectionbooleanDetermines whether simultaneous multiple choice of items is available. Default: false
list_picker.receivedMessageobject+An object that describes a received message of a list items selection by the user
list_picker.receivedMessage.titlestring+A title that is displayed when a customer receives a message
list_picker.receivedMessage.subtitlestring+A subtitle that is displayed when a customer receives a message
list_picker.receivedMessage.stylestring+Defines an item style. The default is "icon". Available values: "icon" / "small" / "large"
list_picker.replyMessageobject+An object in where is described how to display a message after a reply
list_picker.replyMessage.titlestring+ЗA title that is displayed when the message has been sent by the user
list_picker.replyMessage.subtitlestring+A subtitle that is displayed when the message has been sent by the user
list_picker.replyMessage.stylestring+Defines an item style. The default is "icon". Available values: "icon" / "small" / "large"

Adding an item to an Image List Picker

Image List Picker

To expand Image List Picker, with a new item there’s need to be added the following objects to the arrays items[]and images[]:

"images": [
             {
                "identifier": "1",
                "url": "{{image URL}}"
            }
        ]
"items": [
        {
            "identifier": "1", 
            "imageIdentifier": "1", 
            "order": 0, 
            "title": "Gala Apples",
            "subtitle": "Price: $1.57 / each", 
            "style": "small" 
        } 
]

Time Picker Message

The date and time picker function allows to provide to your customers a convenient tool for scheduling an appointment, meeting or event.
The official documentation of Apple Messages for Business: Time Picker

Time Picker

A Time Picker Example

The task Reference in a State Diagram Attachments: timePicker.

{
    "abc": {
        "type": "time_picker",
        "time_picker": {
            "event": {
                "identifier": "1", 
                "location": { 
                    "latitude": 37.7725,
                    "longitude": -22.4311,
                    "radius": "2",
                    "title": "Building One"
                },
                "timeslots": [
                    {
                        "duration": 3600,
                        "identifier": "5",
                        "startTime": "2020-04-01T15:30+0000"
                    },
                    {
                        "duration": 3600,
                        "identifier": "7",
                        "startTime": "2020-04-02T08:30+0000"
                    },
                    {
                        "duration": 3600,
                        "identifier": "9",
                        "startTime": "2020-04-03T21:30+0000"
                    }
                ],
                "timezoneOffset": 0,
                "title": "Schedule an Appointment"
            },
            "receivedMessage": {
                "style": "icon",
                "title": "Please pick a time",
                "subtitle": "This should be 10:00am for -7h users"
            },
            "replyMessage": {
                "style": "icon",
                "title": "Thank you!"
            }
        }
    }
}

Time Picker parameters description

ParameterTypeRequiredDescription
typestring+A type of an object to send
time_pickerobject+An object in where all Time Picker Message parameters are described
time_picker.eventobject+An object in where all events are described
time_picker.event.identifierstring+An item ID that is sent to Corezoid when it has been selected by the client
time_picker.event.locationobjectAn object in where an event location is described
time_picker.event.location.latitudedoubleLocation latitude
time_picker.event.location.longitudedoubleLocation longitude
time_picker.event.location.radiusdoubleLocation radius (in meters). This field is used whether there’s no latitude and longitude
time_picker.event.location.titlestring+An item’s title
time_picker.event.timeslotsarrayAn array of timeslots
time_picker.event.titlestring+An item’s title
time_picker.event.timeslots[].durationintegerA time slot duration (in seconds)
time_picker.event.timeslots[].startTimedouble+An event start time, a date in format UTC (ISO 8601). An example: 2017-05-26T08:27:55+00:00, 2017-05-26T08:27:55+0000, or 2017-05-26T08:27:55Z
time_picker.event.timeslots[].identifierstring+An item ID that is sent to Corezoid when it has been selected by the client
time_picker.event.event.timezoneOffsetintegerMinutes quantity from GMT, that settles an event location time zone. If it’s not defined, the time is displayed according to the current client’s time zone. If defined, the time is displayed according to the event time zone, independently from the client’s location
time_picker.receivedMessageobject+An object that describes a received message from a list of items selected by the user
time_picker.receivedMessage.titlestring+A title that is displayed when a customer receives a message
time_picker.receivedMessage.subtitlestring+A subtitle that is displayed when a customer receives a message
time_picker.receivedMessage.stylestring+Defines an item style. The default is "icon". Available values: "icon" / "small" / "large"
time_picker.replyMessageobject+An object where it is described how to display a message after a reply
time_picker.replyMessage.titlestring+A title that is displayed when the message has been sent by the user
time_picker.replyMessage.subtitlestring+A subtitle that is displayed when the message has been sent by the user
time_picker.replyMessage.stylestring+Defines an item style. The default is "icon". Available values: "icon" / "small" / "large"

Adding an item to a Time Picker Message

Time Picker

To expand the date and time selection list - Time Picker Message with a new item, you need to add the following object to the timeslots array:

"timeslots": [
     {
             "duration": 3600, 
             "identifier": "1",
             "startTime": "2020-04-1T15:30+0000" 
        }
]

Allows to send messages with images and videos to clients.

The official documentation of Apple Messages for Business: Rich Link

Rich Link

A Rich Link Example

The task Reference in a State Diagram
Attachments: richLink.

{
    "abc": {   
        "type": "rich_link",
        "rich_link": {
            "richLinkData": {
                "url": "https://www.corezoid.com/",
                "title": "Welcome to Corezoid!",
                "assets": {
                    "image": {
                        "data": "<…code img in base64…>",
                        "mimeType": "image/png"
                    }
                }
            }
        }
     }
}

Rich Link parameters description

ParameterTypeRequiredDescription
typestring+A type of an object to send
rich_linkobject+An object in where all Rich Link parameters are described
rich_link.richLinkDataobject+An object that contains data to form an object
richLinkData.urlstring+A link the customer will follow after “tapping” the item
richLinkData.titlestring+An item’s title
richLinkData.assetsobject+An object in where an image or a video is described
richLinkData.assets.imageobject+An object in where an image is described
richLinkData.assets.image.datastring+Base64 that presents an item which is used
richLinkData.assets.image.mimeTypestring+MimeType, for example: image/jpeg, image/png
richLinkData.assets.videoobject+An object in where a video is described
richLinkData.assets.video.urlstring+A link to a video
richLinkData.assets.image.mimeTypestring+MimeType, for example: video/mp4, video/mpeg

It’s possible to convert an image to base64 in the online converter, for example:

Quick Reply

Allows to display from two to five customizable choices, and the user can select only one item.
The official documentation of Apple Messages for Business: Quick Reply

Webp.net-resizeimage.jpg

A Quick Reply Message Example

The task Reference for Quick Reply in a State Diagram Attachments: quickReply:

   {
    "abc": {
        "type": "quick_reply",
        "quick_reply": {
            "summaryText": "{{t'key_from_local_1}}",
            "items": [
                {
                    "identifier": "yes",
                    "title": "{{t'key_from_local_2}}"
                },
                {
                    "identifier": "menu",
                    "title": "{{t'key_from_local_3}}"
                }
            ]
        }
    }
}

Quick Reply parameters description

ParameterTypeRequiredDescription
typestring+A type of an object to send
quick_replyobject+An object, in which all Quick Reply parameters are described
quick_reply.summaryTextstring+A summary text that will be used for device notification but also shown in the transcript after user makes a choice
quick_reply.itemsarray+An array of section items
quick_reply.items[].titlestring+Title of the Quick Reply item. Max 1 line of text
quick_reply.items[].identifierstringAn identifier to identify the item

Form Message

Form Messages allow you to create rich, multipage interactive flows for users on iOS and iPadOS devices using a single JSON payload.

The official documentation of Apple Form Messages: Form Messages

Form Message Example

The task Reference in the Attachments state diagram: abcForm.

   {
    "abc": {
        "type": "form",
        "interactiveData": {
            "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension",
            "data": {
                "version": "1.0",
                "requestIdentifier": "{{id}}",
                "dynamic": {
                    "version": "1.1",
                    "template": "form",
                    "data": {
                            "splash": {
                            "header": "Messages for Business Form Demo",
                            "splashtext": "Check out the types of pages available",
                            "buttonTitle": "Continue",
                            "imageIdentifier": "2"
                        },
                        "startPageIdentifier": "001",
                        "showSummary": true,
                        "pages": [
                              {
                                "pageIdentifier": "001",
                                "type": "select",
                                "title": "Please Choose One Selection To Move On To The Next Page",
                                "subtitle": "Single Select Page",
                                "multipleSelection": true,
                                "items": [
                                    {
                                        "title": "Single 1",
                                        "imageIdentifier": "2",
                                        "value": "option01",
                                        "identifier": "001_01",
                                        "nextPageIdentifier": "002"
                                    },
                                    {
                                        "title": "Single 2",
                                        "imageIdentifier": "2",
                                        "value": "option02",
                                        "identifier": "001_02",
                                        "nextPageIdentifier": "002"
                                    },
                                    {
                                        "title": "Single 3",
                                        "value": "option03",
                                        "imageIdentifier": "2",
                                        "identifier": "001_03",
                                        "nextPageIdentifier": "002"
                                    },
                                    {
                                        "title": "Single 4",
                                        "value": "option04",
                                        "imageIdentifier": "2",
                                        "identifier": "001_04",
                                        "nextPageIdentifier": "002"
                                    },
                                    {
                                        "title": "Single 5",
                                        "value": "option01",
                                        "imageIdentifier": "2",
                                        "identifier": "001_05",
                                        "nextPageIdentifier": "002"
                                    }
                                ]
                            },
                            
		{
                                "pageIdentifier": "002",
                                "title": "Select All That Apply",
                                "subtitle": "Multiple Selection",
                                "type": "select",
                                "multipleSelection": true,
                                "nextPageIdentifier": "003",
                                "items": [
                                    {
                                        "title": "Multi 1",
                                        "value": "multi1",
                                        "identifier": "002_01"
                                    },
                                    {
                                        "title": "Multi 2",
                                        "value": "multi2",
                                        "identifier": "002_02"
                                    },
                                    {
                                        "title": "Multi 3",
                                        "value": "multi3",
                                        "identifier": "002_03"
                                    },
                                    {
                                        "title": "Multi 4",
                                        "value": "multi4",
                                        "identifier": "002_04"
                                    },
                                    {
                                        "title": "Multi 5",
                                        "value": "multi5",
                                        "identifier": "002_05"
                                    }
                                ]
                            },
                            {
                                "pageIdentifier": "003",
                                "title": "Date Picker With Min/Max Date and Label Text",
                                "subtitle": "Date Picker",
                                "type": "datePicker",
                                "options": {
                                    "minimumDate": "01/01/1970",
                                    "maximumDate": "01/01/2050",
                                    "labelText": "Select Date:"
                                
		},
                                "nextPageIdentifier": "004"
                            },
                            {
                                "pageIdentifier": "004",
                                "title": "With Custom Label, Prefix, Regex and Placeholder Text",
                                "subtitle": "Numeric Input - Currency",
                                "type": "input",
                                "options": {
                                    "keyboardType": "decimalPad",
                                    "regex": "^\\d*\\.?\\d?\\d?$",
                                    "labelText": "Enter Amount:",
                                    "placeholder": "50.00",
                                    "prefixText": "$"
                                },
                                "nextPageIdentifier": "005"
                            },
                            {
                                "pageIdentifier": "005",
                                "title": "With Placeholder, Label and Expecting a Name",
                                "subtitle": "Text Input - Single Line",
                                "type": "input",
                                "nextPageIdentifier": "006",
                                "options": {
                                    "placeholder": "J. Appleseed",
                                    "labelText": "Name:",
                                    "textContentType": "name",
                                    "required": true
                                }
                            },
                            {
                                "pageIdentifier": "006",
                                "title": "Optional Additional Comment Field",
                                "subtitle": "Text Input - Multiple Lines",
                                "type": "input",
                                "submitForm": true,
                                "options": {
                                    "inputType": "multiline",
                                    "placeholder": "Add any additional details here"
                                }
                            }
                        ]
                    }
                },
                
	         "images": [
                    {
                        "identifier": "1",
                        "data": "{{imageBit}}"
                    },
                    {
                        "identifier": "2",
                        "data": "{{imageBit}}"
                    }
                ]
            },
            "receivedMessage": {
                "title": "Messages for Business Form",
                "subtitle": "Tap to view the available pages",
                "style": "small",
                "imageIdentifier": "1"
            },
            "replyMessage": {
                "title": "Messages for Business Form",
                "subtitle": "Tap to review your selections",
                "style": "small",
                "imageIdentifier": "1"
            }
        },
        "attachments": [
            
        ]
    }
}

Form Message parameters description

ParameterType (and object for ...dynamic.data.pages[])RequiredDescriptionExample/Allowed value
bidstring+Static parameter, which is sent in the Formsee the example above
data.dynamic.versionstring+Should be 1.1 or the specified value when the feature launches1.1
data.dynamic.templatestring+Type is form. Tells the client which template to use to render the viewform
data.dynamic.dataobject+Place all the Form data in this field
...dynamic.data.splash.headerstring+Shown at the start of the Form. When using splash, ensure the appropriate fields listed below displayMessages for Business Form Demo
...dynamic.data.splash.splashtextstringThe main text of the Form starting page
...dynamic.data.splash.buttonTitlestring+Text on the button shown on the page. If buttontext is missing then this view doesn't display and continues onto the first moduleContinue
...dynamic.data.splash.imageIdentifierstringIdentifier of image to be shown at the top of the view2
...dynamic.data.startpageIdentifierstring+Identifier of the starting page for the Forms. Defaults to the first object in the pages[] array if not defined2
...dynamic.data.showSummarybooleanDefaults to “false”. If set to “true” then shows the summary of all the selections made within the Formfalse (default), true
...dynamic.data.pages[].pageIdentifierstring+A unique identifier for the page being shown that is less than 20 characters in length. Do not reuse001
...dynamic.data.pages[].typestring+Data input type for the page. Use one of the following values: select (item selection list), datePicker (date selection menu), or input (keyboard data input)select, datePicker, input
...dynamic.data.pages[].titlestringIf set this displays the title in bold on the page. The title is located between the page title image (see imageIdentifier) and the main textPlease Choose One Selection To Move On To The Next Page
...dynamic.data.pages[].subtitlestring+Used to display the title text of Form pages. For example, an explanation for a page text or a questionPlease, answer the following question
...dynamic.data.pages[].multipleSelectionbooleanEnables multiple item selection for the page when set to “true”. By default, set to “false” allowing the user to select only one item (singleSelect)true, false (default)
...data.pages[].items[]titlestring+Localized string value for display in the page title001
...data.pages[].items[]imageIdentifierstring+Identifier of the image, which is displayed at the top of a Form page01
...data.pages[].items[]valuestring+A string value of the object itselfoption01
...data.pages[].items[]identifierstring+A unique identifier for the item001_01
...data.pages[].items[]nextPageIdentifierstring+A unique page identifier to show the next page. Set this value only when multipleSelection is not defined or set to “false”002
...dynamic.data.pages[]datePicker.optionsstring, dateFormat object+A string representing the date format on the page. Defaults to MM/DD/YYYY. Unless this property is explicitly set, all of the date properties are defined using this format02/15/2021
...dynamic.data.pages[]datePicker.optionsstring, startDate object+A string representing the date displayed by the date picker. Defaults to current date02/15/2021
...dynamic.data.pages[]datePicker.optionsstring, maximumDate object+A string representing the maximum date that a date picker can show. Defaults to current date02/15/2050
...dynamic.data.pages[]datePicker.optionsstring, minimumDate object+A string representing the minimum date that a date picker can show02/15/2000
...dynamic.data.pages[]datePicker.optionsstring, labelText object+A string representing the text string to be shown next to the date field. Defaults to “Date” textDate (default)
...dynamic.data.pages[]optionsstring, regex object+A string representing a JSON encoded Regex string to limit the type of input for input field to use. Note: all Regex strings are JSON-codedExample to limit input to only have proper decimal values provide a regex string: ^\ \d*\.?\d?\d?$
...dynamic.data.pages[]optionsstring, placeholder object+A text string used when there is no other text in the input text fieldDefault values: Required, Optional
...dynamic.data.pages[]optionsboolean, required object+A Boolean value that defaults to “false”. When set to “true”, the next button on page is disabled until the user provides inputtrue, false
...dynamic.data.pages[]optionsstring, inputType object+A string value that defaults to singleline. When set to “multiline” a multi -line user data input is enabledsingleline, multiline
...dynamic.data.pages[]optionsstring, labelText object+A string value representing a text label shown to identify the input field. This value defaults to an empty string. Only applies to inputType:singlelineEnter amount
...dynamic.data.pages[]optionsstring, prefixText object+A string value representing optional text shown next to the text field. This value defaults to an empty string. For example, you can set this value to denote the $ character for the field. Only applies to inputType:singleline$
...dynamic.data.pages[]optionsstring, maximumCharacterCount object+An integer value representing the field size in characters for singleline and multiline. The field size defaults to 30 characters for singleline and 300 characters for multilineDefault values: 30 (for singleline field type), 300 (for multiline field type)
...dynamic.data.pages[]optionsstring, keyboardType objectType of keyboard to be showndefault, asciiCapable, numbersAndPunctuation, URL, numberPad, phonePad, namephonePad, emailAddress, decimalPad,UIKeyboardTypeTwitter,webSearch

Types of keyboard supported for keyboardType

Type of keyboardDescriptionAllowed value
defaultDefault value. Specifies the default keyboard for the current input method
asciiCapableSpecifies a keyboard that displays standard ASCII characters
numbersAndPunctuationSpecifies the numbers and punctuation keyboard
URLSpecifies a keyboard optimized for URL entry. This keyboard type prominently features the period (.), forward slash (/) characters, and the “.com” string".","/",“.com”...
numberPadSpecifies a numeric keypad designed for PIN entry. This keyboard type prominently features the numbers 0 through 9. This keyboard type does not support auto capitalization1,2,3,4,5,6,7,8,9,0
phonePadSpecifies a keypad designed for entering telephone numbers. This keyboard type prominently features the numbers 0 through 9 and the asterisk (*) and hashtag (#) characters1,2,3,4,5,6,7,8,9,0, "*", "#"
namePhonePadSpecifies a keypad designed for entering a person’s name or phone number. This keyboard type does not support auto capitalization
emailAddressSpecifies a keyboard optimized for entering email addresses. This keyboard type prominently features the at (@), period (.), and space characters
decimalPadSpecifies a keyboard with numbers and a decimal point1,2,3,4,5,6,7,8,9,0, "."
UIKeyboardTypeTwitterSpecifies a keyboard optimized for Twitter text entry, with easy access to the at (@) and hashtag (#) characters
webSearchSpecifies a keyboard optimized for web search terms and URL entry. This keyboard type prominently features the space and period (.) characters
textContentTypeA string value representing the keyboard and system information about the expected semantic meaning for the content that users enter. For a full description of each supported value, see UITextContentType on Apple Developer.name, namePrefix, givenName, middleName, familyName, nameSuffix, nickname, jobTitle, organizationName, location, fullStreetAddress, streetAddressLine1, streetAddressLine2, addressCity, addressState, addressCityAndState, sublocality, countryName, postalCode, telephoneNumber, emailAddress, URL, creditCardNumber, username, password, newPassword, oneTimeCode

Apple Pay

Customers will be able to pay your goods and services right from Apple Messages for Business, without having to go to any external sites or fill in the card data.

The official documentation of Apple Messages for Business: Apple Pay

Rich Link

Rich Link

An Apple Pay Message Example

The task Reference in a State Diagram Attachments: applePay.

{
   "abc": {
       "type": "apple_pay_request",
       "apple_pay_request": {
           "receivedMessage": {
               "title": "{{title}}",
               "subtitle": "{{subtitle}}",
               "style": "icon"
           },
           "payment": {
               "paymentRequest": {
                   "lineItems": [
                       {
                           "label": "Item 1",
                           "amount": "0.01",
                           "type": "final"
                       },
                       {
                           "label": "Item 2",
                           "amount": "0.01",
                           "type": "final"
                       }
                   ],
                   "total": {
                       "label": "Your Total",
                       "amount": "0.02",
                       "type": "final"
                   },
                   "applePay": {
                       "merchantIdentifier": "{{merchantIdentifier}}",
                       "supportedNetworks": [
                           "amex",
                           "visa",
                           "discover",
                           "masterCard",
                           "chinaUnionPay",
                           "interac",
                           "privateLabel"
                       ],
                       "merchantCapabilities": [
                           "supportsDebit",
                           "supportsCredit", 
                           "supportsEMV", 
                           "supports3DS"            
                       ]
                   },
                   "merchantName": "{{merchantName}}",
                   "countryCode": "US", 
                   "currencyCode": "USD", 
                   "requiredBillingContactFields": [
                       "postalAddress"
                   ],
                   "requiredShippingContactFields": [
                       "postalAddress",
                       "name",
                       "phoneticName",
                       "phone",
                       "email"
                    ]
               },
               "endpoints": {
                   "paymentGatewayUrl": "https://botplatform.corezoid.com/paymentGateway" 
               }
           }
       }  
   }
}

Apple Pay in Messages for Business parameters description

ParameterTypeRequiredDescription
typestring+A type of an object to send
apple_pay_requestobject+An object in where request parameters are described
apple_pay_request.paymentobject+An object in where invoice parameters are described
apple_pay_request.payment.paymentRequestobject+An object in where invoice parameters are described
apple_pay_request.paymentRequest.lineItemsarray+A list of goods/services, from where formed an invoice
apple_pay_request.paymentRequest.lineItems[].labelstring+A brief product/service description
apple_pay_request.paymentRequest.lineItems[].amountstring+Product/service amount
apple_pay_request.paymentRequest.lineItems[].typestringIndicates whether an order is final or if funds need to be frozen. Available values: "final" / "pending"
apple_pay_request.paymentRequest.totalobject+An object that contains total payment amount
apple_pay_request.paymentRequest.total.typestringA value that indicates whether the item is final or pending
apple_pay_request.paymentRequest.total.amountstring+Total payment amount
apple_pay_request.paymentRequest.total.labelstring+A brief invoice description
apple_pay_request.paymentRequest.applePayobject+An object in where an Apple Pay configuration is described
apple_pay_request.paymentRequest.applePay.merchantIdentifierstring+A merchant ID that has been indicated during the registration in Apple Messages for Business
apple_pay_request.paymentRequest.applePay.supportedNetworksarray+A list of supported payment Networks through which payment will occur. Available values: "amex" / "visa" / "discover" / "masterCard" / "chinaUnionPay" /"interac" / "privateLabel"
apple_pay_request.paymentRequest.applePay.merchantCapabilitiesarray+Possible payment methods. Available values: "supportsDebit" / "supportsCredit" / "supportsEMV" / "supports3DS"
apple_pay_request.paymentRequest.merchantNamestring+Your merchant name
apple_pay_request.paymentRequest.countryCodestring+A merchant country code in format ISO 3166
apple_pay_request.paymentRequest.currencyCodestring+An invoice currency code in format ISO 4217
apple_pay_request.paymentRequest.requiredBillingContactFieldsarrayA client’s payment data list, required for the invoice payment. An available value: "postalAddress". If the value is empty - the information isn’t requested
apple_pay_request.paymentRequest.requiredShippingContactFieldsarrayA client’s contact details list, required for the invoice payment. Available values: "postalAddress" / "name" / "phoneticName" / "phone" / "email"
apple_pay_request.payment.endpointsobject+An object in where payment processing information is described
apple_pay_request.payment.endpoints.paymentGatewayUrlstring+A URL for processing payment through a payment provider. It should always be indicated: "https://botplatform.corezoid.com/paymentGateway"
A Dynamic Invoice
Communications Orchestrator supports a dynamic invoice formation for Apple Pay. To manage it, use a task with the Reference: invoice from the State Diagram Attachments as an instance and customize it according to your needs.

An items array example to form a dynamic invoice

"items": [
    {
        "title": "...",
        "quantity": "...",
        "total": "..."
    },
    {
        "title": "...", 
        "quantity": "...",
        "total": "..."
    }
]

App Extension Call

This option allows to call a function/window from the iOS-application, to expand Apple Messages for Business capabilities.

The official documentation of Apple Messages for Business: iMessage App

App Extension Call

An iMessage App Example

The task Reference in a State Diagram Attachments: appExtensionCall.

{
   "abc": {
       "type": "app_extension_call",
       "interactiveData": {
           "appId": 123456789,
           "appName": "Package Delivery",
           "URL": "?name=WWDC%20Goodies&deliveryDate=09-06-2017&destinationName=Moscone%20Convention%20Center&street=747%20Howard%20St&state=CA&city=San%20Fransisco&country=USA&postalCode=94103&latitude=37%2E7831&longitude=%2D122%2E4041&extraCharge=15%2E00",
           "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:WRS8W2ZKCT:com.example.apple-samplecode.PackageDeliveryWRS8W2ZKCT.MessagesExtension",
           "sessionIdentifier": "{{uuid}}",
           "receivedMessage": {
               "title": "WWDC Goodies",
               "subtitle": "Scheduled for delivery - Today",
               "secondarySubtitle": "",
               "tertiarySubtitle": "",
               "imageTitle": "",
               "imageSubtitle": ""
           },
           "useLiveLayout": true
       },
       "attachments": []
   }
}

iMessage App parameters description

ParameterTypeRequiredDescription
typestring+A type of an object to send
interactiveDataobject+An object in where an interactive message is described
interactiveData.appIdstring+An iMessage extension ID from App Store
interactiveData.appNamestring+An iMessage extension name
interactiveData.URLstring+A deep link that is used by the customer to call an iMessage extension
interactiveData.bidstring+An iMessage extension ID
interactiveData.sessionIdentifierstring+A background session ID
receivedMessage.titleobject+An object in where is described how to display a message upon receiving
receivedMessage.titlestring+An item’s title
receivedMessage.subtitlestringAn item subtitle
receivedMessage.imageTitlestringAn attached image name
receivedMessage.imageSubtitlestringAn attached image subtitle
interactiveData.useLiveLayoutboolean+A parameter that determines whether iMessage application should use Live Layout. Default: true

OAuth 2.0 Request

Verify your customers using the OAuth 2.0 protocol through your own or external services:

OAuth 2.0 Request

OAuth 2.0 Request

The official Apple Messages for Business documentation: OAuth 2.0 Request.

Version 1.0

The official Apple Messages for Business documentation.
A user needs to add the following ref token config to the tokens storage:

ParameterTypeRequiredDescription
oauthobject+Object with config oauth provider
oauth.client_idstring+Client ID, is a public identifier for OAuth apps
oauth.client_secretstring+Client secret, is a secret known only to the application and the authorization server
oauth.scopearray of strings+Scope, is a mechanism in OAuth 2.0 to limit an application's access to a user's account

The Authentication Process Architecture v 1.0

Auth scheme.png

Version 2.0

The official Apple Messages for Business documentation.
A user needs to add the following ref token config to the tokens storage:

ParameterTypeRequiredDescription
oauthobject+Object with config oauth provider
oauth.client_idstring+Client ID, is a public identifier for OAuth apps
oauth.client_secretstring+Client secret, is a secret known only to the application and the authorization server
oauth.redirect_uristring+Redirect URL that the OAuth provider redirects the user
oauth.scopearray of strings+Scope, is a mechanism in OAuth 2.0 to limit an application's access to a user's account
code and state values

The code and state values acquired on Redirect URL need to be sent to an OAuth receiver (./Messengers/Apple Business Chat/OAuth 2.0/OAuth 2.0 (receiver - v2)) using a direct URL in a POST request, or using the Sync API.

The Authentication Process Architecture v 2.0

image.png