Writing interview templates

The bot can automatically interview users when they open a ticket. These interviews are defined in interview templates. The templates each apply to a single ticket category so you can have different interviews depending on the type of ticket.

Interview template commands

Whether you already have a template or not the first step is always to use the /interviewtemplate get <category> command on the ticket category you want to edit. If you haven't yet, use the /addcategory command on the category to register it with the bot. The bot will reply with a JSON template file which you can edit and upload using the /interviewtemplate set command. You can also delete an interview template using the /interviewtemplate delete command.

Writing your first interview template

Use the get command to get a default template for the ticket category you want to edit:

/interviewtemplate get <category>

The bot will reply with a JSON template file for you to edit using your preferred text editor. Note: It is highly recommended to use integrated template validation in your text editor, see below. When you are done editing it you can upload it to the bot using the set command:

/interviewtemplate set <category>

The bot will check that your template is correctly formatted and provide feedback if it is not.

Automatic validation and suggestions in your text editor

It is highly recommended to use the interview template JSON schema to get live validation of your template while you write it:

Guides for different editors:

VS Code

Go to File->Preferences->Settings.
Search for json schema.
Click Edit in settings.json on the schema setting.
Set the json.schemas property to the following to automatically validate template files:

{
    "json.schemas":
    [
        {
            "fileMatch":
            [
                "interview-template*.json"
            ],
            "url": "https://toastielab.dev/Emotions-stuff/SupportChild/raw/branch/main/Interviews/interview_template.schema.json"
        }
    ]
}

Open an interview template, you should now get suggestions for things like message types and color names, and error highlighting for any invalid sections.

Jetbrains Editors

Go to File->Settings->Languages & Frameworks->Schemas->JSON Schema Mapping.
Add a new schema with the following URL: https://toastielab.dev/Emotions-stuff/SupportChild/raw/branch/main/Interviews/interview_template.schema.json.
Restart your editor and all interview templates should now automatically be set to the correct schema in the bottom right of the window.

Interview template format

This section lists all the properties that can be used in an interview template. If you have set up your editor as suggested above it will handle a lot of this for you automatically. All templates start with the following properties at the top level:

Property	Required	Description
`category-id`	Yes	The id of the category this template applies to. You can change this and re-upload the template to apply it to a different category.
`interview`	Yes	Contains the first step of the interview, see below.
The rest of the template is a series of interview steps, with the following parameters:

Property	Required	Description
`message`	Yes	The text in the embed message that will be sent to the user when they reach this step.
`message-type`	Yes	The type of message, decides what the bot will do when the user gets to this step. Must be one of: ERROR, END_WITH_SUMMARY, END_WITHOUT_SUMMARY, BUTTONS, TEXT_SELECTOR, USER_SELECTOR, ROLE_SELECTOR,MENTIONABLE_SELECTOR, CHANNEL_SELECTOR, TEXT_INPUT
`color`	Yes	Colour of the message embed.
`paths`	Yes	One or more interview steps. The name of the step is used as a regex match against the user's answer, except for selection boxes and buttons where each step becomes a button or selection option.
`heading`	No	The title of the embed message.
`summary-field`	No
`button-style`	No
`selector-description`	No
`selector-placeholder`	No
`max-length`	No
`min-length`	No

Example template

{
  "category-id": "1005612326340272169",
  "interview":
  {
    "message": "Are you appealing your own ban or on behalf of another user?",
    "message-type": "BUTTONS",
    "color": "AQUAMARINE",
    "paths":
    {
      "My own ban":
      {
        "message": "Please write your appeal below, motivate why you think you should be unbanned.",
        "message-type": "TEXT_INPUT",
        "color": "CYAN",
        "summary-field": "Ban appeal",
        "paths":
        {
          ".*":
          {
            "heading": "Appeal Summary",
            "message": "Thank you, a staff member will review your appeal.",
            "message-type": "END_WITH_SUMMARY",
            "color": "GREEN",
            "paths": {}
          }
        }
      },
      "Another user's ban":
      {
        "message": "Whose ban are you appealing?",
        "message-type": "USER_SELECTOR",
        "color": "CYAN",
        "summary-field": "User",
        "paths":
        {
          "<@170904988724232192>":
          {
            "message": "Not allowed",
            "message-type": "ERROR",
            "color": "RED",
            "paths": {}
          },
          ".*":
          {
            "message": "What is their role?",
            "message-type": "ROLE_SELECTOR",
            "color": "CYAN",
            "summary-field": "Their Role",
            "paths":
            {
              ".*":
              {
                "message": "Please write the appeal below.",
                "message-type": "TEXT_INPUT",
                "color": "CYAN",
                "summary-field": "Ban appeal",
                "paths":
                {
                  ".*":
                  {
                    "heading": "Appeal Summary",
                    "message": "Thank you, a staff member will review the appeal.",
                    "message-type": "END_WITH_SUMMARY",
                    "color": "GREEN",
                    "paths": {}
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

12 KiB Raw Blame History