Custom actions

A custom action points the agent at any HTTPS API you already have: your order system, your CRM, an internal tool. You describe when to use it and which inputs to collect; the agent asks the visitor, makes the call, and answers with the result. Your database is never exposed.

Create an action

1. Open Custom Actions and click New action

   The same page lists every action in the workspace, including the ones integrations created.

2. Name it and say when to use it

   Name (up to 60 characters) and When to use (up to 500). The second field is what the agent reads to decide, so be specific: "Use when the customer asks about their order status, delivery date, or wants to track a package."

3. Set the request

   Method (GET, POST, PUT, PATCH or DELETE) and an HTTPS URL. Reference inputs anywhere with {{input_name}}, for example https://api.yourdomain.com/orders/{{order_id}}. Placeholders are allowed in the path and query, never in the host.

4. Define the inputs the agent collects

   Up to 10 inputs, each with a name (letters, numbers and underscores, starting with a letter) and a description the agent uses when asking the visitor ("The unique order number provided by the customer"). Every input is required text.

5. Add headers

   Up to 10, for example Authorization: Bearer sk-…. Values are stored encrypted and never shown again; editing headers later replaces all of them.

6. Add a body (POST, PUT, PATCH)

   Up to 4,000 characters, usually JSON such as { "orderId": "{{order_id}}" }. Put placeholders inside quotes in JSON.

7. Limit what the agent may read

   Response fields the agent may read: comma-separated paths such as order.status, order.eta or data.0.id, up to 20. Leave empty to pass the whole response.

8. Save, test, enable

   New actions start disabled. Click Test, enter sample inputs and check the status and body. Flip the switch on the card when it is right.

Body encodings

The body is sent as JSON unless you add a Content-Type header: application/x-www-form-urlencoded sends a form body, and a type containing xml sends XML. Inputs are escaped for whichever encoding is in use, so a visitor cannot break out of a JSON string or an XML element. Other content types are refused when the body contains placeholders. GET and DELETE never send a body.

What happens at run time

• The action is a tool the agent may use when a visitor's request matches your "when to use" text. It collects missing inputs first and never invents values.
• The request goes to your API over HTTPS with the visitor's inputs escaped for their place in the URL, header or body.
• On success the agent reads only the allowed fields and summarises them; it never pastes raw responses. On a "not found" or invalid input it tells the visitor to double-check; on any other error it offers a person.
• The visitor sees the normal typing indicator while this happens, then a plain reply.

Safety rules

• HTTPS only, no credentials in the URL, and the host may not change through placeholders.
• Private and internal addresses are blocked, both by name and by resolving the host over DNS-over-HTTPS before each call.
• Redirects are not followed. Requests time out after 10 seconds. Responses over 2 MB are rejected and at most 4,000 characters reach the agent.
• Inputs with a known format (template actions carry these) are checked before any request is made.
• Execution is at-least-once: a rare retry can run a write twice. Do not connect refunds or payments.

Limits

Up to 20 actions per workspace, integrations included. Test runs are limited to 30 per minute.

Common errors