Skip to content

Add an action

post/add-action
Any key

Adds a new action to the specified chatbot. Top-level fields are checked (see the 400 response); headers, pathParams, queryParams and bodyParams items are stored as sent, without schema checks. An api action is also tested before it is saved: Chat Data sends a request to its url, filling each parameter with its example value, and rejects the action if that request fails.

mcp actions cannot be added with this endpoint. A new action is enabled unless enabled is false; enabled actions count toward your plan's action limit.

Request body

Sending 2 of 2 fields
Required
chatbotIdstring
The ID of the chatbot to which the action will be added.
actionobject
The action to add.
namestring
The name of the action. Only letters, numbers, underscores and hyphens are allowed.
descriptionstring
Description of when to trigger the action.
typestring
The type of action.
For API actions, the URL to call. Use {name} placeholders for path parameters.
For API actions, the HTTP method.
For API actions, the HTTP headers of the request.
For API actions, the URL path parameters.
For API actions, the URL query parameters.
For API actions, the request body parameters.
For search actions, whether to include images in the results. Defaults to true.
For search actions, whether to prioritize recent results.
For search actions, whether to enable the date restriction.
For search actions, the domains to restrict the web search to, as full URLs (for example https://www.example.com). Leave empty to search all domains.
For button actions, the link the button opens. Required for button actions.
For button actions, the button label. Required for button actions.
Whether the action is enabled. New actions are enabled unless this is false.

Only these fields are sent (application/json).

Try it · POST /add-action
curl 'https://api.chat-data.com/api/v2/add-action' \  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",  "action": {    "name": "stockPriceLookup",    "description": "The user wants to know the current stock price of a company",    "type": "search"  }}'
Loading…

Responses

Action successfully added.

Content type: application/json

FieldDescription
statusstring
actionobjectThe action.
action.namestringThe name of the action. Only letters, numbers, underscores and hyphens are allowed.
action.descriptionstringDescription of when to trigger the action.
action.typestringThe type of action. Besides api, search, lead and button, actions created in the dashboard can have other types, such as scrape, document, order_tracking, appointment-ui, mcp or workflow_action.
action.urlstringFor API actions, the URL to call. Use {name} placeholders for path parameters.
action.methodstringFor API actions, the HTTP method. One of: GET, POST, PUT, PATCH, DELETE.
action.headersarray of objectFor API actions, the HTTP headers of the request.
action.headers[].namestringThe name of the header.
action.headers[].valuestringThe value of the header.
action.pathParamsarray of objectFor API actions, the URL path parameters.
action.pathParams[].namestringThe name of the parameter.
action.pathParams[].typestringThe data type of the parameter. One of: string, number, boolean, array, object.
action.pathParams[].descriptionstringDescription of the parameter.
action.pathParams[].requiredbooleanWhether this parameter is required.
action.pathParams[].staticbooleanIndicates whether the parameter is static. A static parameter always sends its example value instead of a value generated by the chatbot.
action.pathParams[].examplestringStringified example value. For non-string types (number, boolean, array, object), the value should be JSON-parseable.
action.pathParams[].itemsobjectFor array types, describes the array items.
action.pathParams[].items.namestringThe name of the property.
action.pathParams[].items.typestringThe data type of the property. One of: string, number, boolean, array, object.
action.pathParams[].items.descriptionstringDescription of the property.
action.pathParams[].items.requiredbooleanWhether this property is required.
action.pathParams[].items.itemsobject
action.pathParams[].items.propertiesarray of objectFor object types, describes the object's properties.
action.pathParams[].propertiesarray of objectFor object types, describes the object's properties.
action.pathParams[].properties[].namestringThe name of the property.
action.pathParams[].properties[].typestringThe data type of the property. One of: string, number, boolean, array, object.
action.pathParams[].properties[].descriptionstringDescription of the property.
action.pathParams[].properties[].requiredbooleanWhether this property is required.
action.pathParams[].properties[].itemsobject
action.pathParams[].properties[].propertiesarray of objectFor object types, describes the object's properties.
action.queryParamsarray of objectFor API actions, the URL query parameters.
action.queryParams[].namestringThe name of the parameter.
action.queryParams[].typestringThe data type of the parameter. One of: string, number, boolean, array, object.
action.queryParams[].descriptionstringDescription of the parameter.
action.queryParams[].requiredbooleanWhether this parameter is required.
action.queryParams[].staticbooleanIndicates whether the parameter is static. A static parameter always sends its example value instead of a value generated by the chatbot.
action.queryParams[].examplestringStringified example value. For non-string types (number, boolean, array, object), the value should be JSON-parseable.
action.queryParams[].itemsobjectFor array types, describes the array items.
action.queryParams[].items.namestringThe name of the property.
action.queryParams[].items.typestringThe data type of the property. One of: string, number, boolean, array, object.
action.queryParams[].items.descriptionstringDescription of the property.
action.queryParams[].items.requiredbooleanWhether this property is required.
action.queryParams[].items.itemsobject
action.queryParams[].items.propertiesarray of objectFor object types, describes the object's properties.
action.queryParams[].propertiesarray of objectFor object types, describes the object's properties.
action.queryParams[].properties[].namestringThe name of the property.
action.queryParams[].properties[].typestringThe data type of the property. One of: string, number, boolean, array, object.
action.queryParams[].properties[].descriptionstringDescription of the property.
action.queryParams[].properties[].requiredbooleanWhether this property is required.
action.queryParams[].properties[].itemsobject
action.queryParams[].properties[].propertiesarray of objectFor object types, describes the object's properties.
action.bodyParamsarray of objectFor API actions, the request body parameters.
action.bodyParams[].namestringThe name of the parameter.
action.bodyParams[].typestringThe data type of the parameter. One of: string, number, boolean, array, object.
action.bodyParams[].descriptionstringDescription of the parameter.
action.bodyParams[].requiredbooleanWhether this parameter is required.
action.bodyParams[].staticbooleanIndicates whether the parameter is static. A static parameter always sends its example value instead of a value generated by the chatbot.
action.bodyParams[].examplestringStringified example value. For non-string types (number, boolean, array, object), the value should be JSON-parseable.
action.bodyParams[].itemsobjectFor array types, describes the array items.
action.bodyParams[].items.namestringThe name of the property.
action.bodyParams[].items.typestringThe data type of the property. One of: string, number, boolean, array, object.
action.bodyParams[].items.descriptionstringDescription of the property.
action.bodyParams[].items.requiredbooleanWhether this property is required.
action.bodyParams[].items.itemsobject
action.bodyParams[].items.propertiesarray of objectFor object types, describes the object's properties.
action.bodyParams[].propertiesarray of objectFor object types, describes the object's properties.
action.bodyParams[].properties[].namestringThe name of the property.
action.bodyParams[].properties[].typestringThe data type of the property. One of: string, number, boolean, array, object.
action.bodyParams[].properties[].descriptionstringDescription of the property.
action.bodyParams[].properties[].requiredbooleanWhether this property is required.
action.bodyParams[].properties[].itemsobject
action.bodyParams[].properties[].propertiesarray of objectFor object types, describes the object's properties.
action.includeImagesbooleanFor search actions, whether to include images in the results. Defaults to true.
action.prioritizeRecentResultsbooleanFor search actions, whether to prioritize recent results.
action.enableDateRestrictionbooleanFor search actions, whether to enable the date restriction.
action.includedDomainsarray of stringFor search actions, the domains to restrict the web search to, as full URLs (for example https://www.example.com). Leave empty to search all domains.
action.linkstringFor button actions, the link the button opens. Required for button actions.
action.labelstringFor button actions, the button label. Required for button actions.
action.enabledbooleanWhether the action is enabled. New actions are enabled unless this is false.
action.indexintegerThe position of the action in the chatbot's action list (0-based).
action.return_filebooleanWhether the action returns a file.

Example

{  "status": "success",  "action": {    "index": 0,    "name": "stockPriceLookup",    "description": "The user wants to know the current stock price of a company",    "type": "api",    "url": "https://api.example.com/stocks/{symbol}/price",    "method": "GET",    "headers": [      {        "name": "Authorization",        "value": "Bearer stk_live_3f9a2c7d1e"      }    ],    "pathParams": [      {        "name": "symbol",        "type": "string",        "description": "The stock ticker symbol to look up.",        "required": true,        "example": "AAPL"      }    ],    "return_file": false  }}

Last updated October 14, 2026