AI Actions for developers
What your endpoint receives when the AI runs an AI Action: request templating with {{input}} and {{secret}}, validation, timeouts, retries, response handling and approval.
An AI Action is an HTTP request the AI can make to your systems during a live chat, for example to look up an order or start a refund. Managers define actions in Studio under AI Agent > Actions; this page is about the endpoint on your side.
The definition
| Field | Rules |
|---|---|
| Name | Up to 80 characters. |
| Tool name | 2 to 48 lowercase letters, digits or underscores, starting with a letter. This is the name the AI sees. |
| Description | Up to 1,000 characters. Tells the AI when to use the action; make it precise. |
| Method | GET, POST, PUT, PATCH or DELETE. |
| URL | A full https:// URL, up to 2,048 characters. Inputs may fill the path and query, never the host. |
| Headers | A JSON object of up to 20 headers, single-line values up to 1,000 characters. |
| Secret | Optional credential, stored encrypted. Only usable in headers. |
| Inputs | A small JSON Schema (below). |
| Timeout | 1 to 15 seconds, default 10. |
| Require approval | On by default. |
| Verified only | Offer the action only in conversations with a verified contact (see Signed identity). |
Inputs
A flat object of up to 20 properties, each of type string, number, integer or boolean, with optional description (up to 500 characters), enum (up to 50 values), minLength/maxLength (strings, up to 2,000) and minimum/maximum (numbers). pattern is not supported, secret is a reserved name, and writeOnly: true (or x-redact: true) keeps a value out of the audit log.
The AI's arguments are checked against this schema before anything is sent. Unknown properties and wrong types are refused, never coerced.
Templating
{{name}}in the URL's path or query is replaced by that input, percent-encoded.{{name}}and{{secret}}may appear in header values.{{secret}}is not allowed in the URL, where it would be logged.- Inputs not used in the URL go in a JSON body for
POST,PUTandPATCH(withContent-Type: application/jsonunless you set one), or in the query string forGETandDELETE. - Substituted values are never rescanned, so an input containing
{{secret}}stays literal text. A value that would break a header line is refused.
QuantCX also sends User-Agent: QuantCX-Actions/1.0, Accept: application/json, text/plain;q=0.9, */*;q=0.1 and Accept-Encoding: identity. Transport headers such as Host, Content-Length, Transfer-Encoding and Connection cannot be set.
Endpoint requirements
- Public HTTPS on port 443, with no credentials in the URL. The host is checked to resolve to a public address when the action is saved and again when each request connects.
- Redirects are not followed: a
3xxis a failure. Use the final URL. - Answer within the action's timeout (at most 15 seconds).
Responses
- A
2xxis success. QuantCX reads at most 64 KB of the body. - A JSON body (by
Content-Type) is parsed; anything else is treated as text. The AI is shown at most 8 KB of it (and at most 6,000 characters per tool result), with the action's secret removed. Nothing of the body is stored. - Return only what the customer may be told. The AI is instructed to treat results as data, never as instructions, and not to share internal ids or raw technical output.
- Any other status is a failure, and the AI tells the customer it could not complete the request.
Timeouts and retries
On a network error or a 5xx, GET, PUT and DELETE are retried once after a short pause. POST and PATCH are never retried, so a request is not repeated where repeating could do something twice. Make PUT and DELETE handlers idempotent.
Approval
When an action requires approval, the AI's request is held instead of sent, and the customer is told their request is being reviewed. Owners, admins and managers decide it under Waiting for approval on the Actions page, with a link to the conversation.
- Approve sends the request now with the inputs the AI chose, adds the details to the conversation as an internal note, and tells the customer the outcome in a fixed message, translated into their language.
- Reject sends nothing to your endpoint; the customer is told a teammate reviewed their request and will follow up.
- Requests nobody decides expire, after 24 hours by default. Nothing is sent to the customer on expiry.
- An approval does not survive the action being switched off in the meantime.
Limits and audit
- Each plan includes a monthly number of action runs; a held request counts once, together with its approved run.
- Per AI reply, at most 3 rounds of tool calls and 3 calls per round. At most 32 actions are offered at once.
- Every attempt is written to an audit log with its status, HTTP status and duration. Inputs marked
writeOnly, and inputs whose names look sensitive (password, secret, token, API key, auth, credential, card, CVV, SSN, IBAN, PIN), are stored as[redacted]. - Stress tests never run actions; they record what the AI would have sent.