Rest API

Create or update a procedure

POST

/api/v1/ai/actions

Create a new procedure, or update an existing one by passing its actionId. The body is the whole procedure, not a patch: fields you leave out are not preserved, so fetch the procedure first and send it back with your changes applied.

Use cases

Automation: Give the AI an API call it can make on the visitor’s behalf
Account setup: Provision the standard procedures for a new workspace
Maintenance: Enable, disable or retarget an existing procedure by passing its actionId

Notes

Send arguments. It is the command’s input and is required, and for command: api it must be the procedure’s own actionId, because the AI dispatches the procedure as /api <arguments>
Generate the actionId yourself when creating a procedure, so arguments can carry the same value in the same request. The API generates one when you omit it, which is too late for arguments to reference
accountId and websiteId are taken from the auth headers; anything you send in the body for them is overwritten
Nothing in the body is validated on write. A procedure missing a field is stored and returns 200, then fails the first time the AI runs it, so read it back with the get procedures endpoint instead of trusting the status code
A value the schema rejects is the worst case: a variable type of number is stored happily and then makes the get procedures endpoint answer 502 for every procedure in the workspace. Stick to the documented enums
Set smartAction explicitly. It decides whether the AI fills the variables from the conversation or the visitor is asked for each one, and it is stored as sent
body is a string containing JSON, not a nested object
Credentials belong in headers as a {{placeholder}} resolved from the visitor’s secure profile. A value declared in variables ends up in the chat data, which is stored with the conversation and sent to the model
Deleting a procedure is not available with an API key, only from the dashboard

Parameters

Header Parameters

x-api-key

required

string

Your API key from account settings.

x-user-email

required

string

The email address of your user.

x-account-id

required

string

The ID of your account. You can find this in the account settings.

x-website-id

required

string

The ID of the workspace you want to use.

Request Body^required

The procedure to store. Common fields are described by the Procedure schema; the properties below are the ones an api procedure adds.

object

accountId

string

websiteId

string

actionId

Unique identifier for this procedure.

string

name

Display name, also what the AI refers to when it decides to run the procedure.

string

description

What the procedure does. The AI reads this when deciding whether it applies.

string

nullable

command

What the procedure executes. api calls an HTTP endpoint, mcp invokes an MCP tool, direct-answer supplies a fixed answer, and the rest drive the component. Each command reads its input from arguments.

string

Allowed values: api mcp direct-answer rephrase-and-answer redirect-to-url start-experience start-live-chat execute-custom-javascript switch-segment send-message-to-segment send-message-to-segment-and-switch resend-message-to-segment-and-switch open-image open-video

arguments

The command’s input. What it has to contain depends on command, and a procedure whose arguments is wrong is stored happily but fails when the AI tries to run it. For api and rephrase-and-answer it must be the procedure’s own actionId. For mcp it is the MCP tool ID, for direct-answer the answer text, for redirect-to-url the URL, for start-experience the component ID, for execute-custom-javascript the code, for the segment commands the topic (and message), and for open-image and open-video the media URL. Only start-live-chat takes no input.

string

nullable

enabled

Whether the procedure is live. Procedures saved before this field existed are treated as enabled and backfilled on read.

boolean

nullable

smartAction

When true the AI fills the variables from the conversation. When false the visitor is asked for each one.

boolean

nullable

escalate

Whether running this procedure hands the conversation to a human.

boolean

guidance

Extra instructions for the AI on how to use this procedure.

string

nullable

variables

The values collected before the procedure runs, referenced as {{name}} in the request.

Array<object>

One value collected from the visitor or filled by the AI before the procedure runs.

object

name

Referenced as {{name}} in the endpoint, headers or body.

string

description

What the value is. Shown to the visitor, and what the AI matches against when filling it itself.

string

type

How the value is collected and validated. string is a single-line input, multiline a text area, email validates an address, regex validates against the regex field, and select offers the options as a dropdown. No other value is accepted: number, boolean, date and phone are reserved but not implemented, and storing one of them makes the get procedures endpoint fail for the whole workspace.

string

Allowed values: string multiline email regex select

optional

boolean

forceCollection

Ask the visitor even when the AI could infer the value.

boolean

regex

Pattern the collected value must match.

string

nullable

options

Fixed set of choices offered to the visitor.

Array<object>

nullable

object

label

string

value

string

dependsOnVariable

Only collect this variable when the named variable has dependsOnVariableValue.

