Mensajes de Apple admitidos para funciones empresariales

Para las aptitudes que exponga a través de los canales de Apple Messages for Business en Oracle Digital Assistant, puede utilizar funciones específicas de Apple Messages for Business, además de las funciones que generalmente se admiten en otros canales.

Para ello, se suele utilizar el elemento channelCustomProperties en los componentes de Common Response para insertar propiedades específicas de Apple.

El código tiene el formato siguiente:

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

Enlace enriquecido

Para incorporar mensajes de enlace enriquecido en mensajes de Apple para canales de negocio, utilice la propiedad personalizada de canal richLinkData y su subpropiedad assets. La propiedad assets puede tomar un objeto image o un objeto video, como se muestra en este ejemplo:

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"

Ejemplo: imagen de enlace enriquecido

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"

Ejemplo: vídeo de enlace enriquecido

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-

Respuesta Rápida

El tipo de mensaje de respuesta rápida es una convención que se utiliza en mensajes de manzana para negocio para proporcionar de dos a cinco respuestas predefinidas que un usuario puede seleccionar con un solo toque.

Puede definir el texto de resumen de la respuesta rápida mediante la propiedad personalizada del canal summaryText:

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

Si no proporciona la propiedad summaryText, el canal utiliza la propiedad text en su lugar.

Además, tenga en cuenta lo siguiente:

summaryText no debe tener más de 25 caracteres.
Para las palabras clave, utilice A, B, C, D y E (en lugar de números).

Ejemplo: Respuesta Rápida

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

Selector de listas

Los mensajes de Apple para empresas tienen un tipo de mensaje de selector de lista que puede utilizar para permitir a los usuarios seleccionar una o más opciones. Para incorporar mensajes del selector de listas en los canales de Apple Messages for Business, utilice las siguientes propiedades personalizadas del canal de Apple:

images. Esta es una lista de objetos que utilizan las propiedades receivedMessage y replyMessage y que contienen los siguientes elementos:
- identifier: identificador mediante el cual otras propiedades hacen referencia a la imagen.
- imageUrl: URL de la imagen que se va a mostrar.
- description.
receivedMessage. Se trata de un objeto con los siguientes elementos opcionales:
- imageIdentifier. Su valor debe coincidir con la propiedad identifier de una de las imágenes definidas en la propiedad personalizada images.
- style. Los valores posibles son icon, small y large.
- subtitle.
- title.
replyMessage. Se trata de un objeto con los siguientes elementos opcionales:
- imageIdentifier. Su valor debe coincidir con la propiedad identifier de una de las imágenes definidas en la propiedad personalizada images.
- style. Los valores posibles son icon, small y large.
- subtitle.
- title.
imageIdentifier. Puede utilizar esta propiedad dentro del elemento channelCustomProperties del elemento options para agregar imágenes a las opciones del selector. Su valor debe coincidir con la propiedad identifier de una de las imágenes definidas en la propiedad personalizada images.

Puede crear selectores de lista de selección única mediante los tipos de elementos de respuesta cards o editForm.

Para los selectores de lista de selección única que utilizan editForm:

Defina displayType para los elementos en "singleSelect".

Para los selectores de lista de selección múltiple, utilice el tipo de elemento de respuesta editForm:

Defina displayType para los elementos en "multiSelect".

También puede crear selectores de lista con varias secciones mediante cualquier combinación de listas singleSelect y multiSelect. Para ello, cree una entrada en items para cada sección y defina el valor displayType de cada entrada en "singleSelect" o "multiSelect", según el tipo de lista que desee para esa sección.

Ejemplo: selector de lista de selección única mediante tarjetas

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"

Ejemplos: ListPicker de selección única con 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 (selección múltiple)

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

Selector de hora

Puede utilizar el tipo de mensaje Selector de tiempo en Mensajes de manzana para negocio para ofrecer a los usuarios intervalos de tiempo. Cada elemento de campo timePicker de editForm corresponde a un intervalo de tiempo que el usuario puede seleccionar. La propiedad defaultValue se utiliza para definir la hora de inicio y la propiedad personalizada del canal de Apple duration para definir la duración del intervalo de tiempo en segundos. También hay propiedades personalizadas del canal de Apple para timeZoneOffset y location.

Ejemplo: selector de hora

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

Formulario de Apple

Puede crear mensajes de formulario de Apple mediante el tipo de elemento de respuesta editForm con una combinación de los siguientes tipos de campos:

numberInput
textInput
datePicker
timePicker
singleSelect
multiSelect

Además de las propiedades de canal personalizadas que necesita para los distintos campos del formulario, utilice las siguientes propiedades personalizadas de canal de Apple para el formulario en su conjunto:

submitForm, que se define en true para el último elemento del formulario.
pickerTitle, que puede utilizar opcionalmente para definir el texto que se muestra en un campo de texto de selector determinado.
selectedItemIndex, que puede utilizar opcionalmente para definir en el número de índice del elemento que desea seleccionar por defecto. El valor por defecto es 0.

Puede definir una página de bienvenida para el formulario con la propiedad personalizada de canal de Apple splash. La propiedad splash contiene los siguientes elementos:

header.
splashText.
buttonTitle. Texto que aparece en el botón. Es obligatorio.
imageIdentifier.

Ejemplo: formulario de Apple

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

Autenticación

