Zoho Cliq · Schema
Zoho Cliq Bots Schemas
MessagingTeam CollaborationChatBotsWebhooksSlash CommandsCommunication
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Zoho Cliq Bots Schemas",
"definitions": {
"BotIncomingWebhookRequest": {
"type": "object",
"description": "Request body for the incoming webhook endpoint. Accepts any number of custom key-value parameters that are passed directly to the bot's <code>incoming_webhook_handler</code> Deluge script. Up to 50 additional parameters are supported, each with a maximum value length of 10,000 characters. There are no fixed or required fields.\n",
"properties": {
"custom_parameters": {
"type": "object",
"description": "Pass additional key-value pairs in the request body to provide context to the bot's handler. These parameters are user-defined and can carry any metadata relevant to your integration.\n<br><br>\n<b>Rules for Custom Parameters</b>\n<ul>\n <li>Up to 50 custom parameters are supported per request.</li>\n <li>Each parameter value can be up to 10,000 characters.</li>\n <li>All values must be of type string.</li>\n <li>Parameter keys should be unique to avoid overwriting values in the bot handler.</li>\n</ul>\n<b>Common Use Cases</b>\n<ul>\n <li>Webhook Verification: Some platforms send a challenge_key during webhook registration to confirm that the endpoint is reachable. Your bot handler should echo it back in the response to complete the handshake.</li>\n <li>CI/CD & Monitoring: Pass parameters like alert_type, build_status, or environment to notify teams about pipeline failures or infrastructure incidents in real time.</li>\n <li>CRM & E-commerce: Send deal updates, order status changes, and customer activity metadata to keep sales and support teams informed without manual intervention.</li>\n</ul>\n"
}
},
"additionalProperties": {
"type": "string"
},
"example": {
"alert_type": "deployment",
"environment": "production",
"service_name": "payment-gateway",
"severity": "critical",
"triggered_by": "CI/CD pipeline"
}
},
"BotIncomingWebhookResponse": {
"type": "object",
"description": "Response returned after a successful incoming webhook message delivery. Contains the list of user IDs that received the message.",
"properties": {
"user_ids": {
"type": "array",
"description": "List of user IDs to whom the bot message was successfully delivered.",
"items": {
"type": "string"
},
"example": [
"55743307",
"55622727"
]
}
},
"example": {
"user_ids": [
"55743307",
"55622727"
]
}
},
"NoResponse": {
"type": "object",
"description": "Represents an empty successful response where no payload is returned.",
"properties": {
"Response Code": {
"type": "string",
"description": "HTTP response code indicating no content is returned.",
"example": "204 No response"
}
}
},
"BotGetResponse": {
"type": "object",
"description": "Response returned when retrieving the details of a specific bot.",
"properties": {
"url": {
"type": "string",
"description": "API endpoint URL for the retrieved bot resource.",
"example": "/api/v3/bots/b-53719000001878011"
},
"type": {
"type": "string",
"description": "Resource type.",
"example": "bot"
},
"data": {
"type": "object",
"description": "Full configuration and details of the bot.",
"properties": {
"unique_name": {
"type": "string",
"description": "Unique identifier of the bot.",
"example": "supportbot"
},
"name": {
"type": "string",
"description": "Display name of the bot.",
"example": "Support Bot"
},
"id": {
"type": "string",
"description": "Numeric ID of the bot.",
"example": "53719000001878011"
},
"description": {
"type": "string",
"description": "Description of the bot.",
"example": "Handles support workflows"
},
"scope": {
"type": "string",
"description": "Access level of the bot.",
"example": "organization"
},
"channel_participation": {
"type": "array",
"description": "Channel interaction capabilities of the bot.",
"items": {
"type": "string"
},
"example": [
"listen_message",
"send_message",
"auto_follow_thread"
]
},
"handlers": {
"type": "array",
"description": "Handlers configured for the bot.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Handler type.",
"example": "menu_handler"
},
"id": {
"type": "string",
"description": "Unique ID of the handler (present for menu_handler).",
"example": "53719000001878017"
},
"name": {
"type": "string",
"description": "Display name of the menu action (present for menu_handler).",
"example": "Action"
},
"icon": {
"type": "string",
"description": "Icon reference for the menu action (present for menu_handler).",
"example": "wand/627282"
},
"position": {
"type": "integer",
"description": "Display position of the menu action (present for menu_handler).",
"example": 1
},
"sub_actions": {
"type": "array",
"description": "Sub-actions under the menu handler.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Sub Action"
},
"icon": {
"type": "string",
"example": "wand/627282"
}
}
}
}
}
}
},
"creator": {
"type": "object",
"description": "User who created the bot.",
"properties": {
"name": {
"type": "string",
"description": "Name of the creator.",
"example": "James"
},
"id": {
"type": "string",
"description": "ZUID of the creator.",
"example": "65113112"
}
}
},
"execution_type": {
"type": "string",
"description": "Script execution engine used by the bot.",
"example": "deluge"
},
"status": {
"type": "string",
"description": "Current operational status of the bot.",
"example": "enabled"
},
"type": {
"type": "string",
"description": "Bot category. Always custom for user-created bots.",
"example": "custom"
},
"default": {
"type": "boolean",
"description": "Indicates whether this is the default bot.",
"example": false
},
"subscriber_count": {
"type": "integer",
"description": "Number of users subscribed to the bot.",
"example": 1
},
"calls": {
"type": "string",
"description": "Indicates whether bot calls are enabled or disabled.",
"example": "disabled"
}
}
}
}
},
"BotCreateResponse": {
"type": "object",
"description": "Response returned after successfully creating a bot.",
"properties": {
"url": {
"type": "string",
"description": "API endpoint URL for the created bot resource.",
"example": "/api/v3/bots"
},
"type": {
"type": "string",
"description": "Resource type.",
"example": "bot"
},
"data": {
"type": "object",
"description": "The created bot object.",
"properties": {
"unique_name": {
"type": "string",
"description": "System-generated unique identifier for the bot (derived from name, cannot be changed).",
"example": "clientcarebot"
},
"name": {
"type": "string",
"description": "Display name of the bot as provided in the request.",
"example": "Clientcare Bot"
},
"id": {
"type": "string",
"description": "Unique numeric ID assigned to the bot.",
"example": "53719000002124012"
},
"description": {
"type": "string",
"description": "Description of the bot as provided in the request.",
"example": "Your client care co-pilot streamlining support by providing instant customer context and easy access to critical resources."
},
"scope": {
"type": "string",
"description": "Access level of the bot as provided in the request.",
"example": "team"
},
"team_ids": {
"type": "array",
"description": "Team IDs mapped to the bot (present when scope is team).",
"items": {
"type": "integer"
},
"example": [
12345678
]
},
"status_messages": {
"type": "array",
"description": "Status messages assigned to the bot.",
"items": {
"type": "string"
},
"example": [
"Here to help you with client support!"
]
},
"channel_participation": {
"type": "array",
"description": "Channel interaction capabilities of the bot.",
"items": {
"type": "string"
},
"example": [
"send_message"
]
},
"calls": {
"type": "string",
"description": "Indicates whether bot calls are enabled or disabled.",
"example": "enable"
},
"handlers": {
"type": "array",
"description": "List of handlers configured for the bot. Empty at creation time.",
"items": {
"type": "object"
}
},
"creator": {
"type": "object",
"description": "Details of the user who created the bot.",
"properties": {
"name": {
"type": "string",
"description": "Name of the creator.",
"example": "James"
},
"id": {
"type": "string",
"description": "ZUID of the creator.",
"example": "65113112"
}
}
},
"execution_type": {
"type": "string",
"description": "Script execution engine used by the bot.",
"example": "deluge"
},
"status": {
"type": "string",
"description": "Current operational status of the bot.",
"example": "enabled"
},
"type": {
"type": "string",
"description": "Bot category. Always custom for user-created bots.",
"example": "custom"
},
"default": {
"type": "boolean",
"description": "Indicates whether this is the default bot for the organization.",
"example": false
},
"subscriber_count": {
"type": "integer",
"description": "Number of users subscribed to the bot.",
"example": 1
}
}
}
}
},
"GenericResponse": {
"type": "object",
"description": "Generic successful response envelope used for bot APIs where detailed payload schema varies.",
"properties": {
"url": {
"type": "string",
"description": "Endpoint URL associated with the response."
},
"type": {
"type": "string",
"description": "Resource type returned by the API."
},
"data": {
"type": "object",
"description": "Resource payload.",
"additionalProperties": true
}
},
"additionalProperties": true
},
"BotListResponse": {
"type": "object",
"description": "Response schema for listing bots.",
"properties": {
"url": {
"type": "string",
"description": "API endpoint URL for the listed resources.",
"example": "/api/v3/bots"
},
"type": {
"type": "string",
"description": "Resource type.",
"example": "bot"
},
"next_token": {
"type": "string",
"description": "Pagination token to fetch the next page of results.",
"example": "NTB8MTc1NjM2MjA5MzQ5OHw1MzcxOTAwMDAwMTYyMDAwMw=="
},
"sync_token": {
"type": "string",
"description": "Token used for incremental synchronization to fetch changes since the last sync.",
"example": "NTB8MTc3NzM0MjEyNzQ3OHw1MzcxOTAwMDAwMTg3ODAxMQ=="
},
"deleted": {
"type": "array",
"description": "IDs of deleted bots returned during incremental sync.",
"items": {
"type": "string"
}
},
"data": {
"type": "array",
"description": "List of bot objects.",
"items": {
"type": "object",
"properties": {
"unique_name": {
"type": "string",
"description": "Unique identifier of the bot.",
"example": "supportbot"
},
"name": {
"type": "string",
"description": "Display name of the bot.",
"example": "Support Bot"
},
"id": {
"type": "string",
"description": "Numeric ID of the bot.",
"example": "53719000001878011"
},
"description": {
"type": "string",
"description": "Description of the bot.",
"example": "Handles support workflows"
},
"scope": {
"type": "string",
"description": "Access level of the bot.",
"example": "organization"
},
"channel_participation": {
"type": "array",
"description": "Channel interaction capabilities of the bot.",
"items": {
"type": "string"
},
"example": [
"listen_message",
"send_message",
"auto_follow_thread"
]
},
"handlers": {
"type": "array",
"description": "Handlers configured for the bot.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Handler type.",
"example": "menu_handler"
},
"id": {
"type": "string",
"description": "Unique ID of the handler (present for menu_handler).",
"example": "53719000001878017"
},
"name": {
"type": "string",
"description": "Display name of the menu action (present for menu_handler).",
"example": "Action"
},
"icon": {
"type": "string",
"description": "Icon reference for the menu action (present for menu_handler).",
"example": "wand/627282"
},
"position": {
"type": "integer",
"description": "Display position of the menu action (present for menu_handler).",
"example": 1
},
"sub_actions": {
"type": "array",
"description": "Sub-actions under the menu handler.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Sub Action"
},
"icon": {
"type": "string",
"example": "wand/627282"
}
}
}
}
}
}
},
"creator": {
"type": "object",
"description": "User who created the bot.",
"properties": {
"name": {
"type": "string",
"description": "Name of the creator.",
"example": "James"
},
"id": {
"type": "string",
"description": "ZUID of the creator.",
"example": "65113112"
}
}
},
"execution_type": {
"type": "string",
"description": "Script execution engine used by the bot.",
"example": "deluge"
},
"status": {
"type": "string",
"description": "Current operational status of the bot.",
"example": "enabled"
},
"type": {
"type": "string",
"description": "Bot category. Always custom for user-created bots.",
"example": "custom"
},
"default": {
"type": "boolean",
"description": "Indicates whether this is the default bot.",
"example": false
},
"subscriber_count": {
"type": "integer",
"description": "Number of users subscribed to the bot.",
"example": 1
},
"calls": {
"type": "string",
"description": "Indicates whether bot calls are enabled or disabled.",
"example": "disabled"
}
}
}
}
}
},
"BotHandlerCreateResponse": {
"type": "object",
"description": "Response schema returned when a new bot handler is created successfully.",
"properties": {
"url": {
"type": "string",
"description": "Endpoint URL of the newly created handler resource."
},
"type": {
"type": "string",
"description": "Resource type identifier.",
"example": "execution_handler"
},
"data": {
"type": "object",
"description": "Configuration details of the created handler.",
"properties": {
"script": {
"type": "string",
"description": "Deluge source code of the handler."
},
"return_type": {
"type": "string",
"description": "Return type expected from the handler script.",
"example": "MAP"
},
"params": {
"type": "array",
"description": "List of runtime parameters passed to the handler script.",
"items": {
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "Name of the parameter."
},
"param_type": {
"type": "string",
"description": "Data type of the parameter (e.g., MAP, STRING, BOOLEAN)."
}
}
}
}
},
"additionalProperties": true
}
},
"example": {
"url": "/api/v3/bots/b-53719000001887001/handlers",
"type": "execution_handler",
"data": {
"script": "response = Map();\nresponse.put(\"text\", \"Welcome! I'm your assistant bot. Send me a message to get started.\");\nreturn response;",
"return_type": "MAP",
"params": [
{
"param_name": "access",
"param_type": "MAP"
},
{
"param_name": "environment",
"param_type": "MAP"
},
{
"param_name": "user",
"param_type": "MAP"
},
{
"param_name": "newuser",
"param_type": "BOOLEAN"
}
]
}
}
},
"BotHandlerDetailsResponse": {
"type": "object",
"description": "Response schema returned when fetching the full details of a specific bot handler.",
"properties": {
"url": {
"type": "string",
"description": "Endpoint URL of the handler resource."
},
"type": {
"type": "string",
"description": "Resource type identifier.",
"example": "execution_handler"
},
"data": {
"type": "object",
"description": "Full configuration and metadata of the handler.",
"properties": {
"script": {
"type": "string",
"description": "Deluge source code of the handler."
},
"handler_id": {
"type": "string",
"description": "Unique identifier of the handler."
},
"name": {
"type": "string",
"description": "Display name of the handler (used for menu-type handlers)."
},
"type": {
"type": "string",
"description": "Type of the handler.",
"enum": [
"welcome_handler",
"message_handler",
"mention_handler",
"context_handler",
"participation_handler",
"incoming_webhook_handler",
"menu_handler",
"call_handler"
]
},
"icon": {
"type": "string",
"description": "Icon reference for the handler, applicable for menu handlers."
},
"return_type": {
"type": "string",
"description": "Return type expected from the handler script.",
"example": "MAP"
},
"params": {
"type": "array",
"description": "List of parameters passed to the handler script at runtime.",
"items": {
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "Name of the parameter."
},
"param_type": {
"type": "string",
"description": "Data type of the parameter (e.g., MAP, STRING)."
}
}
}
}
},
"additionalProperties": true
}
},
"example": {
"url": "/api/v3/bots/b-53719000001887001/handlers/menu_handler",
"type": "execution_handler",
"data": {
"script": "response = Map();\nresponse.put(\"text\", \"\ud83d\udc4b Hi! Choose an option below to get started with the IT Help Desk bot.\");\nreturn response;",
"handler_id": "53719000002155003",
"name": "IT Help Desk",
"type": "menu_handler",
"icon": "wand/627282",
"return_type": "MAP",
"params": [
{
"param_name": "access",
"param_type": "MAP"
},
{
"param_name": "environment",
"param_type": "MAP"
},
{
"param_name": "chat",
"param_type": "MAP"
},
{
"param_name": "user",
"param_type": "MAP"
},
{
"param_name": "location",
"param_type": "MAP"
},
{
"param_name": "sub_action",
"param_type": "STRING"
}
]
}
}
},
"BotHandlerResponse": {
"type": "object",
"description": "Response schema for bot handler create, update, and fetch operations.",
"properties": {
"url": {
"type": "string",
"description": "Endpoint URL for the handler resource."
},
"type": {
"type": "string",
"description": "Resource type.",
"example": "execution_handler"
},
"data": {
"type": "object",
"description": "Handler payload.",
"additionalProperties": true
}
},
"example": {
"url": "/api/v3/bots/b-4000000010001/handlers/menu",
"type": "execution_handler",
"data": {
"display_props": {
"position": 2,
"name": "a123",
"icon": "wand/627282"
},
"id": "53719000001973033"
}
}
},
"BotHandlerLogsResponse": {
"type": "object",
"description": "Response schema for bot handler execution logs.",
"properties": {
"url": {
"type": "string",
"description": "Endpoint URL for the execution log resource."
},
"type": {
"type": "string",
"description": "Resource type.",
"example": "execution_handler"
},
"data": {
"type": "object",
"properties": {
"logs": {
"type": "array",
"description": "Execution logs containing debug information.",
"items": {
"type": "object",
"properties": {
"debugInfo": {
"type": "array",
"description": "Debug information entries as serialized JSON strings.",
"items": {
"type": "string",
"description": "Serialized JSON string containing debug trace information with timestamp and message details."
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"example": {
"url": "/api/v3/commands/4000000011005/handlers/welcome/logs",
"type": "execution_handler",
"data": {
"logs": [
{
"debugInfo": [
"{\"time\":1772868058306,\"message\":{\"mentions\":[],\"text\":\"asf\",\"type\":\"text\",\"content\":{\"text\":\"asf\"}}}"
]
}
]
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"example": "The request cannot be performed. Usually because of malformed parameter or missing parameter."
}
}
},
"BotSubscribersResponse": {
"type": "object",
"description": "Represents the response structure for fetching subscribers of a specific bot. Contains metadata and a list of subscriber details.",
"properties": {
"url": {
"type": "string",
"description": "The API endpoint URL to retrieve the list of subscribers for the specified bot.",
"example": "/api/v3/bots/{BOT_UNIQUE_NAME}/subscribers"
},
"type": {
"type": "string",
"description": "The type of the response object. Typically indicates the resource or entity being described.",
"example": "bot_subscriber"
},
"sync_token": {
"type": "string",
"description": "A token used to synchronize and track the state of the subscribers list across requests.",
"example": "NTB8MTcyMjcwMDXwxNzIyNzA5MzQ0NDM5"
},
"data": {
"type": "array",
"description": "An array containing subscriber details associated with the bot.",
"items": {
"$ref": "#/components/schemas/BotSubscriber"
}
}
}
},
"BotSubscriber": {
"type": "object",
"description": "Detailed information about an individual subscriber of the bot.",
"properties": {
"email_id": {
"type": "string",
"description": "The email address of the subscriber, used for identification and communication.",
"example": "[email protected]"
},
"user_id": {
"type": "string",
"description": "A unique identifier assigned to the subscriber within the system.",
"example": "19183988"
},
"name": {
"type": "string",
"description": "The full name of the subscriber.",
"example": "Scott Fisher"
}
}
},
"Trigger-Bot-Call-Request": {
"type": "object",
"description": "Represents the request body for triggering a bot call with a message, recipients, retries, loops, and optional actions.",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 500,
"description": "The message to be dictated during the call.<br> <b>Limit:</b> 500 characters.\n"
},
"user_ids": {
"type": "array",
"maxItems": 10,
"description": "List of user ZUIDs or emails.<br> <b>Limit:</b> 10 entries.\n",
"items": {
"type": "string",
"description": "User identifier, which can be either a ZUID or an email address."
}
},
"retry": {
"type": "integer",
"maximum": 3,
"description": "Number of retries if the user misses the call. System will retry after 2 minutes.<br> <b>Maximum Attempts:</b> 3\n"
},
"loop": {
"type": "integer",
"maximum": 3,
"description": "Number of times the message will be dictated.<br> <b>Maximum:</b> 3\n"
},
"actions": {
"type": "array",
"maxItems": 5,
"description": "List of actions to be displayed as buttons during the call. <br>Each action includes a label, icon, and a specific action with its associated data. <br><b>Limit:</b> 5\n",
"items": {
"type": "object",
"description": "Defines the structure of an action button shown during the bot call.",
"required":
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-cliq/refs/heads/main/json-schema/bots.json