Supported Apple Messages for Business Features
For skills that you expose through Apple Messages for Business channels in Oracle Digital Assistant, you can use features specific to Apple Messages for Business in addition to the features that are generally supported across other channels.
To do so, you generally use the channelCustomProperties
element in Common Response components to insert Apple-specific properties.
The code has the following format:
...
channelCustomProperties:
- channel: "apple"
properties:
PROPERTY_NAME: "PROPERTY_VALUE"
...
Rich Link
To incorporate Rich Link messages in Apple Messages for Business
channels, you use the richLinkData
channel custom property and its
sub-property assets
. The assets
property can take either an
image
object or a video
object, as shown in this
sample:
channelCustomProperties:
- channel: "apple"
properties:
richLinkData:
assets:
image:
data: "<base-64-encoded image data>"
mimeType: "image/jpeg"
video:
mimeType: "video/mp4",
url: "https://example.com/example.mov"
Example: Rich Link Image
responseItems:
- type: "text"
text: "iPad Pro"
actions:
- type: "url"
url: "https://www.apple.com/ipad-pro/"
channelCustomProperties:
- channel: "apple"
properties:
richLinkData:
assets:
image:
data: "<base 64 encoded image data>"
mimeType: "image/jpeg"
Example: Rich Link Video
responseItems:
- type: "text"
text: "HomePod"
actions:
- type: "url"
url: "https://images.apple.com/media/films/expand/homepod-expand-tpl-cc-us-20180306_1280x720h.mp4"
channelCustomProperties:
- channel: "apple"
properties:
richLinkData:
assets:
image:
data: "<base 64 encoded image data>"
mimeType: "image/jpeg"
video:
mimeType: "video/mp4",
url: "https://store.storevideos.cdn-apple.com/v1/store.apple.com/st/1619042871000/mx532-
Quick Reply
The Quick Reply message type is a convention used in Apples Messages for Business for providing two to five pre-defined responses that a user can select with a single tap.
You can set the Quick Reply's summary text using the summaryText
channel
custom property:
channelCustomProperties:
- channel: apple
properties:
summaryText: Your selection
If you don't provide the summaryText
property, the channel uses
the text
propery instead.
In addition, keep the following in mind:
summaryText
should not be more than 25 characters.- For keywords, you use the
A
,B
,C
,D
, andE
(instead of numbers).
Example: Quick Reply
responseItems:
- text: "You can type or select from the options below:"
type: text
actions:
- payload:
variables:
menuAction: orderAccessories
action: orderAccessories
label: "Order Accessories"
type: postback
keyword: "A"
- payload:
variables:
menuAction: checkOrder
action: checkOrder
label: "Check Order Status"
type: postback
keyword: "B"
channelCustomProperties:
- channel: apple
properties:
summaryText: Your selection
List Picker
Apple Messages for Business has a List Picker message type that you can use to allow users to select one or more options. To incorporate List Picker messages in Apple Messages for Business channels, you use the following Apple channel custom properties:
images
. This is a list of objects that are used by thereceivedMessage
andreplyMessage
properties and which contain the following elements:identifier
: the identifier by which the image is referenced by other properties.imageUrl
: the URL of the image to be displayed.description
.
receivedMessage
. This is an object with the following optional elements:imageIdentifier
. Its value must match with theidentifier
property of one of the images defined in theimages
custom property.style
. The possible values areicon
,small
, andlarge
.subtitle
.title
.
replyMessage
. This is an object with the following optional elements:imageIdentifier
. Its value must match with theidentifier
property of one of the images defined in theimages
custom property.style
. The possible values areicon
,small
, andlarge
.subtitle
.title
.
imageIdentifier
. You can use this property within thechannelCustomProperties
element of theoptions
element to add images to the options in the picker. Its value must match with theidentifier
property of one of the images defined in theimages
custom property.
You can create single-select list pickers using either the
cards
or the editForm
response item types.
For single-select list pickers using editForm
:
- Set the
displayType
for the items to"singleSelect"
.
For multi-select list pickers, use the editForm
response
item type:
- Set the
displayType
for the items to"multiSelect"
.
You can also create list pickers with multiple sections using any combination of
singleSelect
and multiSelect
lists. You do so by
creating an entry in the items
for each section and setting each
entry's displayType
to "singleSelect"
or
"multiSelect"
, depending on the type of list you want for that
section.
Example: Single-Select List Picker Using Cards
responseItems:
- type: "cards"
cardLayout: "horizontal"
headerText: "Here are our pizzas you can order today:"
visible:
entitiesToResolve:
include: "Type"
cards:
- title: "${enumValue}"
description: ""
imageUrl: "system.entityToResolve.value.image"
iteratorVariable: "system.entityToResolve.value.enumValues"
actions:
- label: "Order Now"
type: "postback"
payload:
variables:
pizza: "${enumValue}"
channelCustomProperties:
- channel: "apple"
properties:
images:
- identifier: image1
imageUrl: "https://example.com/url1.jpg"
- identifier: image2
imageUrl: "https://example.com/url2.jpg"
receivedMessage:
imageIdentifier: "image1"
style: "small"
subtitle: "Fresh baked for you"
title: "Select Your Pizza"
replyMessage:
title: "Selected Pizza"
style: "small"
imageIdentifier: "image2"
Examples: Single-Select ListPicker Using editForm
responseItems:
- headerText: "Let's start Shopping!"
type: editForm
formColumns: 1
items:
- displayType: singleSelect
name: selectHeadset
options:
- label: "Logitech® G435 LIGHTSPEED Wireless Gaming Headset"
value: LogitechG435
channelCustomProperties:
- channel: apple
properties:
imageIdentifier: logitech g435
- label: "JBL Live 660NC Wireless Over-Ear NC Headphones"
value: JBL660NC
channelCustomProperties:
- channel: apple
properties:
imageIdentifier: jbl 660nc
- label: "Altec Lansing® 3-In-1, MZX4100-PGRN-STK-6"
value: altec
channelCustomProperties:
- channel: apple
properties:
imageIdentifier: altec
label: Select the headset of your choice
placeholder: Tap to select the product
channelCustomProperties:
- channel: apple
properties:
subtitle: Headset of your choice
required: true
actions:
- processingMethod: mapVariable
variable: skill.skillSelectedProduct
label: Submit
type: submitForm
channelCustomProperties:
- channel: apple
properties:
showSummary: true
receivedMessage:
imageIdentifier: main
subtitle: Personalized search on basis of your requirements
style: large
title: "Tap & Select Headphones"
images:
- identifier: main
imageUrl: "https://example.com/b/shopping-cart-headphones-23724543.jpg"
- identifier: logitech g435
imageUrl: "https://example.com/60_o01_040122/2310460.jpg"
description: "Play never ends with G435."
- identifier: jbl 660nc
imageUrl: "https://example.com/7693360_o01/7693360.jpg"
description: "Enjoy while studying or working out."
- identifier: altec
imageUrl: "https://example.com/18_o01_110422/5159518.jpg"
description: "Simple setup."
replyMessage:
imageIdentifier: logitech g435
subtitle: "Your cart is ready!"
style: icon
title: Tap to view your response.
ListPicker (Multi-Select)
responseItems:
- headerText: Choose the type of product you are looking
type: editForm
formColumns: 1
items:
- displayType: multiSelect
name: features
options:
- label: Noise cancellation
value: Noise cancellation
- label: Microphone/Remote
value: Microphone/Remote
- label: Wireless
value: Wireless
- label: USB connectivity
value: USB connectivity
- label: Voice Assistant Support
value: Voice Assistant Support
- label: Fast Charging
value: Fast Charging
label: What features are you looking for?
placeholder: Select multiple-values
required: true
- displayType: multiSelect
name: usage
options:
- label: Attending Online Meetings
value: Attending Online Meetings
- label: Music
value: Music
- label: Casual usage
value: Casual usage
- label: Binge Watching
value: Binge Watching
- label: Jogging/Gym
value: Jogging/Gym
label: Your purpose of usage
placeholder: Select multiple-values
required: true
actions:
- processingMethod: mapVariable
variable: requirementMap
label: Submit
type: submitForm
channelCustomProperties:
- channel: apple
properties:
receivedMessage:
imageIdentifier: main
subtitle: "Customize your product search!"
style: icon
title: "Tap & Provide your Preferences"
images:
- identifier: main
imageUrl: "https://example.com/images/search-filter-icon.jpg"
- identifier: filter
imageUrl: "https://example.com/images/filter.jpg"
replyMessage:
imageIdentifier: filter
style: icon
Time Picker
You use the Time Picker message type in Apples Messages
for Business to offer the users a time slots. Each timePicker
field
element in the editForm
corresponds to one time slot that user can
pick. You use the defaultValue
property to set the start time and the
Apple channel custom property duration
to set the duration of the time
slot in seconds. There are also Apple channel custom properties for
timeZoneOffset
and location
.
Example: Time Picker
responseItems:
- headerText: "Select Date & Time for your appointment"
type: editForm
formColumns: 2
items:
- displayType: timePicker
defaultValue: "2023-05-10T06:00Z"
name: 27JanOne
label: Slots available
channelCustomProperties:
- channel: apple
properties:
duration: 1800
required: true
- displayType: timePicker
defaultValue: "2023-05-05T07:30Z"
name: 27JanTwo
label: Enter Time
channelCustomProperties:
- channel: apple
properties:
duration: 1800
required: true
- displayType: timePicker
defaultValue: "2023-05-11T07:30Z"
name: 24th
label: another time
channelCustomProperties:
- channel: apple
properties:
duration: 1800
required: true
actions:
- label: Submit
type: submitForm
channelCustomProperties:
- channel: apple
properties:
receivedMessage:
imageIdentifier: clock
subtitle: "Every slot is of 30 mins.!"
style: large
title: "Tap & Select from available Slots"
images:
- identifier: clock
imageUrl: "https://example.com/images/clock.png"
description: clock
timezoneOffset: 1200
replyMessage:
imageIdentifier: clock
style: icon
title: Selected Slot
location:
latitude: 28.605354
radius: 1.5
title: Supremo Customer Service Center
longitude: 77.053546
Apple Form
You can create Apple form messages using the editForm
response item type with a combination of the following field types:
numberInput
textInput
datePicker
timePicker
singleSelect
multiSelect
In addition to the custom channel properties you need for the various fields in the form, you use the following Apple channel custom properties for the form as a whole:
submitForm
, which you set totrue
for the last item in the form.pickerTitle
, which you can optionally use to set text shown to a given picker text field.selectedItemIndex
, which you can optionally use to set to the index number of the item that you want selected by default. The default is0
.
You define a welcome page for the form with the splash
Apple channel custom property. The splash
property contains the
following elements:
header
.splashText
.buttonTitle
. The text that appears on the button. This is required.imageIdentifier
.
Example: Apple Form
responseItems:
- headerText: Provide Delivery Address details
type: editForm
formColumns: 1
items:
- displayType: textInput
name: house_address
label: House No.
required: true
maxLength: 100
channelCustomProperties:
- channel: apple
properties:
subtitle: Your House/Appartment No.
options:
keyboardType: numberPad
- displayType: textInput
name: street_address
label: Street Name
channelCustomProperties:
- channel: apple
properties:
subtitle: Your Street Details
options:
keyboardType: default
required: true
maxLength: 200
- displayType: numberInput
name: zipcode
label: Where do you live?
placeholder: Enter your area zipcode
channelCustomProperties:
- channel: apple
properties:
subtitle: Zip-code
required: true
actions:
- label: Submit
type: submitForm
channelCustomProperties:
- channel: apple
properties:
showSummary: true
receivedMessage:
imageIdentifier: main
subtitle: "Add your details carefully!"
style: icon
title: "Tap & Provide your Delivery details"
images:
- identifier: main
imageUrl: "https://example.com/delivery-address.png"
- identifier: saveAddress
imageUrl: "https://example.com/successful-delivery.png"
replyMessage:
imageIdentifier: saveAddress
style: icon
title: Your address details are saved. Tap to review.
splash:
imageIdentifier: main
Authentication
You can use Digital Assistant's OAuth Account Link component for Authentication messages in Apple Messages for Business. There are two approaches you can use:
- In the OAuth Account Link component's Authorize URL property,
provide
responseType
andscope
query parameters.Upon successful authentication, it returns an authorization code, which you then use to fetch an access token.
- In the OAuth Account Link component's Authorize URL property,
provide
responseType
,clientSecret
, andscope
query parameters.Upon successful authentication, it returns an access token.
iMessage App
With Apple Messages for Business, you can create messages of type iMessage App, which are custom interactive data messages. To get those messages working within an Apple Messages for Business channel in Digital Assistant, you need to construct the Apple interactive data payload in the skill itself using a custom component.
The custom component should send a raw Common Message Model (CMM) message containing the following payload attributes:
type: interactive
(required)interactiveData
:appIcon
appId
appName
URL
(required)bid
(required)receivedMessage
replyMessage
useLiveLayout
For a tutorial on creating an iMessage app, see Integrating Your iMessage App in Apple's documentation.
For information on using Digital Assistant's Common Message Model, see Conversation Messaging section of the Bots Node SDK documentation.
Example: iMessage App Payload
{
"type": "interactive",
"interactiveData": {
"appId": 12345678,
"appName": "Package Delivery",
"URL": "?name=WWDC%20Goodies&deliveryDate=09-06-2017&destinationName=Moscone%20Convention%20Center&street=747%20Howard%20St&state=CA&city=San%20
Fransisco&country=USA&postalCode=94103&latitude=37%2E7831&longitude=%2D122%2E4041&extraCharge=15%2E00",
"bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:4R3L6Z3UP2:com.example.apple-samplecode.PackageDelivery4R3L6Z3UP2.MessagesExtension",
"receivedMessage": {
"title": "PackageDelivery",
"subtitle": "Tap to Install the iMessage App from App Store"
}
}
}
ChannelCustomProperties for Apple Messages for Business
Name | Allowed Values | Applies To... | Description |
---|---|---|---|
images |
Nested object with the following properties:
|
editForm reponse items.
|
Images that you define for use in list items and other places in your form. |
receivedMessage |
Nested object with the following properties, all of
which are optional:
|
editForm reponse items
|
The message that appears above a list picker or other message type. |
replyMessage |
Nested object with the following properties, all of which
are optional:
|
editForm reponse items
|
The message that appears after the user has made a selection with a given picker. |
location |
Nested object with the following
properties:
|
editForm reponse items.
|
Provides coordinates for a given location. |
showSummary |
|
editForm reponse items.
|
If true , a summary of the options the
user has selected are displayed. Defaults to
false .
|
splash |
Nested object with the following properties:
|
editForm reponse items.
|
Used to define a welcome page for the form. |
timeZoneOffset |
A number | editForm reponse items.
|
The difference in minutes between the time in the location's time zone and GMT. |
imageIdentifier |
Strings that match the identifier value
for any images in the images array.
|
Objects in the options array in
editForm reponse items.
|
Used to apply an image to a given option in response
items of type editForm .
|
subtitle |
Any string. | editForm reponse items.
|
Optional subtitle for a list
picker.
Note:
Properties such as |
duration |
A number. | editForm reponse items with a
displayType of timePicker |
The number of seconds the duration. |
options |
Nested object with properties such as
keyboardType and dateFormat .
There are separate options for datePicker and
input page types. See Apple's Form Message
documentation.
|
editForm reponse items with a
displayType of datePicker and
textInput .
|
A category of properties specific to the Apple Messages
for Business channel that can be used on individual items.
Note: This category is distinct from the
|
submitForm |
false |
On individual items in the dataSet
response item type.
|
Set to true if you want the form to be
sent when the item is selected. Defaults to
false .
|
pickerTitle |
String | On individual items in the dataSet
response item type.
|
A string value representing optional text shown next to the picker text field. This value defaults to an empty string. When empty the picker text field centers to the page |
selectedItemIndex |
Number | On individual items in the dataSet
response item type.
|
Optionally use to set to the index number of the item in
a picker that you want selected by default. The default is
0 .
|