Forms Builder

These endpoints control the Forms Builder module.

Note

For the Forms Builder module, the base URL for the API gateway endpoints is https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms.

Note

The documentation often refers to the formId parameter. In interacting with the API, this is what you'll find in form objects 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"
    ]
}

This endpoint retrieves the list of available options that can be used, when generating a form question, to map the question fields to Trello board/card options.

The same information is provided through the Get Form endpoint.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/: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"
        }
    ]
}

This endpoint retrieves the list of available Trello boards that can be used, when creating a form question, to publish approved submissions (provided the server has a paired Trello team).

The same information is provided through the Get Form endpoint.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/: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.

When fetching boards, two "special" boards can be found:

{ "id": "0", "name": "Disable Trello integration" } -> This board ID can be passed in certain options in order to disable the Trello integration.
{ "id": "-1", "name": "Trello team not paired" } -> This board is shown 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"
        },
        ...
    ]
}

This endpoint retrieves the list of all forms in a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/: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": [...]
}

This endpoint retrieves one form for a server.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/:formId

HTTP Response

The response consists of a form object, with 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 submissionms 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": [...]
}

This endpoint creates a new form for a server.

HTTP Request

POST https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms

The request body must include the full form. Validation checks on individual fields are run server-side. Refer to Get Form for the full list of parameters.

HTTP Response

The response consists of a form object. The workflow_id found in the object must be used as formId in subsequent 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": [...]
}

This endpoint updates one form for a server.

HTTP Request

PATCH https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/:formId

The request body must include the full updated form. Validation checks on individual fields are run server-side. Refer to Get Form for the full list of parameters.

HTTP Response

The response consists of 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
}

This endpoint deletes one form for a server.

HTTP Request

DELETE https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/:formId

HTTP Response

The response consists of an atomic object, containing a success parameter (Boolean) indicating whether the form was successfully 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": [...]
}

This endpoint generates a new form template that can be used as a base to create a new form through Create Form.

HTTP Request

GET https://gateway.cycloptux.com/api/v1/bots/:appClientId/servers/:serverId/modules/forms/new

HTTP Response

The response consists of a "template" form object. The workflow_id is assigned by the server when the template is sent through Create Form.

Refer to Get Form for the full list of parameters.