Facebook Messenger Output

Learn more about output templates for Facebook Messenger.

Jovo offers the ability to create structured output that is then translated into native platform responses.

This structured output is called output template. Its root properties are generic output elements that work across platforms. Learn more about how generic output is translated into a Facebook Messenger response below.

{
  message: `Hello world! What's your name?`;
}

You can also add platform-specific output to an output template. Learn more about Facebook Messenger-specific output below.

{
  // ...
  platforms: {
    facebookMessenger: {
      // ...
    }
  }
}

Generic output elements are in the root of the output template and work across platforms. Learn more in the Jovo output template docs.

Below, you can find a list of generic output elements that work with Facebook Messenger:

• message
• quickReplies
• card
• carousel

The generic message element contains the main response of your bot, which is usually displayed in a chat bubble:

{
  message: 'Hello world!',
}

It is also possible to use message as an object which contains both a speech (the spoken text on platforms like Alexa) and a text (written text to be displayed in chat bubbles) field. In this case, Facebook Messenger uses the text element.

{
  message: {
    speech: 'Hello listener!',
    text: 'Hello reader!'
  }
}

Under the hood, Jovo translates the message into message.text as part of a call to the Facebook Send API (see the official Facebook Messenger docs):

{
  "recipient": {
    "id": "<PSID>"
  },
  "message": {
    "text": "Hello world!"
  }
}

The generic quickReplies element allows you to define small buttons that help the user answer a question faster. This concept is also called quick replies in the Facebook Messenger documentation.

Quick replies can be an array of strings:

{
  // ...
  quickReplies: ['yes', 'no'];
}

Alternatively, you can use an array of objects that includes a text (what the user sees) and a value (what is passed to the bot):

{
  // ...
  quickReplies: [
    {
      text: 'oh yeah',
      value: 'yes',
    },
    {
      text: 'hell no',
      value: 'no',
    },
  ];
}

Under the hood, Jovo translates these into Facebook Messenger quick replies of the type text. Learn more in the official Facebook Messenger documentation. The quick replies are added to a message:

{
  "recipient": {
    "id": "<PSID>"
  },
  "messaging_type": "RESPONSE",
  "message": {
    "quick_replies": [
      {
        "content_type": "text",
        "title": "oh yeah",
        "payload": "yes"
      },
      {
        "content_type": "text",
        "title": "hell no",
        "payload": "no"
      }
    ]
  }
}

The payload is the value that gets passed to the NLU integration to turn raw text into structured content. For quick replies that are passed as strings, the title and payload are the same. If the quick replies are objects, the text gets turned into title and the value into payload.

For other quick reply content types, see nativeQuickReplies below.

The generic card element can be used to send a Facebook Messenger generic template. Learn more about other templates below.

Here is an example of a card with all properties that are supported by Facebook Messenger:

{
  // ...
  card: {
    title: 'Hello world!',
    subtitle: 'Welcome to the show.',
    imageUrl: 'https://...',

    // Facebook Messenger specific properties
    defaultAction: { /* ... */ },
    buttons: [ /* ... */ ]
  },
}

The following values are specific for Facebook Messenger and are described in detail in sections below:

• defaultAction: A URL that is opened in the Facebook Messenger webview when a user taps the template. This element has the same properties as the URL button type that's described in the buttons section below.
• buttons: Up to 3 buttons that can be attached to the card.

Under the hood, Jovo translates the card into the following generic template:

{
  "recipient": {
    "id": "<PSID>"
  },
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "generic",
        "elements": [
          {
            "title": "Hello world!",
            "image_url": "https://...",
            "subtitle": "Welcome to the show.",
            "default_action": {
              "type": "web_url",
              "url": "https://...",
              "webview_height_ratio": "tall"
            },
            "buttons": [
              {
                "type": "postback",
                "title": "Start Chatting",
                "payload": "DEVELOPER_DEFINED_PAYLOAD"
              }
            ]
          }
        ]
      }
    }
  }
}

Learn more about this structure in the official API reference by Facebook.

A generic carousel element is a horizontally scrollable set of card items. In Facebook's definition, this is called a carousel of generic templates.

This is how a carousel can be defined:

{
  // ...
  carousel: {
    items: [
      {
        title: 'Hello world!',
        subtitle: 'Welcome to the show.',
        imageUrl: 'https://...',
      },
      {
        title: 'Hello again!',
        subtitle: 'This is element 2.',
        imageUrl: 'https://...',
      }
    ]
  },
}

The elements in an items array can contain all properties that are shown in the card section.

It is possible to add platform-specific output elements to an output template. Learn more in the Jovo output template documentation.

For Facebook Messenger, you can add output elements inside a facebookMessenger object:

{
  // ...
  platforms: {
    facebookMessenger: {
      // ...
    }
  }
}

These elements include:

• nativeQuickReplies
• template
• buttons

The generic quickReplies element can be used for text based quick replies that are supported by many platforms. Additionally, Facebook Messenger supports quick replies that allow you to ask users for their phone number or their email address.

For this, you can use the nativeQuickReplies element that offers all properties in the same way as they are detailed in the official Facebook Messenger API reference.

Here is an example for a phone number quick reply:

import { QuickReplyContentType } from '@jovotech/platform-facebookmessenger';

// ...

{
  // ...
  platforms: {
    facebookMessenger: {
      nativeQuickReplies: [
        {
          content_type: QuickReplyContentType.UserPhoneNumber, // or 'user_phone_number'
        },
      ];
    }
  }
}

The following quick reply types are supported:

Facebook offers different types of message templates. The generic template (which is the result of the generic card element from above) is one example for structured data that can be displayed. Learn more about templates in the official Facebook Messenger docs](https://developers.facebook.com/docs/messenger-platform/send-messages/templates).

You can add a template like this:

import { TemplateType } from '@jovotech/platform-facebookmessenger';

// ...

{
  // ...
  platforms: {
    facebookMessenger: {
      template: [
        {
          template_type: TemplateType.Receipt, // or 'receipt'
        },
      ];
    }
  }
}

Depending on the type, different properties can be added in the same way they are used in the Facebook Messenger API,for example:

import { TemplateType } from '@jovotech/platform-facebookmessenger';

// ...

{
  // ...
  platforms: {
    facebookMessenger: {
      template: [
        {
          template_type: TemplateType.Receipt, // or 'receipt'
          recipient_name: 'Some Name',
          order_number: '2021100123',
          // ...
        },
      ];
    }
  }
}

Here is a table of all supported template types:

A template gets translated into the following:

{
  "recipient":{
    "id":"<PSID>"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"<TEMPLATE_TYPE>",
        // ...
      }
    }
  }
}

All templates (including the generic card element that gets translated into a generic template) may contain buttons, which are added using the buttons array.

import { ButtonType } from '@jovotech/platform-facebookmessenger';

// ...

{
  // ...
  card: {
    // ...
    buttons: [
      {
        type: ButtonType.Postback, // or 'postback'
        title: 'Start Chatting',
        payload: 'DEVELOPER_DEFINED_PAYLOAD' // what happens with payload?
      }

    ],
  },
}

Here is a table of all supported button types: