AdLingo API Message Responses

version: v2.0.0

Responses need to be sent back synchronously with the request, and be wrapped in the response. The bot can send multiple bot responses in the messages array.

{
  "messages": [
    {
      "type": "text",
      "text": "Hello user"
    }, {
      "type": "text",
      "text": "This is the second message"
    }
  ]
}

Limits

Property Restriction
messages
  • minLength = 1
  • maxLength = 10

Message Types

Text Message

Example text message

Message body

{
  "type": "text",
  "text": string
}

Example of text message

{
  "type": "text",
  "text": "This is a regular message this is a regular message this is a regular message ..."
}

Limits

Property Restriction
type required
text
  • required
  • maxLength = 240 characters

NOTE: text message does not support HTML. If a word break occurs, there will be no hyphens.

Quick Replies

Predefined sayable actions to guide the conversation.

Example quick replies

Message body

{
  "type": "quickReplies",
  "quickReplies": <QUICK_REPLY>[]
}

NOTE: <QUICK_REPLY> refers to the Quick Reply primitive.

Example of quick replies

{
  "messages": [
    {
      "type": "quickReplies",
      "quickReplies": [
        {
          "type": "quickReply",
          "label": "Quick reply chip 1",
          "action": {
            "type": "postback",
            "data": "chip1",
            "text": "Chip 1"
          }
        }, {
          "type": "quickReply",
          "label": "Quick reply chip 2",
          "action": {
            "type": "postback",
            "data": "chip2",
            "text": "Chip 2"
          }
        }, {
          "type": "quickReply",
          "label": "Quick reply chip 3",
          "action": {
            "type": "postback",
            "data": "chip3",
            "text": "Chip 3"
          }
        }
      ]
    }
  ]
}

Limits

Property Restriction
type required
quickReplies
  • required
  • minLength = 1 Quick Reply
  • maxLength = 13 Quick Replies, 24 characters each

Image

Used to show users image assets to communicate concepts or products visually.

Example square image
Example landscape image

Message body

{
  "type": "image",
  "url": string,
  "altText": string,
  "options": <IMAGE_OPTIONS>,
  "action": <ACTION>
}

NOTES:

  • <ACTION> refers to the Action primitive.
  • action supports both postback and openUrl type actions.
  • <IMAGE_OPTIONS> refers to the Image Options primitive. If you do not set the options, it defaults to the options default value {aspectRatio: landscape}.

Example of square image (found above)

{
  "messages": [
    {
      "type": "image",
      "url": "https://storage.googleapis.com/dapiodemos-static/docs/waffle.jpg",
      "altText": "Description of the image above",
      "options": {
        "type": "imageOptions",
        "options": {
          "aspectRatio": "square"
        }
      },
      "action": {
        "type": "postback",
        "text": "Show me more images",
        "data": "Show More"
      }
    }
  ]
}

Limits

Property Restriction
type required
url required
altText required

Button

Allows users to take action, such as sending a predefined sayable response or clicking out. Buttons can be used inside other message types.

Example postback button

Message body

{
  "type": "button",
  "label": string,
  "action": <ACTION>
}

NOTES:

  • <ACTION> refers to the Action primitive define below.
  • action supports both postback and openUrl type actions.

Example of postback button

{
  "messages": [
    {
      "type": "button",
      "label": "Postback action",
      "action": {
        "type": "postback",
        "text": "Learn more",
        "data": "learnmore"
      }
    }
  ]
}

Limits

Property Restriction
action required
label required
type
  • required
  • maxLength = 20 characters

Button List

Show list of options (eg. make a menu) .

Example button list with no title text
Example button list with title text

Message body

{
  "type": "buttonList",
  "title": string,
  "buttons": <BUTTON>[]
}

NOTES:

  • buttons are an array of <BUTTON> types as described above.

Example of button list with title text

