Unterstützte Apple-Nachrichten für Geschäftsfeatures

Für Skills, die Sie über Apple Messages for Business-Kanäle in Oracle Digital Assistant verfügbar machen, können Sie Features verwenden, die für Apple Messages for Business spezifisch sind, zusätzlich zu den Features, die in der Regel über andere Kanäle unterstützt werden.

Dazu verwenden Sie im Allgemeinen das Element channelCustomProperties in Common Response-Komponenten, um Apple-spezifische Eigenschaften einzufügen.

Der Code hat das folgende Format:

...
            channelCustomProperties:
            - channel: "apple"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

Rich Link

Um Rich-Link-Nachrichten in Apple Messages for Business-Kanäle zu integrieren, verwenden Sie die benutzerdefinierte Eigenschaft des Kanals richLinkData und die zugehörige Untereigenschaft assets. Die Eigenschaft assets kann entweder ein image-Objekt oder ein video-Objekt annehmen, wie in diesem Beispiel dargestellt:

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"

Beispiel: 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"

Beispiel: 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-

Kurzantwort

Der Nachrichtentyp "Schnellantwort" ist eine Konvention, die in Apples Messages for Business verwendet wird, um zwei bis fünf vordefinierte Antworten bereitzustellen, die ein Benutzer mit einem einzigen Tippen auswählen kann.

Sie können den Zusammenfassungstext der Schnellantwort mit der benutzerdefinierten Eigenschaft des Kanals summaryText festlegen:

channelCustomProperties:
  - channel: apple
    properties:
      summaryText: Your selection

Wenn Sie die Eigenschaft summaryText nicht angeben, verwendet der Kanal stattdessen die Eigenschaft text.

Beachten Sie außerdem Folgendes:

  • summaryText darf nicht mehr als 25 Zeichen enthalten.
  • Bei Schlüsselwörtern verwenden Sie A, B, C, D und E (anstelle von Zahlen).

Beispiel: Kurzantwort

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

Listenauswahl

Apple Messages for Business hat den Typ List Picker message, mit dem Sie Benutzern die Auswahl einer oder mehrerer Optionen ermöglichen können. Um List Picker-Nachrichten in Apple Messages for Business-Kanäle zu integrieren, verwenden Sie die folgenden benutzerdefinierten Eigenschaften des Apple-Kanals:

  • images. Diese Liste enthält Objekte, die von den Eigenschaften receivedMessage und replyMessage verwendet werden und die folgenden Elemente enthalten:
    • identifier: Die ID, mit der das Image von anderen Eigenschaften referenziert wird.
    • imageUrl: Die URL des anzuzeigenden Bildes.
    • description.
  • receivedMessage. Dies ist ein Objekt mit den folgenden optionalen Elementen:
    • imageIdentifier. Der Wert muss mit der Eigenschaft identifier eines der in der benutzerdefinierten Eigenschaft images definierten Images übereinstimmen.
    • style. Die möglichen Werte sind icon, small und large.
    • subtitle.
    • title.
  • replyMessage. Dies ist ein Objekt mit den folgenden optionalen Elementen:
    • imageIdentifier. Der Wert muss mit der Eigenschaft identifier eines der in der benutzerdefinierten Eigenschaft images definierten Images übereinstimmen.
    • style. Die möglichen Werte sind icon, small und large.
    • subtitle.
    • title.
  • imageIdentifier. Sie können diese Eigenschaft im Element channelCustomProperties des Elements options verwenden, um den Optionen in der Auswahl Bilder hinzuzufügen. Der Wert muss mit der Eigenschaft identifier eines der in der benutzerdefinierten Eigenschaft images definierten Images übereinstimmen.

Sie können Einzelauswahllistenauswahlen mit den Antwortelementtypen cards oder editForm erstellen.

Für Einfachauswahllisten mit editForm:

  • Setzen Sie displayType für die Elemente auf "singleSelect".

Verwenden Sie für Mehrfachauswahllistenauswahl den Antwortelementtyp editForm:

  • Setzen Sie displayType für die Elemente auf "multiSelect".

