Documentação do Oracle Cloud Infrastructure

Mensagens da Apple com suporte para recursos de negócios

Para habilidades que você expõe por meio de canais do Apple Messages for Business no Oracle Digital Assistant, você pode usar recursos específicos do Apple Messages for Business, além dos recursos que geralmente são suportados em outros canais.

Para fazer isso, geralmente você usa o elemento channelCustomProperties nos componentes de Resposta Comum para inserir propriedades específicas da Apple.

O código tem o seguinte formato:

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

Link Rich

Para incorporar Mensagens de Rich Link em Mensagens Apple para canais de Negócios, você usa a propriedade personalizada do canal richLinkData e sua subpropriedade assets. A propriedade assets pode ter um objeto image ou um objeto video, conforme mostrado nesta amostra: 

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"

Exemplo: Imagem do Rich Link

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"

Exemplo: Vídeo Rich Link

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-

Resposta Rápida

O tipo de mensagem Resposta Rápida é uma convenção usada no Apples Messages for Business para fornecer de duas a cinco respostas predefinidas que um usuário pode selecionar com um único toque.

Você pode definir o texto resumido da Resposta Rápida usando a propriedade personalizada do canal summaryText: 

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

Se você não fornecer a propriedade summaryText, o canal usará a propriedade text.

Além disso, lembre-se do seguinte:

  • summaryText não deve ter mais de 25 caracteres.
  • Para palavras-chave, use A, B, C, D e E (em vez de números).

Exemplo: Resposta 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

Seletor de Lista

O Apple Messages for Business tem um tipo de mensagem Seletor de Lista que você pode usar para permitir que os usuários selecionem uma ou mais opções. Para incorporar mensagens do Seletor de listas nos canais Apple Messages for Business, use as seguintes propriedades personalizadas do canal Apple:

  • images. Esta é uma lista de objetos usados pelas propriedades receivedMessage e replyMessage e que contêm os seguintes elementos:
    • identifier: o identificador pelo qual a imagem é referenciada por outras propriedades.
    • imageUrl: o URL da imagem a ser exibida.
    • description.
  • receivedMessage. Este é um objeto com os seguintes elementos opcionais:
    • imageIdentifier. Seu valor deve corresponder à propriedade identifier de uma das imagens definidas na propriedade personalizada images.
    • style. Os valores possíveis são icon, small e large.
    • subtitle.
    • title.
  • replyMessage. Este é um objeto com os seguintes elementos opcionais:
    • imageIdentifier. Seu valor deve corresponder à propriedade identifier de uma das imagens definidas na propriedade personalizada images.
    • style. Os valores possíveis são icon, small e large.
    • subtitle.
    • title.
  • imageIdentifier. Você pode usar essa propriedade no elemento channelCustomProperties do elemento options para adicionar imagens às opções no seletor. Seu valor deve corresponder à propriedade identifier de uma das imagens definidas na propriedade personalizada images.

Você pode criar seletores de lista de seleção única usando os tipos de item de resposta cards ou editForm.

Para seletores de lista de seleção única usando editForm:

  • Defina displayType para os itens como "singleSelect".

Para seletores de lista com várias seleções, use o tipo de item de resposta editForm:

  • Defina displayType para os itens como "multiSelect".

Você também pode criar seletores de lista com várias seções usando qualquer combinação de listas singleSelect e multiSelect. Você faz isso criando uma entrada no items para cada seção e definindo o displayType de cada entrada como "singleSelect" ou "multiSelect", dependendo do tipo de lista que deseja para essa seção.

Exemplo: Seletor de Lista de Seleção Única Usando Cartões

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"

Exemplos: ListPicker de Seleção Única Usando 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 (Seleção Múltipla)

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

Seletor de Horário

Use o tipo de mensagem Seletor de Tempo em Mensagens do Apples para Negócios para oferecer aos usuários um intervalo de tempo. Cada elemento de campo timePicker no editForm corresponde a um intervalo de tempo que o usuário pode selecionar. Use a propriedade defaultValue para definir o horário de início e a propriedade personalizada do canal Apple duration para definir a duração do intervalo de tempo em segundos. Há também propriedades personalizadas do canal Apple para timeZoneOffset e location.

Exemplo: Seletor de Horário

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

Formulário Apple

Você pode criar mensagens do formulário Apple usando o tipo de item de resposta editForm com uma combinação dos seguintes tipos de campo:

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

Além das propriedades do canal personalizado necessárias para os vários campos no formulário, você usa as seguintes propriedades personalizadas do canal Apple para o formulário como um todo:

  • submitForm, que você definiu como true para o último item no formulário.
  • pickerTitle, que você pode usar opcionalmente para definir o texto mostrado para um determinado campo de texto do seletor.
  • selectedItemIndex, que você pode usar opcionalmente para definir o número do índice do item que deseja selecionar por padrão. O padrão é 0.

Você define uma página de boas-vindas para o formulário com a propriedade personalizada do canal Apple splash. A propriedade splash contém os seguintes elementos:

  • header.
  • splashText.
  • buttonTitle. O texto que aparece no botão. Isso é obrigatório.
  • imageIdentifier.

