Custom API integrations

Custom API integrations let your chatbot request live information from your ERP, warehouse, CRM, or another service. They can also make changes, such as creating an appointment. An integration stores the base URL; each operation defines one callable request. You then attach selected operations to a chatbot as AI actions.

Before You Start

Check that your account includes Custom API integrations. You need the endpoint's URL, HTTP method, parameter names and types, authentication requirements, and an example response. The endpoint must be reachable from ChatLab's servers; localhost on your computer is not a production endpoint.

Use HTTPS and a test service or test records for setup. A test request really calls the endpoint, so a POST, PATCH, or DELETE may change external data. Make operations safe to repeat where possible.

1. Create an Integration

1. Open Custom Integrations in the main navigation.
2. Click + Define API Integration.
3. Enter API name and API Base URL, for example https://api.example.com.
4. Click Create API Integration.
5. In its list entry, click View, then + Define API Operation.

2. Define the Operation

Give the operation a recognizable label and a machine-readable Operation name, such as getProductDetails. Use letters and numbers only for the operation name, not spaces or underscores. Describe what the operation does and when the chatbot should use it.

Enter the relative URI, for example /v1/products/@productId@. The base URL and URI form the request address.

Some existing screenshots show older sample names or brace-style placeholders. Follow the current syntax below: operation names such as getProductDetails and parameter placeholders surrounded by @.

Path and Query Parameters

Click Add path variable to define productId. Set its data type and value source, then include @productId@ in the URI. Path variables are required, and every defined path variable must appear in the URI before you can save or test.

Use Add query parameter for parameters such as limit or language that belong after the URL's question mark. Enter the name expected by your API, its type, description, and value source.

Available value sources include:

• Provided by user or chatbot: the model supplies a value from the conversation. Explain the expected format and mark required values appropriately.
• Constant: a value configured in the operation, such as a fixed account identifier or restricted API credential.
• Random value: a value generated automatically.
• Client context: a value passed by the host website, where available for your account. See Chat API.

Scalar types include string, integer, double, and boolean. Body parameters also support string and integer arrays.

3. Configure the Method and Body

Choose GET, POST, PUT, PATCH, or DELETE to match your endpoint. For methods other than GET, the editor offers raw or form-data request content.

For a raw JSON body, define the body parameters and insert their @name@ placeholders in the template. Add the appropriate Content-Type header required by your endpoint. For example, with string name and string-array tags parameters:

{
  "name": "@name@",
  "tags": @tags@
}

This is a template, not literal JSON until substitution. Array placeholders must not be surrounded by quotes. Every defined body parameter must be used in the template when the raw-body editor applies. Check the rendered request during testing, including text containing quotes or special characters.

4. Add Authentication Headers

Use Add header to define the headers expected by the API. For a bearer token, use header name Authorization, value source Constant, and value Bearer YOUR_RESTRICTED_TOKEN.

Keep secrets out of prompts and URLs. Avoid operations that return login tokens to the model and rely on instructions to hide them. Prefer a server-side integration endpoint that manages its own authentication and exposes only the permitted operation.

5. Save and Test the Request

1. Click Save changes in the operation editor. Unlike normal chatbot Settings, this editor has an explicit save button.
2. Click Test API Operation. It is disabled while changes are unsaved.
3. Enter representative parameter values. For array test inputs, use comma-separated values.
4. Run the test only against data you are authorized to read or change.
5. Inspect the status code, response body, request URL, headers, body, and any warning shown in the results.
6. Correct errors, save, and repeat as needed.

Do not share test output containing credentials. Return focused, paginated data where possible: large responses can be truncated before they reach the model.

6. Attach the Operation to a Chatbot

Open your chatbot, then Settings > Actions. Use the plus button to add an action, find your operation under custom APIs, and attach or enable it. Creating an account-level integration alone does not make every operation available to every chatbot.

Review the action's instructions and available security settings, then wait for the saved status. See AI actions for the action editor.

7. Explain When to Use It

Open Settings > Role & Behavior.

If you use custom role instructions, select Custom Role Definition and add a precise rule, for example: "When the visitor asks whether a product is in stock, call getProductDetails with its product ID. Report the returned availability. If the lookup fails, explain that availability could not be checked."

Preserve the chatbot's other useful instructions. Wait for the saved status, then use the Overview preview to test realistic questions, missing parameters, errors, and unauthorized requests. Preview conversations can invoke real operations.

AI invocation is not guaranteed or necessarily once-only. Test with the model selected for your chatbot; do not assume a model name alone guarantees correct tool use.

Security and Troubleshooting

Your endpoint must authenticate requests and authorize each user's access before returning sensitive information or performing a change. A browser-supplied client ID, email, order number, or context field is not sufficient proof of identity. If you pass a per-user token through client context, your server must validate it.

Return only the fields the chatbot needs, such as order status instead of a full customer profile. Prompt instructions can guide wording, but cannot guarantee that sensitive data returned to the model stays hidden.

If the request succeeds in the test editor but not in a conversation, check the attached action, its enabled state, instructions, required parameters, and available context. If both fail, inspect the URL, HTTP method, authentication, rendered body, and your endpoint's logs. Avoid repeatedly retrying a write operation until you know whether the previous request succeeded.