Sie können Listenauswahlen mit mehreren Abschnitten auch mit einer beliebigen Kombination aus singleSelect- und multiSelect-Listen erstellen. Dazu erstellen Sie einen Eintrag in der items für jeden Abschnitt und setzen den displayType jedes Eintrags auf "singleSelect" oder "multiSelect", je nachdem, welchen Listentyp Sie für diesen Abschnitt verwenden möchten.

Beispiel: Einfachauswahlliste mit Karten

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"

Beispiele: Einfachauswahl ListPicker mit 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 (Mehrfachauswahl)

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

Zeitauswahl

Mit dem Meldungstyp Zeitauswahl in "Apples Messages for Business" können Sie Benutzern Zeitfenster anbieten. Jedes timePicker-Feldelement im editForm entspricht einem Zeitfenster, das der Benutzer auswählen kann. Mit der Eigenschaft defaultValue legen Sie die Startzeit fest, und mit der benutzerdefinierten Eigenschaft duration des Apple-Kanals legen Sie die Dauer des Zeitfensters in Sekunden fest. Es gibt auch benutzerdefinierte Apple-Channel-Eigenschaften für timeZoneOffset und location.

Beispiel: Zeitauswahl

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-Formular

Sie können Apple-Formularnachrichten mit dem Antwortelementtyp editForm mit einer Kombination der folgenden Feldtypen erstellen:

  • numberInput
  • textInput
  • datePicker
  • timePicker
  • singleSelect
  • multiSelect

Neben den benutzerdefinierten Kanaleigenschaften, die Sie für die verschiedenen Felder im Formular benötigen, verwenden Sie die folgenden benutzerdefinierten Apple-Kanaleigenschaften für das Formular als Ganzes:

  • submitForm, das Sie für das letzte Element im Formular auf true setzen.
  • pickerTitle, mit dem Sie optional Text festlegen können, der einem bestimmten Auswahltextfeld angezeigt wird.
  • selectedItemIndex, mit dem Sie optional die Indexnummer des Elements festlegen können, das Sie standardmäßig auswählen möchten. Der Standard ist 0.

Sie definieren eine Willkommensseite für das Formular mit der benutzerdefinierten Eigenschaft splash des Apple-Kanals. Die Eigenschaft splash enthält die folgenden Elemente:

  • header.
  • splashText.
  • buttonTitle. Der auf der Schaltfläche angezeigte Text. Dies ist ein Pflichtfeld.
  • imageIdentifier.

Beispiel: Apple-Formular

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

Authentifizierung

Sie können die Komponente OAuth-Accountlink von Digital Assistant für Authentifizierungsnachrichten in Apple Messages for Business verwenden. Es gibt zwei Ansätze, die Sie verwenden können:

  • Geben Sie in der Eigenschaft URL autorisieren der Accountlinkkomponente OAuth die Abfrageparameter responseType und scope an.

    Nach erfolgreicher Authentifizierung wird ein Autorisierungscode zurückgegeben, mit dem Sie ein Zugriffstoken abrufen können.

  • Geben Sie in der Eigenschaft URL autorisieren der Accountlinkkomponente OAuth die Abfrageparameter responseType, clientSecret und scope an.

    Nach erfolgreicher Authentifizierung wird ein Zugriffstoken zurückgegeben.

iMessage-Anwendung

Mit Apple Messages for Business können Sie Nachrichten vom Typ iMessage App erstellen, bei denen es sich um benutzerdefinierte interaktive Datennachrichten handelt. Damit diese Nachrichten in einem Apple Messages for Business-Kanal in Digital Assistant funktionieren, müssen Sie die interaktive Apple-Daten-Payload im Skill selbst mit einer benutzerdefinierten Komponente erstellen.

Die benutzerdefinierte Komponente muss eine Raw-Nachricht des Common Message Model (CMM) senden, die folgende Payload-Attribute enthält:

  • type: interactive (erforderlich)
  • interactiveData :
    • appIcon
    • appId
    • appName
    • URL (erforderlich)
    • bid (erforderlich)
    • receivedMessage
    • replyMessage
    • useLiveLayout

Ein Tutorial zum Erstellen einer iMessage-App finden Sie unter Integration Ihrer iMessage-App in der Apple-Dokumentation.

Informationen zur Verwendung des gemeinsamen Nachrichtenmodells von Digital Assistant finden Sie im Abschnitt Unterhaltungs-Messaging in der Dokumentation zum Bots-Knoten-SDK.

