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

FieldRules
NameUp to 80 characters.
Tool name2 to 48 lowercase letters, digits or underscores, starting with a letter. This is the name the AI sees.
DescriptionUp to 1,000 characters. Tells the AI when to use the action; make it precise.
MethodGET, POST, PUT, PATCH or DELETE.
URLA full https:// URL, up to 2,048 characters. Inputs may fill the path and query, never the host.
HeadersA JSON object of up to 20 headers, single-line values up to 1,000 characters.
SecretOptional credential, stored encrypted. Only usable in headers.
InputsA small JSON Schema (below).
Timeout1 to 15 seconds, default 10.
Require approvalOn by default.
Verified onlyOffer 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.

<code>{ "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number the customer gives", "maxLength": 40 }, "reason": { "type": "string", "enum": ["damaged", "late", "other"] } }, "required": ["order_id"] }</code>

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, PUT and PATCH (with Content-Type: application/json unless you set one), or in the query string for GET and DELETE.
  • Substituted values are never rescanned, so an input containing {{secret}} stays literal text. A value that would break a header line is refused.
<code>POST https://api.example.com/orders/{{order_id}}/refunds Authorization: Bearer {{secret}} → POST https://api.example.com/orders/A-1001/refunds Authorization: Bearer sk_… Content-Type: application/json {"reason":"damaged"}</code>

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 3xx is a failure. Use the final URL.
  • Answer within the action's timeout (at most 15 seconds).

Responses

  • A 2xx is 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.