--- updatedAt: 2026-08-06T09:23:57.000Z agentTools: projectIndex: https://developers.alcmeon.com/llms.txt --- # Describe configuration Whenever a new bot box is added to a scenario, we `GET /description` to obtain a description of the bot output connectors, parameters, etc. This endpoint can also be invoked at other times during the bot lifecycle. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Subbot Webhooks", "version": "1.0" }, "x-readme": { "explorer-enabled": false }, "components": { "securitySchemes": { "basic_auth": { "description": "Basic authentication using your environment Instance ID as username and Application Secret as password.\n", "type": "http", "scheme": "basic" } }, "schemas": { "AlcmeonWebhookSignatureHeader": { "type": "string", "description": "Optional header for [signature verification](https://developers.alcmeon.com/docs/api-core-concepts#signature-verification) present if an Alcmeon application has been defined for the sub-bot." }, "Exit": { "type": "object", "properties": { "name": { "type": "string", "description": "The unique name of the output connector." }, "description": { "type": "string", "description": "A human-readable description of what it means to exit the bot box via this output connector. Displayed in the Alcméon editor GUI.\n" } } }, "Variable": { "type": "object", "properties": { "name": { "type": "string", "description": "The unique name of the user conversation variable" }, "description": { "type": "string", "description": "A human-readable description of the meaning of the content of this variable. Displayed in the Alcméon editor GUI.\n" } } }, "IntegerParameterSpecification": { "type": "object", "properties": { "min": { "description": "All parameter values should be such that value >= min", "type": "integer" }, "max": { "description": "All parameter values should be such that value < max", "type": "integer" } } }, "FloatParameterSpecification": { "type": "object", "properties": { "min": { "description": "All parameter values should be such that value >= min", "type": "number" }, "max": { "description": "All parameter values should be such that value < max", "type": "number" } } }, "StringParameterSpecification": { "type": "object", "properties": { "regexp": { "type": "string", "description": "A regular expression that constrains the values allowed. This regular expression should match the [Javascript syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)\n" } } }, "FileParameterSpecification": { "type": "object", "properties": { "mime_types": { "description": "The list of mime types allowed for this file", "type": "array", "items": { "type": "string" } } } }, "ExcelFileSheetHeaderParameterSpecification": { "type": "object", "properties": { "name": { "description": "Name of header", "type": "string" }, "type": { "description": "Type of header. The following types are supported:\n - integer: any positive or negative integers.\n - float: any positive or negative floats.\n - string: any string\n - url: a string, formatted as a url. Only http:// and https:// urls are supported.\n - datetime: a datetime in YYYY-MM-DDTHH:MM:SS+0 format (GMT)\n - url_to_shorten: a string, formatted as a url. Only http:// and https:// urls are supported.\n Any cell within a column of this type will be replaced by a shortened version before\n being stored for use by a subbot\n", "type": "string", "enum": [ "integer", "float", "string", "url", "datetime", "url_to_shorten" ] }, "is_mandatory": { "description": "If true, mandatory a file that is missing the header cannot be uploaded successfully.", "type": "boolean", "default": false } } }, "ExcelFileSheetParameterSpecification": { "type": "object", "properties": { "headers": { "type": "array", "items": { "$ref": "#/components/schemas/ExcelFileSheetHeaderParameterSpecification" } } } }, "ExcelFileParameterSpecification": { "description": "If the content of a cell does not match the type of its header, the file will be rejected during upload.", "type": "object", "properties": { "sheets": { "type": "array", "items": { "$ref": "#/components/schemas/ExcelFileSheetParameterSpecification" } } } }, "EnumParameterSpecification": { "type": "object", "properties": { "values": { "description": "The list of values that can be chosen for this parameter. The bot editor GUI will display this list in a dropdown for selection.\n", "type": "array", "items": { "type": "string" } } } }, "FileParameterValue": { "type": "object", "description": "The value for parameters of type `file`", "properties": { "url": { "type": "string", "format": "uri", "description": "Where to download the file. This url should not be cached: it is valid for less than 30 seconds." }, "cache_key": { "type": "string", "description": "A unique id which can be used as the key to cache the file downloaded from the url. This id is warranted to change if the file is changed by the user." } } }, "TabularArraysParameterValue": { "type": "object", "description": "The value for parameters of type `excel`", "properties": { "url": { "type": "string", "format": "uri", "description": "Where to download the file. This url should not be cached. It is valid for less than 30 seconds. This url is the full url to the [GET /uploaded-tabular-data](https://developers.alcmeon.com/reference/get_uploaded-tabular-data) endpoint.\n" }, "cache_key": { "type": "string", "description": "A unique id which can be used as the key to cache the file downloaded from the url. This id is warranted to change if the file is changed by the user." } } }, "StringParameterValue": { "type": "string", "description": "The value for parameters of type `string`" }, "FloatParameterValue": { "type": "number", "description": "The value for parameters of type `float`" }, "IntegerParameterValue": { "type": "integer", "description": "The value for parameters of type `integer`" }, "BooleanParameterValue": { "type": "boolean", "description": "The value for parameters of type `boolean`" }, "UrlParameterValue": { "type": "string", "format": "uri", "description": "The value for parameters of type `url`" }, "EnumParameterValue": { "type": "string", "description": "The value for parameters of type `enum`" }, "ParameterValue": { "description": "A value for a parameter", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/StringParameterValue" }, { "$ref": "#/components/schemas/FloatParameterValue" }, { "$ref": "#/components/schemas/IntegerParameterValue" }, { "$ref": "#/components/schemas/BooleanParameterValue" }, { "$ref": "#/components/schemas/UrlParameterValue" }, { "$ref": "#/components/schemas/EnumParameterValue" }, { "$ref": "#/components/schemas/FileParameterValue" }, { "$ref": "#/components/schemas/TabularArraysParameterValue" } ] }, "Parameter": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "integer", "float", "boolean", "string", "url", "enum", "file", "excel" ], "description": "The type of the parameter" }, "name": { "type": "string", "description": "The unique name of the box parameter" }, "description": { "type": "string", "description": "A human-readable description of the meaning of the content of this parameter. Displayed in the Alcméon editor GUI.\n" }, "default": { "$ref": "#/components/schemas/ParameterValue" }, "specification": { "$ref": "#/components/schemas/ParameterSpecification" } } }, "ParameterSpecification": { "description": "This field contains a type-specific dictionary that describes the set of values allowed for this parameter.\n\nThis field can be set to null or an empty dictionary to indicate that no specific constraints exist for this parameter.\n", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/IntegerParameterSpecification" }, { "$ref": "#/components/schemas/FloatParameterSpecification" }, { "$ref": "#/components/schemas/StringParameterSpecification" }, { "$ref": "#/components/schemas/FileParameterSpecification" }, { "$ref": "#/components/schemas/ExcelFileParameterSpecification" }, { "$ref": "#/components/schemas/EnumParameterSpecification" } ] }, "Description": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the bot. It will be displayed in the Alcméon editor GUI" }, "version": { "type": "string", "description": "Which version of the subbot protocol this subbot supports. If this is not specified, we assume the subbot supports the v1 API.", "enum": [ "v1", "v2", "v3" ], "default": "v1" }, "description": { "type": "string", "description": "A human-readable description of what the bot does. Displayed in the Alcméon editor GUI" }, "exits": { "description": "A list of Exit objects, each of which describes an output connector for the bot.", "type": "array", "items": { "$ref": "#/components/schemas/Exit" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/Parameter" }, "description": "A list of Parameter objects, each of which describes an attribute that can be configured within the Alcméon editor GUI for a box instance.\n" }, "input_variables": { "description": "A list of Variable objects, each of which describes a user conversation variable that can be read by the bot when a user enters a box via the input connector.\n", "type": "array", "items": { "$ref": "#/components/schemas/Variable" } }, "output_variables": { "description": "A list of Variable objects, each of which describes a user conversation variable that can be written to by the bot when a user exits a box via one of the bot-specific output connector.\n", "type": "array", "items": { "$ref": "#/components/schemas/Variable" } }, "backends": { "description": "A list of backend names that this bot supports. If no value is specified, this bot supports them all.\n", "type": "array", "items": { "$ref": "#/components/schemas/Backend" } }, "companies": { "description": "A list of Alcméon customer names that this bot supports. If no value is specified, this box will be made available to all customers.\n", "type": "array", "items": { "type": "string" } } } }, "Backend": { "type": "string", "enum": [ "facebook", "twitter", "whatsapp", "gbm", "webchat", "instagram" ] } } }, "security": [ { "basic_auth": [] } ], "paths": { "/description": { "get": { "tags": [ "Configuration" ], "summary": "Describe configuration", "description": "Whenever a new bot box is added to a scenario, we `GET /description` to obtain a description of the bot output connectors, parameters, etc. \n\nThis endpoint can also be invoked at other times during the bot lifecycle. \n", "parameters": [ { "in": "header", "name": "X-Alcmeon-Webhook-Signature", "schema": { "$ref": "#/components/schemas/AlcmeonWebhookSignatureHeader" } } ], "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Description" } } } } } } } } } ```