Create Tool

This endpoint allows you to create a new tool for a specific agent.

​

Creating a Datastore Tool

For more details, see the Datastore Tool documentation.

When creating a tool of type datastore, you must provide the datastoreId of an existing datastore.

{
  "type": "datastore",
  "datastoreId": "clq5g0p5k0001l60t7p1f3b2a"
}

​

Creating a Delayed Responses Tool

For more details, see the Delayed Responses Tool documentation.

When creating a tool of type delayed_responses, you can optionally provide a config object with a delay property to specify the delay time in seconds. The minimum value is 6 seconds.

{
  "type": "delayed_responses",
  "config": {
    "delay": 30
  }
}

​

Creating a Follow-up Messages Tool

For more details, see the Follow-up Messages Tool documentation.

When creating a tool of type follow_up_messages, you can provide a config object to control the follow-up behavior.

• max_sends: The maximum number of follow-up messages to send (integer, 1-10).
• interval_hours: The interval in hours between each message (integer, 1-96).
• messages: The content of the follow-up messages. You can define multiple messages by separating them with ||.

{
  "type": "follow_up_messages",
  "config": {
    "max_sends": 3,
    "interval_hours": 24,
    "messages": "Hello! Just checking in.||Any updates on our previous conversation?||I'm closing this chat now, but feel free to reach out if you need anything else."
  }
}

​

Creating an HTTP Tool

For more details, see the HTTP Tool documentation.

The http tool is highly versatile, allowing you to make requests to any external API. You can configure headers, query parameters, path variables, and the request body.

• type: Must be "http".
• isRaw: (Optional, default: false) If true, the tool is configured with a raw cURL command.
• config: An object containing the HTTP request details.
  • name: A friendly name for the tool (e.g., “Search Weather”).
  • description: A clear explanation of what the tool does. This is crucial for the AI to decide when to use it.
  • url: The base URL of the API endpoint.
  • method: The HTTP method (GET, POST, PUT, DELETE, PATCH).
  • withApproval: (Optional) If true, the AI will require human approval before executing the tool.
  • headers: (Optional) An array of objects (key, value) for request headers.
  • queryParameters: (Optional) An array of objects for URL query parameters.
  • pathVariables: (Optional) An array of objects to substitute parts of the URL (e.g., /users/{userId}).
  • body: (Optional) An array of objects for x-www-form-urlencoded or multipart/form-data request bodies.
  • rawBody: (Optional) A string for a raw JSON request body.
  • hasMaximumToolCalls: (Optional, default: false) If true, limits the number of times the tool can be called.
  • maximumToolCalls: (Optional) The maximum number of calls allowed. Defaults to 1 if hasMaximumToolCalls is true.
  • isErrorCountable: (Optional) If true, failed calls count towards the limit. Defaults to true if hasMaximumToolCalls is true.

For fields like headers, queryParameters, and pathVariables, you can specify isUserProvided: true to indicate that the AI should ask the end-user for that value.

​

Example: Changing Conversation Status

This example demonstrates a more advanced POST request. It’s designed to change the status of a conversation by dynamically providing its ID.

• pathVariables: The conversation_id is dynamically inserted into the URL. The AI will use the context variable {conversation-id} to get the correct value.
• body: The new status is sent in the request body. Since isUserProvided is true, the AI will determine the appropriate status to send.
• acceptedValues: This array restricts the AI to only use one of the three specified values for the status (RESOLVED, UNRESOLVED, HUMAN_REQUESTED), ensuring data integrity.

{
  "type": "http",
  "isRaw": false,
  "config": {
    "name": "Set conversation Status (form)",
    "description": "Change the Status of a conversation between RESOLVED, UNRESOLVED or HUMAN_REQUESTED.",
    "url": "https://api.chatvolt.ai/conversations/:conversation_id/set-status",
    "method": "POST",
    "withApproval": false,
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer <bearer-token>",
        "isUserProvided": false,
        "description": "",
        "acceptedValues": []
      }
    ],
    "body": [
      {
        "key": "status",
        "value": "",
        "isUserProvided": true,
        "description": "New conversation status",
        "acceptedValues": [
          "RESOLVED",
          "UNRESOLVED",
          "HUMAN_REQUESTED"
        ]
      }
    ],
    "queryParameters": [],
    "pathVariables": [
      {
        "key": "conversation_id",
        "value": "",
        "isUserProvided": true,
        "description": "use {conversation-id}",
        "acceptedValues": []
      }
    ],
    "hasMaximumToolCalls": true,
    "maximumToolCalls": 1,
    "isErrorCountable": true
  }
}

​

Example: Search Weather

{
  "type": "http",
  "isRaw": false,
  "config": {
    "name": "Search Weather",
    "description": "Fetches the weather forecast for a specific city.",
    "url": "https://api.weatherapi.com/v1/current.json",
    "method": "GET",
    "withApproval": false,
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json",
        "isUserProvided": false
      }
    ],
    "queryParameters": [
      {
        "key": "key",
        "value": "YOUR_API_KEY",
        "isUserProvided": false,
        "description": "API Key for WeatherAPI."
      },
      {
        "key": "q",
        "value": "London",
        "isUserProvided": true,
        "description": "The name of the city to get the weather for."
      }
    ],
    "hasMaximumToolCalls": true,
    "maximumToolCalls": 5,
    "isErrorCountable": true
  }
}