Facebook Messenger

Si quiere configurar el canal para Facebook Messenger, necesitará lo siguiente:

Una cuenta de desarrollador de Facebook
Una página de Facebook
Una aplicación Facebook
Un token de acceso a página
Un ID de secreto de aplicación
El URL del webhook
Un token de verificación

Para ejecutar el asistente digital (o una aptitud autónoma) en Facebook Messenger, antes debe configurar una página de Facebook y una aplicación de Facebook. Puede obtener más información al respecto en la documentación de la plataforma de mensajería de Facebook.

En pocas palabras, así es como funciona. La página de Facebook aloja el asistente digital. Los usuarios chatean con el asistente digital a través de esta página cuando utilizan la ventana de chat en un explorador de escritorio. Cuando utilizan un dispositivo móvil, los usuarios interactúan con el asistente digital directamente a través de Facebook Messenger. En este caso, la aplicación Facebook permite al asistente digital obtener los mensajes manejados por Facebook Messenger.

Para crear un canal de Facebook Messenger, necesita artefactos generados por Oracle Digital Assistant y por Facebook Messenger.

De Oracle Digital Assistant, necesitará:

El URL del webhook que conecta el asistente digital con Facebook Messenger
El token de verificación que permite a Facebook Messenger identificar al asistente digital

De Facebook Messenger, necesitará:

El token de acceso a página
El ID de secreto de aplicación

Dado que es necesario transferir estos artefactos entre Digital Assistant y Facebook Messenger, tendrá que ir cambiando entre estas dos plataformas mientras configura el canal.

Paso 1: configuración de Facebook Messenger

Para empezar, genere el secreto de aplicación y el token de acceso a página en Facebook Messenger.

Conéctese a la cuenta del desarrollador de Facebook.
Cree una página de Facebook para alojar el bot. La descripción, las imágenes y la portada que agregue a la página servirán a los usuarios para identificar al bot.
A continuación, cree la aplicación de Facebook que vaya a enlazar con esta página. Puesto que se trata de una aplicación de Messenger, seleccione Apps para Messenger y, a continuación, haga clic en Crear ID de aplicación.

Descripción de la ilustración setup-fbapp.png

Si no ha seleccionado la opción Aplicaciones para Messenger en este cuadro de diálogo (por ejemplo, si va a crear una aplicación de prueba), haga clic en Agregar producto en la barra de navegación izquierda, seleccione Messenger en la página Configuración de producto y, a continuación, haga clic en Comenzar.

Descripción de la ilustración add-product.png
En la página Panel de control de la aplicación de Facebook, copie el secreto de la aplicación y péguelo en un lugar del sistema de fácil acceso.

Descripción de la ilustración facebook-dashboard.png
Necesitará el secreto de aplicación para completar la configuración del canal de Facebook.
En el panel de control de la aplicación, genere el token de acceso a página seleccionando la página de Facebook.

Descripción de la ilustración page-access-token.png
Copie el token de acceso y péguelo en un lugar de fácil acceso.
Utilizará este token, que da a la aplicación Facebook acceso a la API de mensajería de Facebook, para terminar la definición del canal en Digital Assistant.

Nota

Debido a los cambios efectuados en la API del perfil de usuario de Facebook, ahora es necesario solicitar permisos para determinados campos del perfil de usuario en cualquier aplicación de Facebook que se haya creado antes o después del 26 de julio de 2018. Sin los siguientes permisos, el nombre del usuario se rellenará como una cadena numérica aleatoria.

pages_messaging
pages_user_locale
pages_user_timezone

Si ha creado la aplicación antes del 26 de julio, tiene hasta el 29 de enero de 2019 para aplicar los permisos. Si ha creado su aplicación después del 26 de julio de 2018, tiene que agregar los permisos lo antes posible. Puede definirlos en la sección Revisión de aplicación para Messenger de la página de Messenger.

Paso 2: creación del canal en Digital Assistant

Complete el cuadro de diálogo Crear canal proporcionando las claves de token de acceso a página y secreto de aplicación de Facebook.

En Digital Assistant, haga clic en Canales en el menú de la izquierda y, a continuación, seleccione Usuarios.
A continuación, haga clic en Agregar canal para abrir el cuadro de diálogo Crear canal.
Asigne un nombre al canal.
Seleccione Facebook Messenger como tipo de canal.