Beispiel: 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 für Apple Messages for Business

Name Zulässige Werte Gültig für... Beschreibung
images Verschachteltes Objekt mit den folgenden Eigenschaften:
  • imageUrl
  • identifier, die Zeichenfolge, mit der das Bild vom Element imageIdentifier anderer Eigenschaften referenziert wird, wie receivedMessage.
  • description, eine optionale Textbeschreibung des Bildes.
editForm-Antwortelemente. Bilder, die Sie für die Verwendung in Listenelementen und an anderen Stellen in Ihrem Formular definieren.
receivedMessage Verschachteltes Objekt mit den folgenden Eigenschaften, die alle optional sind:
  • imageIdentifier
  • style
  • subtitle
  • title
editForm Antwortelemente Die Nachricht, die über einer Listenauswahl oder einem anderen Nachrichtentyp angezeigt wird.
replyMessage Verschachteltes Objekt mit den folgenden Eigenschaften, die alle optional sind:
  • imageIdentifier
  • style
  • subtitle
  • title
editForm Antwortelemente Die Meldung, die angezeigt wird, nachdem der Benutzer eine Auswahl mit einer bestimmten Auswahl getroffen hat.
location Verschachteltes Objekt mit den folgenden Eigenschaften:
  • latitude
  • longitude
  • radius
  • title
editForm-Antwortelemente. Bietet Koordinaten für einen bestimmten Standort.
showSummary
  • true
  • false
editForm-Antwortelemente. Wenn Sie true verwenden, wird eine Zusammenfassung der vom Benutzer ausgewählten Optionen angezeigt. Wird standardmäßig auf false gesetzt.
splash Verschachteltes Objekt mit den folgenden Eigenschaften:
  • imageIdentifier
  • buttonTitle
  • header
  • splashText
editForm-Antwortelemente. Wird zum Definieren einer Willkommensseite für das Formular verwendet.
timeZoneOffset A-Nummer editForm-Antwortelemente. Die Differenz in Minuten zwischen der Zeit in der Zeitzone des Standorts und GMT.
imageIdentifier Zeichenfolgen, die mit dem Wert identifier für Bilder im Array images übereinstimmen. Objekte im Array options in editForm-Antwortelementen. Wird verwendet, um ein Bild auf eine bestimmte Option in Antwortelementen vom Typ editForm anzuwenden.
subtitle Beliebige Zeichenfolge. editForm-Antwortelemente. Optionaler Untertitel für eine Listenauswahl.

Hinweis: Eigenschaften wie receivedMessage und replyMessage haben auch ein optionales subtitle-Element.

duration A number. editForm-Antwortelemente mit dem displayType timePicker Die Anzahl der Sekunden für die Dauer.
options Verschachteltes Objekt mit Eigenschaften wie keyboardType und dateFormat. Es gibt separate Optionen für die Seitentypen datePicker und input. Siehe Dokumentation zu Formularnachrichten von Apple. editForm-Antwortelemente mit dem displayType datePicker und textInput. Eine Kategorie von Eigenschaften, die für den Apple Messages for Business-Kanal spezifisch sind und für einzelne Elemente verwendet werden können.

Hinweis: Diese Kategorie unterscheidet sich vom options-Element des items-Elements in editForm-Antwortelementen.

submitForm
  • true
  • false
oder false
Für einzelne Elemente im Antwortelementtyp dataSet. Setzen Sie den Wert auf true, wenn das Formular bei der Auswahl des Elements gesendet werden soll. Wird standardmäßig auf false gesetzt.
pickerTitle Zeichenfolge Für einzelne Elemente im Antwortelementtyp dataSet. Ein Zeichenfolgenwert, der optionalen Text darstellt, der neben dem Auswahltextfeld angezeigt wird. Dieser Wert ist standardmäßig eine leere Zeichenfolge. Wenn das Auswahl-Textfeld leer ist, wird die Seite zentriert
selectedItemIndex Zahl Für einzelne Elemente im Antwortelementtyp dataSet. Optional können Sie die Indexnummer des Artikels in einer Auswahl festlegen, die standardmäßig ausgewählt werden soll. Der Standard lautet 0.