Update Bot Manifest

Released in 24.1. Updates the manifest of the calling service user. The manifest contains the list of supported commands.

Update own service account manifest

POSTyourpodURL.symphony.com/pod/v1/user/manifest/own

Header parameters

Body

Service Account Manifest to put in user account

manifest*string

Manifest containing commands supported by the service account. Must be valid JSON.

Response

Success

Body

formatenum

TEXTXML

messagestring

Request

const response = await fetch('yourpodURL.symphony.com/pod/v1/user/manifest/own', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "manifest": "text"
    }),
});
const data = await response.json();

Response

{
  "format": "TEXT",
  "message": "Success"
}

This feature requires Client2 v24.5 (release date: May 2024) as well as SBE v24.1 (check availability with your Technical Account Manager or Symphony representative).

The manifest describes the list of Slash commands that your bot supports, and is persisted on the Symphony backend.

Every time a user is in a room with your bot, he can display all supported commands by typing "/" in the chat text editor.

With this new auto complete menu, users can easily discover all the features available through your Bot. The menu also makes it much easier and faster to type properly formatted commands.

The list of commands is supposed to stay relatively static and should be updated only if the list of supported commands evolves (e.g. a new command is supported or an existing command changes).

You can create the manifest manually and upload it by following the steps below.

Manifest guide

Structure

A manifest is a JSON document that defines a list of commands. Each command must have a name and a description (desc), and can optionally have an example and a list of arguments (args).

Sample manifest:

{
    "commands": [
        {
            "args": [
                {
                    "name": "[query1]"
                },
                {
                    "name": "[query2]"
                }
            ],
            "desc": "Search users based on name, company or job title",
            "example": "/search John Smith",
            "name": "search"
        },
        {
            "args": [
                {
                    "name": "[product_name]"
                }
            ],
            "desc": "Onboard a new user on a product.",
            "example": "/onboard Mtx102",
            "name": "onboard"
        },
        {
            "args": [
                {
                    "name": "[cmdname]"
                }
            ],
            "desc": "Get more information on how to use a command.",
            "example": "/help onboard",
            "name": "help"
        },
        {
            "args": [
                {
                    "name": "[nbusers]"
                },
                {
                    "name": "[product]"
                }
            ],
            "desc": "List top users of a product.",
            "example": "/topperf 10 Mtx503",
            "name": "topperf"
        }
    ]
}

Notes on manifest format

Commands are single words: The name of a command can't contain any spaces. If you want to have sub commands (e.g. /create ticket and /create profile ) then you can use arguments for that. You can have several commands with the same name.

Limitations

Long display names: Bots with a very long display name (more than 5 separate words) are not well supported: The list of commands will not display if a user types "/" after a mention to your Bot. Users will still be able to see the commands if they type "/" without a mention to your Bot.

Manifest size: The maximum length of the manifest is 6000 characters. Remove unnecessary spaces (compress) to keep the character count low.

Steps

Once you have completed your manifest, it needs to be 1. Compressed then 2. JSON-escaped, and finally 3. Uploaded to Symphony, using the Upload Bot Manifest endpoint.

1. Compress the manifest

The maximum length of the manifest is 6000 characters, hence the benefit of removing all unnecessary characters such as spaces, tabs or new lines.

Compressed manifest

{"commands": [{"args": [{"name": "[query1]"}, {"name": "[query2]"}], "desc": "Search users based on name, company or job title", "example": "/search John Smith", "name": "search"}, {"args": [{"name": "[product_name]"}], "desc": "Onboard a new user on a product.", "example": "/onboard Mtx102", "name": "onboard"}, {"args": [{"name": "[cmdname]"}], "desc": "Get more information on how to use a command.", "example": "/help onboard", "name": "help"}, {"args": [{"name": "[nbusers]"}, {"name": "[product]"}], "desc": "List top users of a product.", "example": "/topperf 10 Mtx503", "name": "topperf"}]}

2. JSON-escape

Then you need to JSON-escape the manifest. Free tools are available online to perform this operation.

JSON-escaped manifest

{\"commands\": [{\"args\": [{\"name\": \"[query1]\"}, {\"name\": \"[query2]\"}], \"desc\": \"Search users based on name, company or job title\", \"example\": \"\/search John Smith\", \"name\": \"search\"}, {\"args\": [{\"name\": \"[product_name]\"}], \"desc\": \"Onboard a new user on a product.\", \"example\": \"\/onboard Mtx102\", \"name\": \"onboard\"}, {\"args\": [{\"name\": \"[cmdname]\"}], \"desc\": \"Get more information on how to use a command.\", \"example\": \"\/help onboard\", \"name\": \"help\"}, {\"args\": [{\"name\": \"[nbusers]\"}, {\"name\": \"[product]\"}], \"desc\": \"List top users of a product.\", \"example\": \"\/topperf 10 Mtx503\", \"name\": \"topperf\"}]}

3. Upload to Symphony

Upload the JSON-escaped manifest as a body parameter of the Update Bot Manifest endpoint as shown in the example below:

curl --location 'https://mypodurl.symphony.com/pod/v1/user/manifest/own' \
--header 'sessionToken: thisisthesessiontoken' \
--header 'Content-Type: application/json' \
--data '{
  "manifest": "{\"commands\": [{\"args\": [{\"name\": \"[query1]\"}, {\"name\": \"[query2]\"}], \"desc\": \"Search users based on name, company or job title\", \"example\": \"\/search John Smith\", \"name\": \"search\"}, {\"args\": [{\"name\": \"[product_name]\"}], \"desc\": \"Onboard a new user on a product.\", \"example\": \"\/onboard Mtx102\", \"name\": \"onboard\"}, {\"args\": [{\"name\": \"[cmdname]\"}], \"desc\": \"Get more information on how to use a command.\", \"example\": \"\/help onboard\", \"name\": \"help\"}, {\"args\": [{\"name\": \"[nbusers]\"}, {\"name\": \"[product]\"}], \"desc\": \"List top users of a product.\", \"example\": \"\/topperf 10 Mtx503\", \"name\": \"topperf\"}]}"
}'

The endpoint above needs to be called with the identity of the Bot for which the manifest is uploaded. There is currently no endpoint to update the manifest of another service user.

Validation

Once the manifest is uploaded, you can test that the commands auto complete menu displays correctly by opening a chat with your bot and typing the "/" character.

If the auto complete menu does not display, please open the developer tools' console and look for an error log related to the format of the manifest. This log could start with 'Error while parsing the manifest from the bot'.

Please note that the manifest is cached on the Client: Reload your Client to refresh the cache after you have uploaded a new version of your manifest.

Last updated 7 days ago