Descripción de la ilustración create-channel-dialog-started.png
En el campo Token de acceso a página, pegue el token de acceso a página generado anteriormente en el procedimiento de configuración de Facebook Messenger.
En el campo Secreto de aplicación, pegue el secreto de aplicación que haya copiado previamente, en el procedimiento de configuración de Facebook Messenger.
Haga clic en Crear.
En la página Canales, copie tanto el token de verificación como el URL del webhook y péguelos en algún lugar del sistema de fácil acceso. Los necesitará para configurar el webhook de Facebook.

Descripción de la ilustración fb-channel-complete.png

Paso 3: configuración del webhook de Facebook Messenger

En Facebook Messenger, defina el URL de devolución de llamada utilizando el URL del webhook generado por Digital Assistant en el paso anterior.

En Facebook Messenger, asegúrese de haber seleccionado el proyecto creado inicialmente para el webhook.

Descripción de la ilustración fb-messenger-project.png
Haga clic en Messenger y, a continuación, seleccione Configuración.

Descripción de la ilustración fb-navbar.png
Haga clic en Suscribirse a eventos para abrir el cuadro de diálogo Nueva suscripción a página.
Copie el URL del webhook que haya obtenido de la página Canales de Digital Assistant y péguela en el campo URL de devolución de llamada del cuadro de diálogo Nueva suscripción a página.
Copie el token de verificación generado por Digital Assistant y péguelo en el campo del token de verificación.
En Campos de suscripción, seleccione los eventos de devolución de llamada messages y messaging_postbacks.

El evento messages se dispara cuando alguien envía un mensaje a la página de Facebook.
Haga clic en Verificar y guardar.
Suscríbase a la página:
1. En la sección Webhooks de la configuración de Messenger, seleccione la página de Facebook del asistente digital (o la aptitud independiente).
2. Haga clic en Suscribirse.
.

Consejo:
Puede que necesite devolver el webhook. Para ello, haga clic en Cancelar suscripción y, a continuación, en Suscribirse.

Paso 4: activación del canal de Facebook

Una vez terminada la configuración, ya se puede activar el canal de Facebook.

En Digital Assistant, seleccione el canal y active el control Canal activado.
Haga clic en y seleccione el asistente digital o la aptitud que desea asociar al canal.

Ya puede probar el bot en el canal.

Paso 5: prueba del bot en Facebook Messenger

Una vez terminada la configuración del canal de Facebook y la mensajería, puede probar el bot utilizando la página de Facebook, Facebook Messenger (https://www.messenger.com/) y la aplicación de Facebook Messenger en el teléfono (). Una vez ubicado el bot en la búsqueda, ya puede empezar a chatear con él. Puede ver los cambios realizados en el flujo de diálogo en tiempo real.
A continuación se describe el ensayo bot.png
Descripción de la ilustración test-bot.png

Menú persistente

Facebook Messenger permite crear un menú persistente junto al campo Mensaje. Consulte https://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/ para obtener más información sobre esta función.

En el ejemplo siguiente, se muestran las opciones del menú persistente "Order Pizza" y "Order Pasta":

Descripción de persistent-menu.jpg a continuación

Descripción de la ilustración persistente-menu.jpg

Creación de una opción de menú persistente

Para agregar opciones del menú de Facebook persistente a un asistente digital o una aptitud independiente, siga estos pasos:

Asegúrese de cumplir con todos los requisitos, incluido el botón de inicio.
Puede consultar los requisitos aquí: https://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/#requirements
Agregue una acción para cada opción de menú de la matriz call_to_actions del menú persistente de Facebook, como se describe en https://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/#set_menu.
Defina las opciones del menú persistente con una llamada POST a la API de la plataforma de Messenger.
El URI de la solicitud es https://graph.facebook.com/v2.6/me/messenger_profile?access_token=<TOKEN_ACCESO_PÁGINA>, donde <TOKEN_ACCESO_PÁGINA> es el token de acceso a página de la aplicación Facebook.

Opciones del menú persistente para un asistente digital

Aquí se muestra el formato de la llamada POST a la API de la plataforma de Messenger para agregar opciones del menú persistente de Facebook para un asistente digital:

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"menu item display name",
              "type":"postback",
              "payload":"{\"action\":\"system.textReceived\",\"variables\": {\"system.text\": \"utterance that contains the skill's invocation name\"}}"
            }
          ]
    }
  ]
}

