Oracle Cloud Infrastructure Documentation

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, and E (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 the receivedMessage and replyMessage 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 the identifier property of one of the images defined in the images custom property.
    • style. The possible values are icon, small, and large.
    • subtitle.
    • title.
  • replyMessage. This is an object with the following optional elements:
    • imageIdentifier. Its value must match with the identifier property of one of the images defined in the images custom property.
    • style. The possible values are icon, small, and large.
    • subtitle.
    • title.
  • imageIdentifier. You can use this property within the channelCustomProperties element of the options element to add images to the options in the picker. Its value must match with the identifier property of one of the images defined in the images 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 to true 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 is 0.

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 and scope 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, and scope 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:
  • imageUrl
  • identifier, which is the string by which the image is referenced from the imageIdentifier element of other properties, such as receivedMessage.
  • description, which is an optional textual description of the image.
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:
  • imageIdentifier
  • style
  • subtitle
  • title
 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:
  • imageIdentifier
  • style
  • subtitle
  • title
 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:
  • latitude
  • longitude
  • radius
  • title
 editForm reponse items. Provides coordinates for a given location.
showSummary
  • true
  • false
 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:
  • imageIdentifier
  • buttonTitle
  • header
  • splashText
 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 receivedMessage and replyMessage also have an optional subtitle element.

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 options element of the items element in editForm response items.

submitForm
  • true
  • false
or 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.