Forms configuration

Form model
Form DTO fields:
id - [string] uuid of form
orgId - [string] uuid of organization
locale - [string] locale which the form was created for
availableForAgents - [boolean] determines whether agents can access and send the form
name - [string] name of the form
config - [object] configuration of the form's inputs (see input types below)
expireInterval - (optional)[number] - milliseconds after which the form can no longer be submitted
sendInterval - (optional)[number] - milliseconds after which the form can be sent again
blockIfPreviousUnsubmitted - (optional)[boolean] - determines whether the form can be sent if previous has not been submitted yet
routeOnSubmit - (optional)[boolean] - determines whether submitting the form should result in opening and assignment of the conversation
tagGroupId - (optional)[string] uuid of tag group. Form will be available only in rooms with given tagGroupId. Form with empty tagGroupId available in any room
Inputs form
Use this form to collect information
Config (inputs) fields:
radioButtonsInputs - array of objects representing radio buttons input
multipleButtonsInputs - array of objects representing multiple buttons input
radioListInputs - array of objects representing radio list input
checkboxListInputs - array of objects representing checkbox list input
textInputs - array of objects representing text input
Buttons (multiple choice)
multipleButtonsInputs
Mulitple buttons input
Click here to see the code
The input above is represented by the following object:
{
    "index": 0,
    "name": "conversation_expectation",
    "displayName": "I expect the conversation to be:",
    "buttons": [
        {
            "value": "quick",
            "displayName": "Quick"
        },
        {
            "value": "nice",
            "displayName": "Nice & kind"
        },
        {
            "value": "helpful",
            "displayName": "Helpful"
        }
    ]
}
Buttons (single choice)
radioButtonsInputs
Radio buttons input
Click here to see the code
The input above is represented by the following object:
{
    "index": 1,
    "name": "device_type",
    "displayName": "I have a problem with my:",
    "buttons": [
        {
            "value": "phone",
            "displayName": "Phone"
        },
        {
            "value": "laptop",
            "displayName": "Laptop"
        },
        {
            "value": "elbow",
            "displayName": "Elbow"
        }
    ]
}
Radio input with list of options (single choice)
radioListInputs
Radio list input
Click here to see the code
The input above is represented by the following object:
{
    "index": 2,
    "name": "timeline",
    "displayName": "I have been a customer for:",
    "options": [
        {
            "value": "under_six_months",
            "displayName": "<= 6 months"
        },
        {
            "value": "six_months_to_two_years",
            "displayName": "<= 2 years"
        },
        {
            "value": "longer",
            "displayName": "> 2 years"
        }
    ]
}
Input with list of options (multiple choice)
checkboxListInputs
Checkbox list input
Click here to see the code
The input above is represented by the following object:
{
    "index": 3,
    "name": "favorite_colors",
    "displayName": "Colors I like:",
    "options": [
        {
            "value": "white",
            "displayName": "White"
        },
        {
            "value": "black",
            "displayName": "Black"
        },
        {
            "value": "yellow",
            "displayName": "Yellow"
        }
    ]
}
Text input
textInputs
Text input
Click here to see the code
The input above is represented by the following object:
{
    "index": 4,
    "name": "language_name",
    "displayName": "The best programming language is:",
    "placeholder": "Type language name here..."
}
Full example
Inputs order in the form is determined by `index` property of representing object
Click here to see form with inputs represented above
{
    "id": "0b05797b-a15b-42a5-96ec-XXXXXXXXXXXX",
    "orgId": "95a25389-5b2f-4b43-a311-XXXXXXXXXXXX",
    "locale": "en",
    "config": {
        "radioButtonsInputs": [
            {
                "index": 1,
                "name": "device_type",
                "displayName": "I have a problem with my:",
                "buttons": [
                    {
                        "value": "phone",
                        "displayName": "Phone"
                    },
                    {
                        "value": "laptop",
                        "displayName": "Laptop"
                    },
                    {
                        "value": "elbow",
                        "displayName": "Elbow"
                    }
                ]
            }
        ],
        "multipleButtonsInputs": [
            {
                "index": 0,
                "name": "conversation_expectation",
                "displayName": "I expect the conversation to be:",
                "buttons": [
                    {
                        "value": "quick",
                        "displayName": "Quick"
                    },
                    {
                        "value": "nice",
                        "displayName": "Nice & kind"
                    },
                    {
                        "value": "helpful",
                        "displayName": "Helpful"
                    }
                ]
            }
        ],
        "radioListInputs": [
            {
                "index": 2,
                "name": "timeline",
                "displayName": "I have been a customer for:",
                "options": [
                    {
                        "value": "under_six_months",
                        "displayName": "<= 6 months"
                    },
                    {
                        "value": "six_months_to_two_years",
                        "displayName": "<= 2 years"
                    },
                    {
                        "value": "longer",
                        "displayName": "> 2 years"
                    }
                ]
            }
        ],
        "checkboxListInputs": [
            {
                "index": 3,
                "name": "favorite_colors",
                "displayName": "Colors I like:",
                "options": [
                    {
                        "value": "white",
                        "displayName": "White"
                    },
                    {
                        "value": "black",
                        "displayName": "Black"
                    },
                    {
                        "value": "yellow",
                        "displayName": "Yellow"
                    }
                ]
            }
        ],
        "textInputs": [
            {
                "index": 4,
                "name": "name",
                "displayName": "The best programming language is:",
                "placeholder": "Type language name here..."
            }
        ]
    },
    "availableForAgents": true,
    "name": "Problem questionaire",
    "expireInterval": 60000,
    "sendInterval": 10000,
    "blockIfPreviousUnsubmitted": true,
    "routeOnSubmit": false
}
Auto assign form
Use this form to route clients' conversations based on their choice
Auto assign form
Click here to see form configuration
The form above is represented by the following object:
{
    "id": "2909d885-d34c-49b9-8e8e-XXXXXXXXXXXX",
    "orgId": "d90482fe-17bf-48d5-aa75-XXXXXXXXXXXX",
    "locale": "en",
    "config": {
        "type": "auto_assign_form",
        "tagGroups": [
            {
                "tagGroupId": "23b133fa-f2d1-4140-bddc-XXXXXXXXXXXX",
                "displayName": "First tag group"
            },
            {
                "tagGroupId": "c0f47b47-8269-4002-9734-XXXXXXXXXXXX",
                "displayName": "Second tag group"
            },
            {
                "tagGroupId": "c972191f-ddea-40df-bbbe-XXXXXXXXXXXX",
                "displayName": "Third tag group"
            }
        ]
    },
    "availableForAgents": true,
    "name": "assignment_form",
}
 Predefined message form
