Actions

GET /v1/actions/types lists the six types and whether this deployment can create each one. The settings each type takes in config are described on POST /v1/actions.

The one you will use most: the bot calls your endpoint and uses the answer.

parameters declares what the model may pass. A {{name}} placeholder in the URL's path or query, a header value or body_template takes that argument; the scheme and host never change. The token goes in credentials, not in config.headers: credentials are stored encrypted and never returned, while config comes back on every read.

A dry run: it shows what the action would do without doing it. Send arguments to check the config and templating; send a visitor message to ask the model whether it would call the action at all, and with what.

Nothing is sent: no request reaches your endpoint or MCP server, no email goes out, no run is recorded and no event fires. request_summary shows the method and host a live run would call.

Every time the model calls an action in a conversation, a run is recorded.

status is success, failed, timed_out, pending (a handoff or notify email still queued) or confirmation_pending (a high-risk call waiting for the visitor to confirm). A confirmed call is recorded as a new run, and an unconfirmed request becomes skipped after two hours. The arguments and request details of a run are shown in the dashboard, not on /v1. Runs across a whole bot are at GET /v1/chatbots/{id}/action_runs, including those of deleted actions (action_id: null).

Get told instead of asking

Actions are the point where the product reaches into your systems, so "did my tool run, and did it work" is the question you cannot answer any other way.

A call to a high-risk action runs only after the visitor confirms it in a later message. Set is_high_risk to require that; an http_request with POST, PUT, PATCH or DELETE, and an mcp action without config.low_risk, always require it.

The handoff action flags a conversation for a human and emails the addresses in its targets. When it fires, the conversation gets handoff_requested: true and a handoff_reason, and conversation.handoff.requested is emitted once.

Wire that event to wherever your team actually looks. A handoff nobody sees is worse than no handoff, because the visitor has been told someone is coming.

If you already expose tools over MCP, point at the server and discover them rather than transcribing definitions by hand:

It fetches the server's tool list so you can register one mcp action per tool you want. It answers 404 MCP_NOT_ENABLED where the platform has MCP switched off. A token you send is used for that request only; store it in the action's credentials.token.

Actions can hold credentials for your own systems:

• credentials are write-only. They are stored encrypted and never returned; has_credentials tells you whether any are set. A PATCH merges the keys you send, and an empty value removes one.
• config is returned in full on every read, so keep secrets out of it — including config.headers.
• A run records a classified error code (timeout, upstream_error, …), never your endpoint's raw error text, so a failing upstream cannot leak a token into run history.

Use a dedicated, narrowly-scoped credential for each action, and rotate it on your side, then send the new value with PATCH /v1/actions/{id}.

• A vague description. The commonest reason an action "never fires".
• A slow endpoint. The platform gives up after 8 seconds by default, and until then the visitor waits. Return quickly, even if that means returning "still working".
• Assuming it ran. Check the run status, or subscribe to the events.
• A token in config.headers. It is returned on every read; use credentials.

• Events — the action events and everything else.
• Conversations — see actions in context.
• Security — credential handling.