{
  "messages": [
    {
      "type": "buttonList",
      "title": "What would you want to find out?",
      "buttons": [
        {
          "type": "button",
          "label": "Learn more about ABC",
          "action": {
            "type": "postback",
            "text": "Learn more",
            "data": "learnmore"
          }
        }, {
          "type": "button",
          "label": "Visit website 1",
          "action": {
            "type": "openUrl",
            "url": "https://adlingo.com"
          }
        }, {
          "type": "button",
          "label": "Call an agent now",
          "action": {
            "type": "call",
            "url": "tel:415-123-4567"
          }
        }, {
          "type": "button",
          "label": "Learn more about XYZ",
          "action": {
            "type": "postback",
            "text": "Learn more",
            "data": "learnmore"
          }
        }, {
          "type": "button",
          "label": "Visit website 2",
          "action": {
            "type": "openUrl",
            "url": "https://adlingo.com"
          }
        }
      ]
    }
  ]
}

Limits

Property Restriction
type required
buttons
  • required
  • minLength = 1 button
  • maxLength = 5 buttons
title maxLength = 80 characters

Card

  • Highlight an important concept in the conversation that needs visuals and/or descriptive information (eg. recommended product details).
  • Offer actions for the user to take, related to a specific concept (eg. buy a product, subscribe to deals, etc.).
  • Can include an image.
Example card with two buttons
Example card with one button
Example card with no text

Message body

{
  "type": "card",
  "title": string,
  "subtitle": string,
  "action": <ACTION>,
  "body": string,
  "image": <IMAGE>,
  "buttons": <BUTTON>[]
}

NOTES:

  • type is required, and at least one of the other properties are required.
  • The card, buttons, and image can have an action. It is not necessary or recommended to have an action on all elements.

Example of card with two buttons and image

{
  "messages": [
    {
      "type": "card",
      "title": "Title",
      "subtitle": "Subtitle",
      "body": "Body text should be inserted here text should be inserted here text should be inserted here ...",
      "action": {
        "type": "postback",
        "text": "Waffles",
        "data": "waffles"
      },
      "image": {
        "type": "image",
        "url": "https://storage.googleapis.com/dapiodemos-static/docs/waffle.jpg",
        "altText": "Picture of delicious waffles",
        "options": {
          "type": "imageOptions",
          "options": {
            "aspectRatio": "landscape"
          }
        }
      },
      "buttons": [
        {
          "type": "button",
          "label": "Learn more",
          "action": {
            "type": "postback",
            "text": "Learn more",
            "data": "learnmore"
          }
        }, {
          "type": "button",
          "label": "Visit website 1",
          "action": {
            "type": "openUrl",
            "url": "https://adlingo.com"
          }
        }
      ]
    }
  ]
}

Limits

Property Restriction
type required
title maxLength = 80 characters
subtitle maxLength = 80 characters
body maxLength = 240 characters
buttons maxLength = 3 buttons
  • Presents multiple cards to a user so they can choose.
  • It can be used to present predefined sayable options with visuals.
  • It can be used to offer multiple products with clickout (openUrl action) buttons in each.
Example card carousel with cards with two buttons
Example card carousel with cards with no image nor buttons

Message body

{
  "type": "cardCarousel",
  "cards": <CARD>[]
}

NOTES:

  • Behavior: Image options from the first card define the options for all cards in carousel.
  • <CARD> refers to the Card type.

Example of card carousel with cards with two buttons and image