Predefined message is a  form to send simple text without any inputs as a adviser message. Form configuration accepts the only property message`. Such form could be used to send links and messages with additional conversation data:
{{roomId}} - conversation room id
Predefined meesage
Click here to see form configuration
​
The form above is represented by the following object:
{
    "id": "b5cb64ec-9d85-4fe1-8df7-c8a4b8131b2d",
    "orgId": "95a25389-5b2f-4b43-a311-7625f73da813",
    "locale": "pl",
    "config": {
        "type": "predefined_message_form",
        "message": "Simple predefined message with in room id = {{roomId}}"
    },
    "availableForAgents": true,
    "name": "Simple message",
    "routeOnSubmit": false
}
API
Create
POST - /api/message-widgets/{locale}
Creates new form
Requires apiKey header of an adviser with settings_action_forms permission
Requires body with following fields:
required: name, availableForAgents, config (described above)
optional: expireInterval, sendInterval, blockIfPreviousUnsubmitted
Click here to see an example
Example
curl --location --request POST 'https://spinner.closer.app/api/message-widgets/en' \
--header 'x-api-key: your-api-key-here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "a_problem_questionaire",
    "availableForAgents": true,
    "tagGroupId": "0000-0000-0000-000000000000",
    "config": {
        "textInputs": [
            {
                "index": 0,
                "name": "best_language",
                "displayName": "The best programming language is:",
                "placeholder": "Type language name here..."
            }
        ]
    }
}'
Update
PUT - /api/message-widgets/{uuid}
Updates existing form
Requires apiKey header of an adviser with settings_action_forms permission
Requires body with same schema as POST request
Click here to see an example
Example
curl --location --request PUT 'https://spinner.closer.app/api/message-widgets/d7f68940-e47f-4cd3-bc99-79e112749559' \
--header 'x-api-key: your-api-key-here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "a_problem_questionaire",
    "availableForAgents": false,
    "config": {
        "textInputs": [
            {
                "index": 0,
                "name": "best_language",
                "displayName": "The best programming language is:",
                "placeholder": "Type language name here..."
            }
        ]
    }
}'
Read
GET - /api/message-widgets/{locale}
Gets all created forms' DTOs
Requires apiKey of organization's adviser
Click here to see an example
Example
curl --location --request GET 'https://spinner.stage.closer.app/api/message-widgets/en' \
--header 'x-api-key: your-api-key-here'
GET - /api/message-widgets/{orgId}/{messageWidgetId}
Gets single form DTO
Does not require authentication
Click here to see an example
Example
curl --location --request GET 'https://spinner.closer.app/api/message-widgets/95a25389-5b2f-4b43-a311-7625f73da813/0b05797b-a15b-42a5-96ec-fd821456c69e
Widget OAuth configuration
Org configuration API
Last modified 4mo ago