{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Zoho Cliq Slashcommands Schemas", "definitions": { "SlashCommandResponse": { "type": "object", "description": "Slash Commands API response envelope.", "properties": { "url": { "type": "string" }, "type": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "example": { "url": "/api/v3/commands/227828000000128009", "type": "command", "data": { "name": "greet", "id": "227828000000128009", "handlers": [ { "type": "execution_handler" } ], "creator": { "name": "Ryan West", "id": "119440882" }, "execution_type": "deluge", "hint": "Send a greeting message", "status": "enabled", "max_suggestions": 5, "type": "custom", "description": "Sends a customizable greeting to a user or channel", "scope": "organization", "options": { "user": "The user to greet", "msg": "Custom greeting message" } } } }, "ExecutionRecordResponse": { "type": "object", "description": "Response envelope for slash command handler execution records.", "properties": { "status": { "type": "string", "description": "HTTP status text of the response.", "example": "OK" }, "code": { "type": "integer", "description": "HTTP status code of the response.", "example": 200 }, "data": { "type": "object", "properties": { "logs": { "type": "array", "description": "List of execution log entries.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the execution record." }, "time": { "type": "integer", "format": "int64", "description": "Epoch timestamp (ms) when the handler was executed." }, "executionTime": { "type": "integer", "description": "Time taken to execute the handler, in milliseconds." }, "output": { "type": "string", "description": "Output returned by the handler script (serialized as a JSON string)." }, "user": { "type": "object", "description": "Details of the user who triggered the command execution.", "properties": { "id": { "type": "string" }, "zoho_user_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" } } } } } } } } }, "example": { "status": "OK", "code": 200, "data": { "logs": [ { "user": { "zoho_user_id": "697322516", "last_name": "Raman", "email": "priya.raman@zylker.com", "first_name": "Priya", "id": "697322516" }, "output": "{}", "time": 1770628936698, "executionTime": 183, "id": "d37d7b20-0598-11f1-8871-fb8adfa476c7" }, { "user": { "zoho_user_id": "697322516", "last_name": "Raman", "email": "priya.raman@zylker.com", "first_name": "Priya", "id": "697322516" }, "output": "{}", "time": 1770628887877, "executionTime": 179, "id": "b66694e0-0598-11f1-b90c-55af9267af80" } ] } } }, "v3-exehandler-create": { "type": "object", "description": "Payload for creating a new handler. For Deluge commands, provide `type` and `script`. For Webhook commands, provide `type` and `permissions`.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "execution_handler", "suggestion_handler" ], "description": "Type of the handler to create. Accepted values:
\n\n" }, "script": { "type": "string", "description": "Deluge script source code for the handler.
\nMaximum size: 250KB
\nNote: Applicable only for Deluge commands. Do not pass script for Webhook commands - use permissions instead.\n" }, "permissions": { "type": "array", "maxItems": 5, "description": "List of data attributes to forward to your server in the webhook payload when the handler fires.
\nNote: Applicable only for Webhook commands. Do not pass permissions for Deluge commands - use script instead.
\nMaximum: 5 permissions per handler.
\nAllowed values:\n\nRefer to the permissions availability table in the Create a handler endpoint for per-handler availability.\n", "items": { "type": "string", "enum": [ "attachments", "chat", "location", "user" ] } } } }, "longid_regex": { "type": "string", "description": "Numeric long integer identifier used to reference platform components such as Commands, Functions, Widgets, Message Actions, Schedulers, and Extensions." }, "COMMAND_HANDLER_TYPE_regex": { "type": "string", "enum": [ "execution_handler", "suggestion_handler" ], "description": "Name of a slash command handler. Accepted values: execution_handler (fires on command invocation), suggestion_handler (fires to generate autocomplete suggestions).\n" }, "update-slash-command-request-body": { "type": "object", "description": "Payload for updating a slash command. All fields are optional; only the fields provided will be updated.", "properties": { "execution_url": { "type": "string", "maxLength": 225, "description": "Updated server URL where Cliq will forward handler events. Applicable only for Webhook commands.
\nThis field can be updated independently to redirect the command to a new endpoint without any other changes.
\nMaximum length: 225 characters.\n", "example": "https://api.yourcompany.com/cliq/commands/updated-handler" }, "name": { "type": "string", "maxLength": 30, "description": "Updated name of the slash command. This is the text users type after \"/\" to invoke the command. Must be unique within the command's scope.
\nMaximum length: 30 characters
\nAllowed characters: lowercase letters, numbers, and underscores only. No spaces or special characters allowed.\n" }, "hint": { "type": "string", "maxLength": 128, "description": "Updated hint shown in the slash command picker to help users understand the command's purpose. Should be concise and descriptive.
\nMaximum length: 128 characters\n" }, "description": { "type": "string", "maxLength": 300, "description": "Updated detailed description of the slash command's functionality. This can provide more in-depth information than the hint and may be shown in command documentation or tooltips.
\nMaximum length: 300 characters\n" }, "options": { "type": "object", "description": "Updated options map. Options are additional properties which can alter the output of a /command based on the user's requirements.
\nMaximum size: 5 key-value pairs.
\n\nExample syntax:
\n
{\"options\": {\"location\": \"City to check weather for\", \"unit\": \"Temperature unit: celsius or fahrenheit\"}}
\n", "additionalProperties": { "type": "string", "maxLength": 100 } }, "scope": { "type": "string", "enum": [ "organization", "team", "personal" ], "description": "Updated access scope of the slash command. Determines who can see and use the command.
\nAllowed values:
\n\n" }, "team_ids": { "type": "array", "maxItems": 4, "description": "Updated list of team_ids that are allowed to access the command when scope is set to team. Each ID corresponds to a team within the organization.
\nMaximum items: 4 team IDs can be specified.
\nThis field is required if scope is being changed to team.\n", "items": { "type": "integer" } }, "image": { "type": "string", "maxLength": 204800000, "description": "Updated base64 encoded image used as the command icon. This icon will be displayed next to the command in the slash command picker.
\nImage requirements:
\n\n" }, "max_suggestions": { "type": "integer", "maximum": 5, "description": "Updated maximum number of autocomplete suggestions that can be selected by the user when the command is typed.
\nMaximum value: 5 suggestions\n" } }, "example": { "hint": "Send a personalized greeting - updated", "description": "Sends a customizable greeting to a user or channel", "scope": "organization", "options": { "user": "The user to greet", "msg": "Custom greeting message" }, "max_suggestions": 5 } }, "v3-exehandler-edit": { "type": "object", "description": "Payload for updating an existing handler. For Deluge commands, provide `script`. For Webhook commands, provide `permissions`.", "properties": { "script": { "type": "string", "description": "Updated Deluge script source code for the handler.
\nMaximum size: 250KB
\nNote: Applicable only for Deluge commands.\n" }, "permissions": { "type": "array", "maxItems": 5, "description": "Updated list of data attributes to forward to your server in the webhook payload.
\nNote: Applicable only for Webhook commands.
\nAllowed values: attachments, chat, location, user. Note: attachments is not available for suggestion_handler.\n", "items": { "type": "string", "enum": [ "attachments", "chat", "location", "user" ] } } } }, "create-slash-command-request-body": { "type": "object", "description": "Payload for creating a new slash command.", "required": [ "name", "hint", "scope" ], "properties": { "execution_type": { "type": "string", "enum": [ "deluge", "webhook" ], "description": "Defines how the command executes its handlers.
\n\n", "example": "deluge" }, "execution_url": { "type": "string", "maxLength": 225, "description": "The URL that Zoho Cliq will POST handler events to when the command is invoked.
\nRequired when execution_type is webhook.
\nMaximum length: 225 characters.\n", "example": "https://api.yourcompany.com/cliq/commands/handler" }, "name": { "type": "string", "maxLength": 30, "description": "Name of the slash command. This is the text that users will type after the \"/\" to invoke the command. Must be unique within the command's scope.
\nMaximum length: 30 characters
\nAllowed characters: Only lowercase letters.\n" }, "hint": { "type": "string", "maxLength": 128, "description": "Hint shown in the slash command picker to help users understand the command's purpose. Should be concise and descriptive.
\nMaximum length: 128 characters\n" }, "description": { "type": "string", "maxLength": 300, "description": "Detailed description of the slash command's functionality. This can provide more in-depth information than the hint and may be shown in command documentation or tooltips.
\nMaximum length: 300 characters\n" }, "options": { "type": "object", "description": "Options are additional properties which can alter the output of a /command based on the user's requirements.
\nMaximum size: 5 key-value pairs.
\n\nExample syntax:
\n
{\"options\": {\"location\": \"City to check weather for\", \"unit\": \"Temperature unit: celsius or fahrenheit\"}}
\n", "additionalProperties": { "type": "string", "maxLength": 100 } }, "scope": { "type": "string", "enum": [ "organization", "team", "personal" ], "description": "Access scope of the slash command. Determines who can see and use the command.
\nAllowed values:
\n \n" }, "team_ids": { "type": "array", "maxItems": 4, "description": "List of team_ids that are allowed to access the command when scope is set to team. Each ID corresponds to a team within the organization.
\nMaximum items: 4 team IDs can be specified.
\nThis field is required if scope is team.\n", "items": { "type": "integer" } }, "image": { "type": "string", "maxLength": 204800000, "description": "Base64 encoded image used as the command icon. This icon will be displayed next to the command in the slash command picker and can help users visually identify the command.
\nImage requirements:
\n\n" }, "max_suggestions": { "type": "integer", "maximum": 5, "description": "Maximum number of autocomplete suggestions that can be selected by the user when the command is typed.
\n
Maximum value: 5 suggestions\n" } }, "example": { "name": "greet", "hint": "Send a greeting message", "description": "Sends a customizable greeting to a user or channel", "scope": "organization", "options": { "user": "The user to greet", "msg": "Custom greeting message" }, "max_suggestions": 5 } }, "list-all-slash-commands-response": { "type": "object", "description": "Response schema for listing slash commands.", "properties": { "url": { "type": "string", "example": "/api/v3/commands" }, "type": { "type": "string", "example": "command" }, "sync_token": { "type": "string", "description": "Token for incremental sync. Pass this in the next request to retrieve only commands updated since this response.", "example": "MTB8MTc3NzM2MDM5OTQ5Mnw=" }, "next_token": { "type": "string", "description": "Pagination token for the next page of results." }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "handlers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } } } }, "creator": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" } } }, "execution_type": { "type": "string", "example": "deluge" }, "hint": { "type": "string" }, "status": { "type": "string", "example": "enabled" }, "type": { "type": "string", "example": "custom" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "organization", "team", "personal" ] }, "max_suggestions": { "type": "integer" }, "options": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "example": { "url": "/api/v3/commands", "type": "command", "sync_token": "MTB8MTc3NzM2MDM5OTQ5Mnw=", "data": [ { "name": "report", "id": "227828000000128011", "handlers": [ { "type": "execution_handler" } ], "creator": { "name": "Ryan West", "id": "119440882" }, "execution_type": "deluge", "hint": "Generate a sales or activity report", "status": "enabled", "type": "custom", "description": "Generates a report for the specified date range and team", "scope": "organization", "options": { "type": "Report type (e.g. sales, activity, attendance)", "period": "Date range (e.g. today, this_week, last_month)" } }, { "name": "ticket", "id": "227828000000128009", "handlers": [ { "type": "execution_handler" }, { "type": "suggestion_handler" } ], "creator": { "name": "Ryan West", "id": "119440882" }, "execution_type": "deluge", "hint": "Create or look up a support ticket", "status": "enabled", "max_suggestions": 5, "type": "custom", "description": "Creates a new support ticket or retrieves an existing one by ID", "scope": "team", "options": { "action": "Action to perform (create or lookup)", "priority": "Ticket priority (low, medium, high, critical)" } } ] } }, "base64_regex": { "type": "string", "description": "Base64-encoded pagination or sync token used for cursor-based pagination and incremental data sync." } } }