Forms Builder
These endpoints create, read, update, and delete a server's forms, and list the Trello boards and options a form question can map to.
Note
For the Forms Builder module, the base URL for the API gateway endpoints is https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms.
Note
The formId in a path is the value that form objects carry as workflow_id.
Get Trello Options
HTTP Request Example
GET /trelloOptions HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN> HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"options": [
"Description",
"Title",
"List",
"Label",
"Attachment",
"Private"
]
} Returns the options available when a form question maps its fields to Trello board or card options.
Get Form returns the same information.
HTTP Request
GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms/trelloOptions
HTTP Response
The response contains the options array of strings, with the following values:
| Value | Description |
|---|---|
| Description | The description (content) of a Trello card. |
| Title | The title of a Trello card. |
| List | The name of a list on the Trello board. |
| Label | A label on a Trello board, assigned to the card. |
| Attachment | The attachment of a Trello card. |
| Private | Any field marked with "Private" will not be sent to Trello. |
Get Trello Boards
HTTP Request Example
GET /trelloBoards HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN> HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"trello_boards": [
{
"id": "0",
"name": "Disable Trello integration"
},
{
"id": "5c4e576b0386d8313e9e3722",
"name": "GiselleBot Support Center :: Bug Reports & Future Development"
}
]
} HTTP/1.1 200 OK
Content-Type: application/json
{
"trello_boards": [
{
"id": "-1",
"name": "Trello team not paired"
}
]
} Returns the Trello boards that a form question can publish approved submissions to, when the server has a paired Trello team.
Get Form returns the same information.
HTTP Request
GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms/trelloBoards
HTTP Response
The response contains the trello_boards array. Each element of the array has the following parameters:
| Parameter | Type | Description |
|---|---|---|
| id | String | The ID of the Trello board. |
| name | String | The name of the Trello board. |
The list can also contain two special boards:
{ "id": "0", "name": "Disable Trello integration" }-> This board ID disables the Trello integration when you pass it in certain options.{ "id": "-1", "name": "Trello team not paired" }-> This board appears when the server is not paired to any Trello team.
Get Forms
HTTP Request Example
GET / HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN> HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"forms": [
{
"workflow_id": 1,
"trello_integration": true,
"workflow_live": true,
"title": "Bug Reports",
"color_hex": "#3a7fdb"
},
...
]
} Returns every form in a server.
HTTP Request
GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms
HTTP Response
The response contains the forms array. Each element of the array has the following parameters:
| Parameter | Type | Description |
|---|---|---|
| workflow_id | Integer | The ID of the form. |
| trello_integration | Boolean | Whether the Trello integration is enabled for the form (a.k.a. "Trello Mode"). |
| workflow_live | Boolean | Whether the form is currently enabled. |
| title | String | The title of the form. |
| color_hex | String | The form color, as a hexadecimal string. |
Get Form
HTTP Request Example
GET /1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN> HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"workflow_id": 1,
"channel_id": "534754593490337802",
"fwd_channel_ids": [
"539252303400796211"
],
"role_mentions": [
"539276949307260928"
],
"timestamp_created": "2019-01-28T01:07:25.274Z",
"workflow_live": true,
"trello_integration": true,
"anonymize": true,
"disable_downvote": false,
"disable_upvote": false,
"extended_embed": true,
"trello_board": "5c4e576b0386d8313e9e3722",
"title": "Bug Reports",
"color_hex": "#3a7fdb",
"highlight_attachments": false,
"anonymize_rejection": false,
"disable_mentions": false,
"disable_priorities": false,
"steps": [
{
"step_id": 1,
"type": "reaction",
"string": "What bot are you leaving a bug report for?",
"answers_validation": [
"GiselleBot",
"Belfast-chan",
"Other"
],
"char_limit": [
1,
2000
],
"alias": "Bot Name",
"trello_mapping": "Label"
},
...
],
"trello_options": [...],
"trello_boards": [...]
} Returns one form for a server.
HTTP Request
GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms/:formId
HTTP Response
The response is a form object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
| workflow_id | Integer | The ID of the form. |
| channel_id | String | The channel ID of the authorization channel. |
| fwd_channel_ids | Array<String> | The channel IDs of the forwarding channels. |
| role_mentions | Array<String> | The role IDs of the authorized role(s). |
| public_mentions | Array<String> | The role IDs of the public role mentions. |
| timestamp_created | String | The timestamp of the form creation. |
| workflow_live | Boolean | Whether the form is currently enabled. |
| trello_integration | Boolean | Whether the Trello integration is enabled for the form (a.k.a. "Trello Mode"). |
| anonymize | Boolean | Whether the public submissions are anonymized in Discord Mode (hidden submitter info). |
| disable_downvote | Boolean | Whether the downvote tracking feature (and downvote arrow application for new submissions) is disabled. |
| disable_upvote | Boolean | Whether the upvote tracking feature (and upvote arrow application for new submissions) is disabled. |
| extended_embed | Boolean | Whether the extended embed mode is enabled in "Trello Mode" for public in-Discord summary messages. |
| trello_board | String | The ID of the Trello board linked to the form. |
| title | String | The title of the form. |
| color_hex | String | The form color, as a hexadecimal string. |
| highlight_attachments | Boolean | Whether the attachment highlighting feature is enabled. |
| anonymize_rejection | Boolean | Whether the name of the user that rejected a submission will appear in the rejection message. |
| disable_mentions | Boolean | Whether the authorized role(s) will not be mentioned when a new submission is received. |
| disable_priorities | Boolean | Whether the priority buttons are not applied to the validation message. |
| steps | Array<Object> | An array of steps (questions) for the form (see below for more info). |
| trello_options | Array<String> | Equivalent to the options array from Get Trello Options. |
| trello_boards | Array<Object> | Equivalent to the trello_boards array from Get Trello Boards. |
Each step (question) has the following parameters:
| Parameter | Type | Description |
|---|---|---|
| step_id | Integer | The ID of the step. This will be recalculated based on the order of the steps when editing the form. |
| type | String | The type of question. Accepted values are message or reaction. |
| string | String | The content of the question. |
| answers_validation | Array<String> | If type is set to reaction, the list of possible answers. If type is set to message, the list of validation words/sentences (answers will be ignored unless the message contains at least one of the chosen words/sentences). |
| char_limit | Array<Integer> | An array of two elements, specifying the minimum and maximum number of characters an answer can have. The first element must be higher than 0. The second element must be lower than, or equal to, 2000. The second integer must be higher than, or equal to, the first. |
| alias | String | A short alias/title that will replace the full question when the submission is sent. |
| trello_mapping | String | The mapping of the question into one of the entities of the Trello board, if "Trello Mode" is enabled. Refer to Get Trello Options. |
Create Form
HTTP Request Example
POST / HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>
{
"channel_id": "534754593490337802",
"fwd_channel_ids": [
"895420834318020628"
],
"role_mentions": [
"530800536627314698"
],
"public_mentions": [],
"trello_integration": false,
...
"steps": [...]
} HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"workflow_id": 4,
"channel_id": "534754593490337802",
"fwd_channel_ids": [
"895420834318020628"
],
"role_mentions": [
"530800536627314698"
],
"public_mentions": [],
"trello_integration": false,
...
"steps": [...],
"trello_options": [...],
"trello_boards": [...]
} Creates a new form for a server.
HTTP Request
POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms
The request body must include the full form. The server validates individual fields. Refer to Get Form for the full list of parameters.
HTTP Response
The response is a form object. Use its workflow_id as formId in later calls.
Refer to Get Form for the full list of parameters.
Update Form
HTTP Request Example
PATCH /1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>
{
"workflow_id": 1,
"channel_id": "534754593490337802",
...
"workflow_live": false,
...
"disable_downvote": true,
"disable_upvote": true,
...
"steps": [...]
} HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"workflow_id": 1,
"channel_id": "534754593490337802",
...
"workflow_live": false,
...
"disable_downvote": true,
"disable_upvote": true,
...
"steps": [...],
"trello_options": [...],
"trello_boards": [...]
} Updates one form for a server.
HTTP Request
PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms/:formId
The request body must include the full updated form. The server validates individual fields. Refer to Get Form for the full list of parameters.
HTTP Response
The response is a form object.
Refer to Get Form for the full list of parameters.
Delete Form
HTTP Request Example
DELETE /1 HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN> HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true
} Deletes one form for a server.
HTTP Request
DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms/:formId
HTTP Response
The response contains a single success parameter (Boolean) that reports whether the form was deleted.
Get New Form Template
HTTP Request Example
GET /new HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN> HTTP Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"workflow_id": null,
"channel_id": null,
"fwd_channel_ids": [],
"role_mentions": [],
"public_mentions": [],
"timestamp_created": null,
"trello_integration": false,
"trello_board": "-1",
"workflow_live": false,
"title": "TITLE_NOT_FOUND",
"color_hex": "#00d084",
...
"steps": [],
"trello_options": [...],
"trello_boards": [...]
} Returns a new form template to use as the base for Create Form.
HTTP Request
GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/:serverId/modules/forms/new
HTTP Response
The response is a template form object. The server assigns workflow_id when the template is sent through Create Form.
Refer to Get Form for the full list of parameters.