{
  "messages": [
    {
      "type": "cardCarousel",
      "cards": [
        {
          "type": "card",
          "title": "Title",
          "subtitle": "Subtitle",
          "body": "Body text should be inserted here text should be inserted here text should be inserted here ...",
          "action": {
            "type": "postback",
            "text": "Waffles",
            "data": "waffles"
          },
          "image": {
            "type": "image",
            "url": "https://storage.googleapis.com/dapiodemos-static/docs/waffle.jpg",
            "altText": "Picture of delicious waffles",
            "options": {
              "type": "imageOptions",
              "options": {
                "aspectRatio": "landscape"
              }
            }
          },
          "buttons": [
            {
              "type": "button",
              "label": "Learn more",
              "action": {
                "type": "postback",
                "text": "Learn more",
                "data": "learnmore"
              }
            }, {
              "type": "button",
              "label": "Visit website",
              "action": {
                "type": "openUrl",
                "url": "https://adlingo.com"
              }
            }
          ]
        }, {
          "type": "card",
          "title": "Title",
          "subtitle": "Subtitle",
          "body": "Body text should be inserted here text should be inserted here text should be inserted here ...",
          "action": {
            "type": "postback",
            "text": "Waffles",
            "data": "waffles"
          },
          "image": {
            "type": "image",
            "url": "https://storage.googleapis.com/dapiodemos-static/docs/waffle.jpg",
            "altText": "Picture of delicious waffles",
            "options": {
              "type": "imageOptions",
              "options": {
                "aspectRatio": "landscape"
              }
            }
          },
          "buttons": [
            {
              "type": "button",
              "label": "Learn more",
              "action": {
                "type": "postback",
                "text": "Learn more",
                "data": "learnmore"
              }
            }, {
              "type": "button",
              "label": "Visit website",
              "action": {
                "type": "openUrl",
                "url": "https://adlingo.com"
              }
            }
          ]
        }, {
          "type": "card",
          "title": "Title",
          "subtitle": "Subtitle",
          "body": "Body text should be inserted here text should be inserted here text should be inserted here ...",
          "action": {
            "type": "postback",
            "text": "Waffles",
            "data": "waffles"
          },
          "image": {
            "type": "image",
            "url": "https://storage.googleapis.com/dapiodemos-static/docs/waffle.jpg",
            "altText": "Picture of delicious waffles",
            "options": {
              "type": "imageOptions",
              "options": {
                "aspectRatio": "landscape"
              }
            }
          },
          "buttons": [
            {
              "type": "button",
              "label": "Learn more",
              "action": {
                "type": "postback",
                "text": "Learn more",
                "data": "learnmore"
              }
            }, {
              "type": "button",
              "label": "Visit website",
              "action": {
                "type": "openUrl",
                "url": "https://adlingo.com"
              }
            }
          ]
        }
      ]
    }
  ]
}

Limits

Property Restriction
type required
cards
  • required
  • minLength = 1 card
  • maxLength = 16 cards

Typing Indicator / Delay

Delay elements can be used to add a "pause" to the conversation, and they can be inserted between other elements (eg: between two "text" responses). During delays, the UI will show a typing indicator if showTypingIndicator is set to true.

Example typing delay

Message body

{
  "type": "delay",
  "showTypingIndicator": boolean,
  "durationMS": integer
}

Example of typing delay

{
  "messages": [
    {
      "type": "delay",
      "showTypingIndicator": true,
      "durationMS": 400
    }
  ]
}

Limits

Property Restriction
type required
showTypingIndicator required
durationMS
  • required
  • maxLength = 30000ms

Primitive Message Types

These are building blocks of other message types. These should never be used alone, but should be treated as interfaces to be implemented.

Action

The purpose of the Action type (and primitives in general) is to associate or attach them to other message types to make them actionable. For example you can make an image clickable on a card by adding one of the following actions.

OpenUrl

Message body

{
  "type": "openUrl",
  "url": string
}

Example

{
  "type": "openUrl",
  "url": "https://google.com"
}

Postback

Message body

{
  "type": "postback",
  "data": string,
  "text": string
}

Caveats:

  1. If only text is set, it will render and postback the text value
  2. If data and text are set, text will render and data will postback

Example

{
  "type": "postback",
  "data": "Hello",
  "text": "Hi"
}

Call

Message body

{
  "type": "call",
  "url": string
}

Example

{
  "type": "call",
  "url": "tel:111-234-5678"
}

Image Options

Message body

{
  "type": "imageOptions",
  "options": {
    "aspectRatio": string
  }
}

NOTES:

  • aspectRatio can be one of 2 values
    • square (1:1)
    • landscape (1.91:1)
  • Default values: {aspectRatio: landscape}

Example

{
  "type": "imageOptions",
  "options": {
    "aspectRatio": "square"
  }
}

Quick Reply

Message body

{
  "type": "quickReply",
  "label": string,
  "action": <ACTION>,
}

NOTE: <ACTION> denotes the Action type as either a postback or an openUrl.

Example

{
  "type": "quickReply",
  "label": "Quick reply chip",
  "action": {
    "type": "postback",
    "data": "Hello",
    "text": "Hi"
  },
}

Limits

Property Restriction
action required
label
  • required
  • maxLength = 24 characters