Settings

Settings resource is used for setting up certain properties of a channel like get started button, menu, etc.

Note

Settings are available only on some channels:

• Amio Chat - Settings
• Facebook Messenger - Settings

Get Settings

GET https://api.amio.io/v1/channels/{channel_id}/settings

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}

Update Settings

PATCH https://api.amio.io/v1/channels/{channel_id}/settings

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}

Response 400

{}

Channel-specific settings

Select a channel to see its specifics.

Amio Chat

Amio Chat: Overview

Amio Chat allows you to restrict domains where the chat will be running, using a domain whitelist.

• Domains Whitelist

Amio Chat: Get Settings

Response Body Params

Parameter	Type	Description
domains_whitelist	array	List of domains allowed for cross origin requests (CORS) during connection to Amio Chat servers.

GET https://api.amio.io/v1/channels/{channel_id}/settings

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

{
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Amio Chat: Update Settings

Delete Settings

You can delete any settings with PATCH request setting the parameter to null, i.e. {"domains_whitelist": null}.

Response Body Params

Parameter	Type	Description
domains_whitelist	array	List of domains allowed for cross origin requests (CORS) during connection to Amio Chat servers. If this value is set to null or an empty list, then all connection attempts will be refused.

PATCH https://api.amio.io/v1/channels/{channel_id}/settings

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Example request (cUrl)

{
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Response 200

{
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Amio Chat: Domains Whitelist

Amio Chat allows to restrict domains where the web chat will be running. Only the whitelisted domains will be allowed for cross origin requests (CORS) during connection to Amio Chat servers.

When adding domains to the whitelist, please keep in mind that the whole fully qualified domain name, including protocol, is required. If your server uses non-standard port, then you have to include it, too (standard ports are 80 for HTTP, 443 for HTTPS). localhost is allowed and has to be whitelisted if you want to run your code locally.

If the domain whitelist is set to null or an empty list [ ], then no connection will be allowed.

Caution

Default domain whitelist value is null which means that no connection will be allowed.

Facebook Messenger

Facebook Messenger: Overview

Facebook Messenger allows you to set a variety of items which enhance the feel and look of your Messenger channel for your users:

• Get Started Button
• Menu
• User Inputs
• Domains Whitelist

Facebook API Rate Limits

All settings requests directly interact with Facebook API. Unlike other Facebook API endpoints, this endpoint has low rate limits. Amio API will inform you when Facebook API rate limits are reached. It usually takes several minutes until Facebook resets the rate limits.

Facebook Messenger: Get Settings

Response Body Params

Parameter	Type	Description
get_started_button	object	Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.
get_started_button.payload	string	Any arbitrary data you will receive in Postback Received webhook when a user clicks the button.
menu	array	List of the menu for different locales. Given the menu is displayed based on the user’s locale preference. If you want to set the menu, get started button is required as well. When setting a menu, at least one default locale menu is required. See Menu chapter for more details.
menu.[ ].locale	string	Specifies locale of given menu. Value has to be in form of locale or default.
menu.[ ].items	object	List of menu item objects. Maximum allowed size is 3.
user_inputs	array	List of settings for user inputs for different locales. If you want to disable user inputs then the menu is required to be set. When setting user input, at least one default locale user input is required. See User Inputs chapter for more details.
user_inputs.[ ].locale	string	Specifies locale of given user input. Value has to be in form of locale or default.
user_inputs.[ ].enabled	boolean	Set to false in order to disable users’ input, set to true otherwise.
domains_whitelist	array	Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.

GET https://api.amio.io/v1/channels/{channel_id}/settings

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  },
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        }
      ]
    }
  ],
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ],
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Facebook Messenger: Update Settings

Delete Settings

You can delete any settings with PATCH request setting the parameter to null, i.e. {"menu": null}.

Response Body Params

