diff --git a/docs/InterviewTemplates.md b/docs/InterviewTemplates.md index 86b78da..b223bda 100644 --- a/docs/InterviewTemplates.md +++ b/docs/InterviewTemplates.md @@ -1,37 +1,49 @@ -# Writing interview templates +# 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 + +## Interview Template Commands + Whether you already have a template or not the first step is always to use the `/interviewtemplate get ` 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 + +## Writing Your First Interview Template + Use the get command to get a default template for the ticket category you want to edit: ``` /interviewtemplate get ``` + 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 ``` + 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 + +## Automatic Template Validation and Suggestions in Text Editors + 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: + +### Guides for Different Editors: +
+ VS Code 1. Go to `File->Preferences->Settings`. - 2. Search for `json schema`. - 3. Click `Edit in settings.json` on the schema setting. - 4. Set the `json.schemas` property to the following to automatically validate template files: - ```json { "json.schemas": @@ -41,124 +53,239 @@ It is highly recommended to use the interview template JSON schema to get live v [ "interview-template*.json" ], - "url": "https://toastielab.dev/Emotions-stuff/SupportChild/raw/branch/main/Interviews/interview_template.schema.json" + "url": "https://raw.githubusercontent.com/KarlOfDuty/SupportBoi/refs/heads/main/Interviews/interview_template.schema.json" } ] } ``` - 5. 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 1. Go to `File->Settings->Languages & Frameworks->Schemas->JSON Schema Mapping`. - -2. Add a new schema with the following URL: `https://toastielab.dev/Emotions-stuff/SupportChild/raw/branch/main/Interviews/interview_template.schema.json`. - +2. Add a new schema with the following URL: `https://raw.githubusercontent.com/KarlOfDuty/SupportBoi/refs/heads/main/Interviews/interview_template.schema.json`. 3. 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 +## 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 ```json { - "category-id": "1005612326340272169", + "category-id": "1006863882301755503", "interview": { - "message": "Are you appealing your own ban or on behalf of another user?", + "message": "What is your favourite colour?", "message-type": "BUTTONS", - "color": "AQUAMARINE", + "color": "BLUE", + "summary-field": "Favourite colour", "paths": { - "My own ban": + "PRIMARY": { - "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": {} - } - } + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "BLUE", + "button-style": "PRIMARY", + "paths": {} }, - "Another user's ban": + "SECONDARY": { - "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": {} - } - } - } - } - } - } + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "GRAY", + "button-style": "SECONDARY", + "paths": {} + }, + "SUCCESS": + { + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "GREEN", + "button-style": "SUCCESS", + "paths": {} + }, + "DANGER": + { + "message": "Summary", + "message-type": "END_WITH_SUMMARY", + "color": "RED", + "button-style": "DANGER", + "paths": {} } } } } -``` \ No newline at end of file +``` + +### Template Root + +| 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 interview conversation tree, starting with one path which branches into many. | + +### Interview Paths + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property                             RequiredTypeDescription
+ + +`message` + YesString +The text in the embed message that will be sent to the user when they reach this step. +
+`message-type` + YesString +The type of message, decides what the bot will do when the user gets to this step. + + +
+ + +`color` + YesString + +Colour of the message embed. You can either enter a colour name or a hexadecimal RGB value. +
+`paths` + YesSteps +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` + YesString +The title of the embed message. +
+`summary-field` + YesString +When an interview ends all previous answers with this property will be put in a summary. +If this property is not specified the answer will not be shown in the summary. +The value of this property is the name which will be displayed next to the answer in the summary. +
+`button-style` + YesString +The style of this path's button. Requires that the parent path is a `BUTTONS` path. +Must be one of the following: +- `PRIMARY` +- `SECONDARY` +- `SUCCESS` +- `DANGER` + +Default style is `SECONDARY`. + +![Button Example](./img/buttonExample.png) +
+`selector-description` + YesString +Description for this option in the parent path's selection box. Requires that the parent path is a `TEXT_SELECTOR`. +
+`selector-placeholder` + YesString +The placeholder text shown before a value is selected in the selection box. Requires that this path is a `TEXT_SELECTOR`. +
+`max-length` + YesNumber +The maximum length of the user's response message. Requires that this path is a `TEXT_INPUT`. +
+`min-length` + YesNumber +The minimum length of the user's response message. Requires that this path is a `TEXT_INPUT`. +
+ +### Message Types + +| Message Type | Description | +|------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| `ERROR` | Sends an error message but does not stop the interview. The interview remains on the same step as before allowing the user to try again. | +| `END_WITH_SUMMARY` | End the interview and create a summary of the answers. | +| `END_WITHOUT_SUMMARY` | End the interview with a simple message without a summary. | +| `BUTTONS` | Creates a message with one button per child path where the button text is the name of the child path. | +| `TEXT_SELECTOR` | Creates a selection box with one option per child path where the option text is the name of the child path. | +| `USER_SELECTOR` | Creates a selection box where the user can select a user from the Discord server. The value used for the summary is the user's mention. | +| `ROLE_SELECTOR` | Same as above but for a role. | +| `MENTIONABLE_SELECTOR` | Same as above but works for both roles and users. | +| `CHANNEL_SELECTOR` | Same as above but for channels and categories. | +| `TEXT_INPUT` | Lets the user reply to the bot message with their own text. | \ No newline at end of file diff --git a/docs/img/buttonExample.png b/docs/img/buttonExample.png new file mode 100644 index 0000000..7c1d551 Binary files /dev/null and b/docs/img/buttonExample.png differ