Puede utilizar el componente Vínculo de cuenta OAuth de Digital Assistant para mensajes de autenticación en Apple Messages for Business. Hay dos enfoques que puede utilizar:

En la propiedad Autorizar URL del componente de enlace de cuenta OAuth, proporcione los parámetros de consulta responseType y scope.
Tras una autenticación correcta, devuelve un código de autorización que se utiliza para recuperar un token de acceso.
En la propiedad Autorizar URL del componente de enlace de cuenta OAuth, proporcione los parámetros de consulta responseType, clientSecret y scope.
Tras la autenticación correcta, devuelve un token de acceso.

Aplicación iMessage

Con Apple Messages for Business, puede crear mensajes de tipo iMessage App, que son mensajes de datos interactivos personalizados. Para que esos mensajes funcionen dentro de un canal Apple Messages for Business en Digital Assistant, debe crear la carga útil de datos interactiva de Apple en la aptitud mediante un componente personalizado.

El componente personalizado debe enviar un mensaje raw de Common Message Model (CMM) que contenga los siguientes atributos de carga útil:

type: interactive (necesario)
interactiveData :
- appIcon
- appId
- appName
- URL (necesario)
- bid (necesario)
- receivedMessage
- replyMessage
- useLiveLayout

Para obtener un tutorial sobre la creación de una aplicación iMessage, consulte Integración de la aplicación iMessage en la documentación de Apple.

Para obtener información sobre el uso del modelo de mensajes común de Digital Assistant, consulte la sección Mensajería de conversación de la documentación del SDK del nodo de bots.

Ejemplo: carga útil de la aplicación iMessage

{
  "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 para Apple Messages for Business

Nombre	Valores permitidos	Se aplica a...	Descripción
`images`	Objeto anidado con las siguientes propiedades: `imageUrl` `identifier`, que es la cadena mediante la cual se hace referencia a la imagen desde el elemento `imageIdentifier` de otras propiedades, como `receivedMessage`. `description`, que es una descripción textual opcional de la imagen.	`editForm` elementos de respuesta.	Imágenes que defina para su uso en elementos de lista y otros lugares del formulario.
`receivedMessage`	Objeto anidado con las siguientes propiedades, todas ellas opcionales: `imageIdentifier` `style` `subtitle` `title`	`editForm` elementos de respuesta	Mensaje que aparece sobre un selector de lista u otro tipo de mensaje.
`replyMessage`	Objeto anidado con las siguientes propiedades, todas ellas opcionales: `imageIdentifier` `style` `subtitle` `title`	`editForm` elementos de respuesta	Mensaje que aparece después de que el usuario ha realizado una selección con un selector determinado.
`location`	Objeto anidado con las siguientes propiedades: `latitude` `longitude` `radius` `title`	`editForm` elementos de respuesta.	Proporciona coordenadas para una ubicación determinada.
`showSummary`	`true` `false`	`editForm` elementos de respuesta.	Si es `true`, se muestra un resumen de las opciones que el usuario ha seleccionado. Toma `false` como valor por defecto.
`splash`	Objeto anidado con las siguientes propiedades: `imageIdentifier` `buttonTitle` `header` `splashText`	`editForm` elementos de respuesta.	Se utiliza para definir una página de bienvenida para el formulario.
`timeZoneOffset`	A number	`editForm` elementos de respuesta.	La diferencia en minutos entre la hora en la zona horaria de la ubicación y GMT.
`imageIdentifier`	Cadenas que coinciden con el valor `identifier` para cualquier imagen de la matriz `images`.	Objetos de la matriz `options` en los elementos de respuesta `editForm`.	Se utiliza para aplicar una imagen a una opción determinada en elementos de respuesta de tipo `editForm`.
`subtitle`	Cualquier cadena.	`editForm` elementos de respuesta.	Subtítulo opcional para un selector de lista. Nota: las propiedades como `receivedMessage` y `replyMessage` también tienen un elemento `subtitle` opcional.
`duration`	A number.	`editForm` elementos de respuesta con un `displayType` de `timePicker`	Número de segundos de duración.
`options`	Objeto anidado con propiedades como `keyboardType` y `dateFormat`. Hay opciones independientes para los tipos de página `datePicker` y `input`. Consulte la documentación de mensajes de formulario de Apple.	`editForm` responde a los elementos con un `displayType` de `datePicker` y `textInput`.	Categoría de propiedades específicas del canal Mensajes de Apple para empresas que se pueden utilizar en artículos individuales. Nota: esta categoría es distinta del elemento `options` del elemento `items` en los elementos de respuesta `editForm`.
`submitForm`	`true` `false` o `false`	En elementos individuales del tipo de elemento de respuesta `dataSet`.	Establézcalo en `true` si desea que se envíe el formulario cuando se seleccione el elemento. Toma `false` como valor por defecto.
`pickerTitle`	Cadena	En elementos individuales del tipo de elemento de respuesta `dataSet`.	Valor de cadena que representa el texto opcional que se muestra junto al campo de texto del selector. Este valor por defecto es una cadena vacía. Cuando está vacío, el campo de texto del selector se centra en la página
`selectedItemIndex`	Número	En elementos individuales del tipo de elemento de respuesta `dataSet`.	Opcionalmente, se utiliza para definir el número de índice del elemento en un selector que desea seleccionar por defecto. El valor por defecto es `0`.

Documentación de Oracle Cloud Infrastructure