string

nullable

dependsOnVariableValue

string

nullable

availability

string

nullable

Allowed values: ALWAYS DURING_OPENING_HOURS OUTSIDE_OPENING_HOURS

lifecycleStage

string

nullable

Allowed values: support newSales retention salesExpansion

enabledSegments

Restrict the procedure to these AI segments. Empty or absent means every segment.

Array<string>

nullable

enabledAudiences

Restrict the procedure to these audiences.

Array<string>

nullable

preCollectionMessage

Shown before the visitor is asked for the variables.

string

nullable

preExecuteMessage

Shown just before the procedure executes.

string

nullable

immediatelyExecute

boolean

nullable

triggerAfterResponse

boolean

triggerAfterUnanswered

Run the procedure when the AI could not answer the question.

boolean

triggerAfterTimeout

boolean

triggerAfterTimeoutTime

Seconds of inactivity before the timeout trigger fires.

number

skipTranslation

boolean

nullable

javascriptDisplayTrigger

JavaScript expression that must be truthy for the procedure to be offered.

string

nullable

documentsTriggeringAction

Training documents that reference this procedure, so you can see which knowledge triggers it. Read-only, and only returned by the list operation.

Array<object>

object

actionId

ID of the procedure. Pass the ID of an existing procedure to update it. To create one, generate a UUID yourself and send it here, so arguments can carry the same value in the same request. Omitting it makes the API generate an ID, which leaves an api procedure with no way to reference itself.

string

method

HTTP method of the call the procedure makes.

string

Allowed values: GET POST

endpoint

URL to call. Supports {{variable}} placeholders.

string

nullable

headers

Request headers. The only place a credential placeholder may appear.

object

key

additional properties

string

body

Request body as a string. For a JSON body this is JSON encoded as a string, not a nested object.

string

nullable

bodyType

string

Allowed values: json plain

bodySchema

Schema the dashboard uses to validate the body. Not enforced by the API.

object

transformer

JavaScript that reshapes the API response before the AI uses it.

string

nullable

onSuccessPostActions

What happens after a successful call.

Array<object>

One step run after the procedure succeeded or failed.

object

command

required

What the step does. display-message shows text in the chat, translated into the conversation language.

string

Allowed values: display-message call-query

Identifier for the step. Generated when omitted.

string

text

The text to show. Only for display-message.

string

query

The question to send back to the AI. Only for call-query.

string

promptLabel

Label shown for the follow-up query. Only for call-query.

string

systemPrompt

System prompt used for the follow-up query. Only for call-query.

string

onErrorPostActions

What happens after a failed call.

Array<object>

One step run after the procedure succeeded or failed.

object

command

required

What the step does. display-message shows text in the chat, translated into the conversation language.

string

Allowed values: display-message call-query

Identifier for the step. Generated when omitted.

string

text

The text to show. Only for display-message.

string

query

The question to send back to the AI. Only for call-query.

string

promptLabel

Label shown for the follow-up query. Only for call-query.

string

systemPrompt

System prompt used for the follow-up query. Only for call-query.

string

Example

{
  "actionId": "3f6c1b52-9a4e-4c8d-9f1a-2b7d5e0c4a13",
  "arguments": "3f6c1b52-9a4e-4c8d-9f1a-2b7d5e0c4a13",
  "name": "Look up order status",
  "description": "Retrieves the status of an order from the shop backend.",
  "command": "api",
  "enabled": true,
  "smartAction": true,
  "method": "GET",
  "endpoint": "https://api.example.com/orders/{{orderId}}",
  "headers": {
    "x-api-key": "{{shopApiKey}}"
  },
  "body": "{}",
  "bodyType": "json",
  "variables": [
    {
      "name": "orderId",
      "description": "The order number the visitor is asking about",
      "type": "string"
    }
  ],
  "onSuccessPostActions": [
    {
      "command": "display-message",
      "text": "Here is the status of your order."
    }
  ],
  "onErrorPostActions": []
}

Responses

200

The procedure was created or updated.

object

actionId

ID of the procedure that was written. Echoes the actionId you sent, or the generated one when you created a procedure.

string

message

string

Example

{
  "actionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message": "AI action upserted"
}

400

Bad request - missing body or websiteId.

401

Unauthorized - invalid API key.

Create or update a procedure

Parameters

Header Parameters

Request Body required

Example

Responses

200

Example

400

401

Request Body^required