Exemplo: Formulário 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

Autenticação

Você pode usar o componente OAuth Link da Conta do Digital Assistant para mensagens de Autenticação no Apple Messages for Business. Há duas abordagens que você pode usar:

  • Na propriedade Autorizar URL do componente Link da Conta OAuth, forneça os parâmetros de consulta responseType e scope.

    Após a autenticação bem-sucedida, ele retorna um código de autorização, que você usa para extrair um token de acesso.

  • Na propriedade Autorizar URL do componente Link da Conta OAuth, forneça os parâmetros de consulta responseType, clientSecret e scope.

    Após a autenticação bem-sucedida, ele retorna um token de acesso.

Aplicativo iMessage

Com o Apple Messages for Business, você pode criar mensagens do tipo iMessage App, que são mensagens de dados interativas personalizadas. Para fazer com que essas mensagens funcionem em um canal do Apple Messages for Business no Digital Assistant, você precisa construir a carga útil de dados interativa da Apple na própria habilidade usando um componente personalizado.

O componente personalizado deve enviar uma mensagem CMM (Common Message Model) bruta contendo os seguintes atributos de payload:

  • type: interactive (obrigatório)
  • interactiveData :
    • appIcon
    • appId
    • appName
    • URL (obrigatório)
    • bid (obrigatório)
    • receivedMessage
    • replyMessage
    • useLiveLayout

Para obter um tutorial sobre como criar um aplicativo iMessage, consulte Integração do Seu Aplicativo iMessage na documentação da Apple.

Para obter informações sobre como usar o Modelo de Mensagem Comum do Digital Assistant, consulte a seção Mensagens de Conversa da documentação do SDK do Nó de Bots.

Exemplo: iMessage Payload do Aplicativo

{
  "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 Mensagens da Apple para Empresas

Nome Valores permitidos Aplica-se a... Descrição
images Objeto aninhado com as seguintes propriedades:
  • imageUrl
  • identifier, que é a string pela qual a imagem é referenciada do elemento imageIdentifier de outras propriedades, como receivedMessage.
  • description, que é uma descrição textual opcional da imagem.
editForm itens de resposta. Imagens que você define para uso em itens de lista e outros locais em seu formulário.
receivedMessage Objeto aninhado com as seguintes propriedades, todas opcionais:
  • imageIdentifier
  • style
  • subtitle
  • title
 editForm itens de resposta A mensagem que aparece acima de um seletor de lista ou outro tipo de mensagem.
replyMessage Objeto aninhado com as seguintes propriedades, todas opcionais:
  • imageIdentifier
  • style
  • subtitle
  • title
 editForm itens de resposta A mensagem que aparece depois que o usuário faz uma seleção com um determinado seletor.
location Objeto aninhado com as seguintes propriedades:
  • latitude
  • longitude
  • radius
  • title
 editForm itens de resposta. Fornece coordenadas para um determinado local.
showSummary
  • true
  • false
 editForm itens de resposta. Se true, um resumo das opções selecionadas pelo usuário será exibido. O padrão é false.
splash Objeto aninhado com as seguintes propriedades:
  • imageIdentifier
  • buttonTitle
  • header
  • splashText
 editForm itens de resposta. Usado para definir uma página de boas-vindas para o formulário.
timeZoneOffset Um número editForm itens de resposta. A diferença em minutos entre a hora no fuso horário do local e GMT.
imageIdentifier Strings que correspondem ao valor identifier para qualquer imagem no array images. Objetos no array options nos itens de resposta editForm. Usado para aplicar uma imagem a uma determinada opção em itens de resposta do tipo editForm.
subtitle Qualquer string. editForm itens de resposta. Subtítulo opcional para um seletor de lista.

Observação: Propriedades como receivedMessage e replyMessage também têm um elemento subtitle opcional.

duration Um número. editForm itens de resposta com um displayType de timePicker O número de segundos pela duração.
options Objeto aninhado com propriedades como keyboardType e dateFormat. Há opções separadas para os tipos de página datePicker e input. Consulte a documentação de Mensagem de Formulário da Apple. Itens de resposta editForm com um displayType de datePicker e textInput. Uma categoria de propriedades específicas do canal Apple Messages for Business que pode ser usada em itens individuais.

Observação: Esta categoria é distinta do elemento options do elemento items nos itens de resposta editForm.

submitForm
  • true
  • false
ou false		 Em itens individuais no tipo de item de resposta dataSet. Defina como true se quiser que o formulário seja enviado quando o item for selecionado. O padrão é false.
pickerTitle String Em itens individuais no tipo de item de resposta dataSet. Um valor de string que representa o texto opcional mostrado ao lado do campo de texto do seletor. Este valor assume como padrão uma string vazia. Quando esvaziar os centros de campo de texto do seletor para a página
selectedItemIndex Número Em itens individuais no tipo de item de resposta dataSet. Opcionalmente, use para definir o número do índice do item em um seletor que você deseja selecionar por padrão. O padrão é 0.