Parameter	Type	Description
get_started_button	object	Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.
get_started_button.payload	string	Any arbitrary data you will receive in Postback Received webhook when a user clicks the button.
menu	array	List of the menu for different locales. Given the menu is displayed based on the user’s locale preference. If you want to set the menu, get started button is required as well. When setting a menu, at least one default locale menu is required. See Menu chapter for more details.
menu[].locale	string	Specifies locale of given menu. Value has to be in form of locale or default.
menu[].items	array[object]	List of menu item objects. Maximum allowed size is 3.
user_inputs	array[object]	List of settings for user inputs for different locales. If you want to disable user inputs then the menu is required to be set. When setting user input, at least one default locale user input is required. See User Inputs chapter for more details.
user_inputs[].locale	string	Specifies locale of given user input. Value has to be in form of locale or default.
user_inputs[].enabled	boolean	Set to false in order to disable users’ input, set to true otherwise.
domains_whitelist	array[string]	Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.

PATCH https://api.amio.io/v1/channels/{channel_id}/settings

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Example request (cUrl)

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  },
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        }
      ]
    }
  ],
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ],
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Response 200

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  },
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        }
      ]
    }
  ],
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ],
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Facebook Messenger: Get Started Button

Get Started Button is visible on the welcome screen when the user comes for the first time. If the user tapes the button, it will trigger Postback Received webhook and deliver the user’s page-scoped id.

You can then present a personalised message to greet the user or provide a structured message with buttons to prompt him or her to take an action. The button is a good mean to increase conversions. Adding a “Get Started” button resolves the issue of users not knowing what to write to break the ice with your bot.

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  }
}

Parameter	Type	Description
get_started_button	object	Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.
get_started_button.payload	string	Any arbitrary data you will receive in Postback Received webhook when a user clicks the button.

Facebook Messenger: Menu

Creating a menu in Facebook Messenger, you can highlight important actions or provide a link to a webpage. Menu for Facebook Messenger is hierarchical and consists of different menu items:

• Url
• Postback
• Nested Menu

🚧 The Menu requires Get Started Button

You must set a Get Started Button if you want to use the menu in Facebook Messenger.

📘 Testing Tips

Facebook Messenger menu is cached by default. If you update the menu while testing just refresh the page. If it doesn’t help, try refreshing the web. If it doesn’t help, try deleting the messenger thread and then beginning the conversation once again.

The Menu is visible only if:

• Facebook Messenger has a version 106 and above.
• The attached Facebook page must be published.

{
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com/"
        },
        {
          "type": "postback",
          "title": "POSTBACK Item",
          "payload": "POSTBACK DATA"
        },
        {
          "type": "menu",
          "title": "NESTED Item",
          "payload": {
            "items": [
              {
                "type": "url",
                "title": "NESTED URL Item",
                "payload": "http://www.google.com/"
              }
            ]
          }
        }
      ]
    }
  ]
}

Parameter	Type	Description
menu[].locale	string	Specifies locale of given menu. Value has to be in form of locale or default.
menu[].items	array[object]	List of menu item objects. Maximum allowed size is 3.

Url Menu Item

Parameter	Type	Description
type	string	Must be set to url.
title	string	Title of the menu item. A maximum size of 30 characters.
payload	string	Must be a valid URL.

Postback Menu Item

Parameter	Type	Description
type	string	Must be set to postback.
title	string	Title of the menu item. A maximum size of 30 characters.
payload	string	This data will be sent back to Postback Received webhook. A maximum size of 1000 characters.

Nested Menu

Parameter	Type	Description
type	string	Must be set to menu. The maximal hierarchical depth is 3 levels.
title	string	Title of the menu item. A maximum size of 30 characters.
payload	object	Object with attribute items holding an array of nested menu items. The maximum number of items is 5 objects. Menu can have a deep nesting up to level of 3.

Facebook Messenger: User Inputs

You can disable the user from writing you a message back using user_inputs settings. This forces the user to use only buttons provided in structured messages or in the menu.

{
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ]
}

Parameter	Type	Description
user_inputs[].locale	string	Specifies locale of given menu. Value has to be in form of locale or default.
user_inputs[].enabled	boolean	Set to false in order to disable users’ input, set to true otherwise.

User Inputs requires Menu

You must set a Menu if you want to disable user input.

Facebook Messenger: Domains Whitelist

Some features like Checkbox Plugin require domains to be whitelisted.

{
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Parameter	Type	Description
domains_whitelist	array[string]	Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.

Whitelisting in Facebook Page Settings

In addition to domains whitelist API, you can whitelist domains in Facebook Page administration:

1. Click Settings in your Facebook Page.
2. Click Messenger Platform on the left menu.
3. Edit domains in Whitelisted Domains sectionn.