Para la carga útil, utilice una acción system.textReceived que transfiera una expresión de Facebook Messenger al asistente digital a través de una variable system.text. Dicha expresión debe contener el nombre de llamada de la aptitud de destino (es decir, una llamada explícita) para garantizar el enrutamiento adecuado.

A continuación, se muestra un ejemplo de la creación de dos opciones del menú persistente para la aptitud en Facebook Messenger ("Order Pizza" y "Order Pasta"):

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"Order Pizza",
              "type":"postback",
              "payload":"{\"action\":\"system.textReceived\",\"variables\": {\"system.text\": \"Order pizza from Pizza Joe \"}"
            },
            {
              "title":"Order Pasta",
              "type":"postback",
              "payload":"{\"action\":\"system.textReceived\",\"variables\": {\"system.text\": \"Order pasta from Pizza Joe \"}"
            }
          ]
    }
  ]
}

Opciones de menú persistentes para una aptitud independiente

Aquí se muestra el formato de la llamada POST a la API de la plataforma de Messenger para agregar opciones del menú persistente de Facebook para una aptitud independiente:

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"menu item display name",
              "type":"postback",
              "payload":"{\"action\":\"action name\",\"variables\": {}"
            }
          ]
    }
  ]
}

La carga útil es el nombre del evento que se asigna al flujo que desea disparar en el flujo de diálogo de la aptitud.

A continuación, puede hacer referencia a la acción de ayuda en el menú persistente de Facebook.

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"Help",
              "type":"postback",
              "payload":"{\"action\":\"help\",\"variables\": {}"
            }
          ]
    }
  ]
}

Capacidades admitidas

Los canales de Facebook Messenger en Digital Assistant admiten las siguientes capacidades:

texto (tanto envío como recepción)
imágenes (tanto envío como recepción)
archivos (tanto envío como recepción)
emojis (tanto envío como recepción)
ubicación, pero en desuso (tanto envío como recepción)
enlaces
devoluciones
solicitudes de ubicación
propiedades personalizadas
componentes del carrusel
componentes de la lista

Si va a dirigir la aptitud a varios canales con diferentes capacidades de formato y sintaxis, puede utilizar el marcado HTML básico en los mensajes. Si lo hace, ese marcado se convertirá automáticamente al formato de rebaja de Facebook Messenger cuando el mensaje se transmita al canal. Esto es particularmente útil si está dirigiendo sus habilidades a otros canales además de Facebook Messenger. Consulte Formato de texto enriquecido en canales.

Restricciones de mensajes

Los canales de Facebook Messenger de Digital Assistant presentan las siguientes restricciones de mensajes:

Mensajes de texto
- Longitud máxima del mensaje de texto: 640 caracteres. Si la longitud supera los 640 caracteres, el texto se dividirá en varios mensajes.
- Longitud máxima de la etiqueta de acción de texto: 20 caracteres
- Tipos de acciones de texto permitidas: devolución, llamada, URL
- Número máximo de acciones de texto: 3. Si hay más acciones de texto, el mensaje se convierte en varias tarjetas horizontales. Cada una de las tarjetas contiene un máximo de 3 acciones e incluye el mismo texto como título.
Tarjetas horizontales
- Longitud máxima del título: 80 caracteres
- Longitud máxima de la descripción: 80 caracteres
- Longitud máxima de la etiqueta de acción de la tarjeta: 20 caracteres
- Número máximo de tarjetas: 10
- Número máximo de acciones de tarjeta: 3. Si hay más de 3 acciones de tarjeta, la tarjeta se duplica para presentar las acciones de tarjeta restantes.
- Número mínimo de acciones de tarjeta: 0
- Número máximo de acciones de lista de tarjeta: 0
- ¿Se necesita al menos una descripción, imagen o acción?: sí
- Tipos de acciones de tarjeta permitidas: devolución, llamada, URL, compartición
- Tipos de acciones de lista de tarjetas permitidas: N/D
Tarjetas verticales
- No se admite
Mensajes anexos
- ¿Se admite?: sí
- ¿Se permiten acciones de anexo?: no
Botones de acción
- Longitud máxima de la etiqueta de acción global: 20 caracteres
- Número máximo de acciones globales: 11
- Tipos de acciones globales permitidas: devolución

Extensiones de canal de Facebook Messenger

En los canales de Facebook Messenger, puede ampliar la funcionalidad de los componentes de respuesta común con capacidades específicas de Facebook.

