Instagram Output

Learn more about output templates for Instagram.

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 an Instagram response below.

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

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

{
  // ...
  platforms: {
    instagram: {
      // ...
    }
  }
}

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

• 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, Instagram 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 Instagram Messaging docs):

{
  "recipient": {
    "id": "<IGSID>"
  },
  "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 Instagram Messaging 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 Instagram quick replies of the type text. Learn more in the official Instagram Messaging documentation. The quick replies are added to a message:

{
  "recipient": {
    "id": "<IGSID>"
  },
  "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.

The generic card element can be used to send a Instagram Messaging generic template.

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

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

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

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

• defaultAction: A URL that is opened in the Instagram 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": "<IGSID>"
  },
  "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 Instagram Messaging docs.

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 Instagram, you can add output elements inside a instagram object:

{
  // ...
  platforms: {
    instagram: {
      // ...
    }
  }
}

These elements include:

• buttons

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-instagram';

// ...

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

    ],
  },
}

Not all button types supported by Facebook Messenger are supported by Instagram. Here is a table of all supported button types:

Learn more about the buttons types in the official Facebook Messenger docs.