Custom API
Open in CMSThe Custom API screen defines the HTTP APIs your agent can call during a conversation, for example to look up an order or create a ticket. Found in the agent sidebar under Tools → Custom API. Changes you make here are kept on the page until you click Save all changes.
Custom API
| Import OpenAPI Schema | Opens the import dialog to create APIs from an OpenAPI schema. |
| Add New API | Opens the New API panel. |
| Add Category | Shows a Category name field to create a category. A name that already exists cannot be added. |
| Set Authentication | Opens the Set Authentication panel to apply one authentication to many APIs at once. |
| Empty state | "No APIs Configured" is shown when there are no APIs and no categories. |
| Save all changes | Saves every API, category and order change after you confirm. |
API List and Categories
| API row | Shows the API name and description. Click it to open the Edit API panel. |
| Drag handle | "Drag to reorder". Drag an API to change its order or to move it into another category (or out of all categories). |
| Enable / Disable switch | Turns an API on or off for the agent without deleting it. |
| Delete button | Removes the API from the list. Nothing is saved until you click Save all changes. |
| Rename category | Renames a category. |
| Delete category | Deletes an empty category. Disabled while the category still holds APIs ("Cannot delete: category is not empty"). |
| Empty category | Shows "No APIs in this category. Drag an API here to add it." |
New API / Edit API: Basic Information
| Action Name | A unique, descriptive name for the API (required), for example retrieveWeatherData. |
| Description | Explains in detail what the API does. The agent uses it to decide when to call the API. |
| HTTP Method | GET, POST, PUT, DELETE or PATCH. |
| Target URI | The endpoint the API calls. |
| Loading Text Type | What users see while the API runs: None, Fixed, Dynamic or Auto. |
| Loading Text / Loading Text Prompt | Shown for Fixed (the exact text to display) and Dynamic (a prompt the agent uses to write the text). |
| Rules | Instructions for when and how to use the API, for example "Only provide responses for supported locations". |
| Response Prompt | How the agent should present the result. |
| Additional Properties | Lets the API accept parameters that are not in the properties list. |
| Send Metadata | Sends conversation and user context (agent, user, message and channel info) with each request, as headers and, depending on the HTTP method, in the query string or request body. |
New API / Edit API: Authentication
| Auth Type | None, Basic, Bearer, Custom or Oauth. |
| Key | Bearer: the token. Custom: the header value. |
| Username / Password | Basic authentication credentials. |
| Header Name | Custom: the name of the header that carries the key. |
| OAuth Provider | Client Credentials or Google Service Account (JWT Bearer). |
| Token URL | The OAuth token endpoint. |
| Client ID / Client Secret / Scopes | Client Credentials settings. |
| Google Service Account JSON | Google Service Account: upload the JSON key file from Google Cloud Console. On an existing API you can upload a new file to replace it. |
| User Delegation (Optional) / API Scopes | Google Service Account: the user to act as, and the Google API scopes to request. |
New API / Edit API: Properties
| Property Name | The parameter name. |
| Property Type | Boolean, Number or String. |
| Location | Where the value is sent: Querystring, Header, Body or Path. |
| Required Parameter | Marks the parameter as required. |
| Property Enum | Optional list of allowed values. |
| Property Description | Tells the agent what to put in the parameter. |
| Add New Property | Adds another parameter. |
| Test API | Shown when editing an existing API. Opens the test view. |
| Add New API / Update API | Applies the panel to the list. Click Save all changes afterwards to save it. |
Test API
| Back to Configuration | Returns to the API form. |
| API Details | The HTTP method, authentication, endpoint and description of the API. |
| Parameters | An input for each configured property. |
| Metadata | Shown when Send Metadata is on: Agent ID, User ID, User Email, Inquiry Message ID, Media Type, Messenger Product and Messenger Account Code, sent with the request. |
| Call API | Sends the request. |
| API Response | The status code, Response Headers and Response Body, each with a copy button. |
Import OpenAPI Schema
| Schema Format | JSON or YAML (required). |
| Schema File | Drag and drop or select a JSON or YAML file. |
| Override Authentication | No keeps the existing or no authentication; Yes applies the authentication you set here to every imported API. |
| Paste your OpenAPI schema here | The schema editor (step 2). |
| Import Preview | Lists the New APIs and Updated APIs before importing. |
| Start Import | Adds the APIs to the list. A summary confirms the result; review authentication and click Save all changes. |
Set Authentication
| Authentication fields | The same fields as the Authentication section of an API. |
| Select APIs to update | All APIs grouped by category, with checkboxes, Select All and Clear All. |
| OK | Asks you to confirm, then overwrites the authentication of the selected APIs. Click Save all changes afterwards. |
| Cancel | Closes the panel without changes. |
Related guide: Connect Your API