Para acceder a las extensiones, utilice el elemento channelCustomProperties de los metadatos del componente de respuesta común y defina las propiedades adecuadas. El código tiene el formato siguiente:

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

Estas son las propiedades personalizadas disponibles para los canales de Facebook Messenger:

Nombre de la propiedad	Valores permitidos	Se aplica a...	Descripción
`top_element_style`	`compact` `large`	Elementos de respuesta con los siguientes atributos: `type: "cards"` `cardLayout: "vertical"`	Determina cómo se representa la imagen de la primera tarjeta. Consulte https://developers.facebook.com/docs/messenger-platform/send-messages/template/list/#cover_image para obtener información detallada. Si no se especifica, Oracle Digital Assistant establece por defecto esta propiedad en `compact`, la opción opuesta al valor por defecto de Facebook.
`image_aspect_ratio`	`horizontal` `square`	Elementos de respuesta con los siguientes atributos: `type: "cards"` `cardLayout: "horizontal"`	Ratio de aspecto utilizada para representar imágenes. El valor por defecto es `horizontal` (1.91:1). `square` define la ratio de aspecto en 1:1. Consulte https://developers.facebook.com/docs/messenger-platform/reference/template/generic#attachment
`sharable`	`true` `false`	Elementos de respuesta de tipo `cards`.	Defina esta opción en `true` para activar el botón de uso compartido nativo en Messenger para el mensaje de plantilla. Toma `false` como valor por defecto. Consulte https://developers.facebook.com/docs/messenger-platform/reference/template/generic#attachment
`webview_height_ratio`	`compact` `tall` `full`	Cualquiera de los siguientes: Una tarjeta en la que se especifica la propiedad `"url"` Un elemento `action` donde `"type": "url"`	Altura de la vista web que se abre al pulsar el botón del URL o al pulsar la altura de la tarjeta con la propiedad de URL especificada. Consulte https://developers.facebook.com/docs/messenger-platform/reference/buttons/url#properties
`messenger_extensions`	`true` `false`	Cualquiera de los siguientes: Una tarjeta en la que se especifica la propiedad `"url"` Un elemento `action` donde `"type": "url"`	Las extensiones de Messenger le permiten integrar con precisión las experiencias de la vista web con la experiencia de Messenger, al permitir el acceso a las funcionalidades agregadas en la vista web. Consulte https://developers.facebook.com/docs/messenger-platform/reference/messenger-extensions-sdk
`fallback_url`	Un URL válido	Cualquiera de los siguientes: Una tarjeta en la que se especifica la propiedad `"url"` Un elemento `action` donde `"type": "url"`	URL que se utilizará en los clientes que no admitan las extensiones de Messenger. Si no se define, el `url` se utilizará como reserva. Solo se puede especificar si `messenger_extensions` es true. Consulte https://developers.facebook.com/docs/messenger-platform/reference/buttons/url#properties
`webview_share_button`	`hide`	Cualquiera de los siguientes: Una tarjeta en la que se especifica la propiedad `"url"` Un elemento `action` donde `"type": "url"`	Defínalo en `hide` para desactivar el botón Compartir en la vista web (en el caso de información confidencial). Esto no afecta a los recursos compartidos iniciados por el desarrollador mediante extensiones.
`share_contents`	El formato es el utilizado en la API de envío de Facebook Messenger	Una `acción` donde `"type": "share"`	El mensaje que quiere que vea el destinatario del recurso compartido, si es diferente del que está conectado a este botón. Consulte https://developers.facebook.com/docs/messenger-platform/reference/buttons/share#properties

A continuación, se muestra un ejemplo de las propiedades personalizadas definidas en el nivel de elemento de respuesta (top_element_style) y en el nivel de tarjetas (webview_height_ratio y fallback_url):

responseItems:
  - type: "cards"
    cardLayout: "vertical"
    cards:
      - title: "${pizzas.name}"
        description: "${pizzas.description}"
        imageUrl: "${pizzas.image}"
        url: "${pizzas.moreInfo}"
        iteratorVariable: "pizzas"
        channelCustomProperties:
          - channel: "facebook"
            properties:
              webview_height_ratio: "compact"
              fallback_url: "http://www.oracle.com"
    channelCustomProperties:
      - channel: "facebook"
        properties:
          top_element_style: "large"
...

Para obtener más información general sobre channelCustomProperties, consulte Extensiones específicas del canal.

Documentación de Oracle Cloud Infrastructure