> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Place an action

> Place a BotShield Action in the Console or with the Gates API: its act key, the name and reason your customer reads, who may send it, and high-value actions.

You place a [BotShield Action](https://docs.botshield.ai/actions/overview.md) once, under a short **act key** such as `trade`. An action is live as soon as it is placed. You can rename it, change who may send it, and turn it off and on at any time. Actions are placed per environment: a Development action and a Production action are separate, even when they share a key.

## In the Console

In the [BotShield Console](https://console.botshield.ai), select **Verified Accounts** in the sidebar, open the **BotShield Actions** tab and select **Place an action**. The list shows the actions placed in the environment selected in the header, with their state, where they live and when they were placed. **All**, **Live** and **Off** filter the list.

| Field | What to enter |
| - | - |
| **Name** | What your customer reads as the title of the confirmation, for example "Confirm trade". Up to 60 characters. |
| **Act key** | The key your act strings start with, for example `trade`. Lower-case letters, digits, `_` and `-`, up to 40 characters. The Console suggests one from the name. |
| **Where it lives** (optional) | An `https://` link to the page where the act happens. |
| **Staff can send** | Your support team can send this action to a customer from the Console. See [Staff can send](#staff-can-send). |
| **High-value · Only from a signed-in customer** | The action is asked for only from your server, with your own reference for the customer. See [High-value actions](#high-value-actions). |

Select **Place action**. In Production, placing an action is confirmed with your Developer passkey.

**Edit** on a row changes the action's name, the reason your customer reads, and who can send it. In the Console, in Production, a change that widens the action is confirmed with your Developer passkey (through the Gates API, the key's Gates API access stands in for it): a new name or reason, turning on **Staff can send**, or turning off **High-value**. Tightening it, for example turning **Staff can send** off, asks for no passkey. To stop an action, select **Turn off** on its row. Turning off takes effect at once and never asks for a passkey. **Turn on** in Production is confirmed with your Developer passkey. Only organization admins place, change and turn actions on or off.

### The name and the reason

Your customer reads one line for the action: its **reason** when you set one, otherwise its **name**. The reason is set in the Console's **Edit** dialog, under **The reason your customer reads**: up to 90 characters, with no links. Clear it and your customer reads the name again.

A request can replace that line for one ask: `act_label` on [a tap on your page](https://docs.botshield.ai/actions/overview.md#the-label) or on [an ask through an agent](https://docs.botshield.ai/actions/ask-through-an-agent.md).

## With the Gates API

Use an API key with **Gates API access**. See [Gates API](https://docs.botshield.ai/gate/gates-api.md#authentication). The environment comes from the key.

```bash curl theme={null}
curl -s https://api.botshield.ai/operations/gates-api/actions/create \
  -H "Authorization: Bearer $BOTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Confirm trade","actKey":"trade","whereUrl":"https://tickets.example.com/trades"}'
```

```json theme={null}
{
  "data": {
    "data": {
      "action": {
        "id": "6b0d2f4e-8a51-4c3e-9f7a-2d1c5e8b9a04",
        "name": "Confirm trade",
        "reason": null,
        "act_key": "trade",
        "where_url": "https://tickets.example.com/trades",
        "state": "live",
        "environment": "production",
        "placed_at": "2026-11-03T18:42:10.204Z",
        "turned_off_at": null,
        "staff_can_send": false,
        "high_value": false,
        "kind": "action",
        "signin_qr": false,
        "pending_where_url": null,
        "pending_where_url_at": null
      }
    }
  }
}
```

| Operation | Request | Response |
| - | - | - |
| `POST /gates-api/actions/create` | `name` (1–60 characters), `actKey` (lower-case letters, digits, `_`, `-`, up to 40), `whereUrl` (optional, `https://`), `staffCanSend` (optional), `highValue` (optional) | `{ action }` |
| `GET /gates-api/actions/list` | none | `{ actions: [...] }`, newest first, in the key's environment, live and off |
| `POST /gates-api/actions/update` | `actKey`, and at least one of `name`, `staffCanSend`, `highValue` | `{ action }` |
| `POST /gates-api/actions/set-state` | `actKey`, `state` (`live` or `off`) | `{ action }` |

An act key is unique within one environment. The reason your customer reads is set in the Console only; the API returns it as `reason`.

Turning an action off takes effect at once and is safe to repeat:

```bash curl theme={null}
curl -s https://api.botshield.ai/operations/gates-api/actions/set-state \
  -H "Authorization: Bearer $BOTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actKey":"trade","state":"off"}'
```

Mark an existing action high-value:

```bash curl theme={null}
curl -s https://api.botshield.ai/operations/gates-api/actions/update \
  -H "Authorization: Bearer $BOTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actKey":"trade","highValue":true}'
```

### The action object

| Field | Description |
| - | - |
| `id` | BotShield's id for the action. |
| `name` | What your customer reads when no reason is set. |
| `reason` | The line your customer reads, set in the Console, or `null`. |
| `act_key` | The key your act strings start with. |
| `where_url` | Where the action lives, or `null`. |
| `state` | `live` or `off`. |
| `environment` | `development` or `production`, from the key. |
| `placed_at`, `turned_off_at` | When it was placed, and when it was last turned off (`null` while live). |
| `staff_can_send` | Your support team can send it. |
| `high_value` | It is asked for only from your server, with your own reference for the customer. |
| `kind` | `action` for every action you place here. Your Recovery Action and your Sign-on Action, if you have them, are listed with `recovery` and `signin`. Those two are placed and changed in the Console only, and no act string, ask or staff send reaches them. |
| `signin_qr`, `pending_where_url`, `pending_where_url_at` | Used by the Sign-on and Recovery Actions only. `false` and `null` on every other action. |

## Staff can send

An action marked **Staff can send** (`staffCanSend: true`) is one your support team may send to a customer from the Console. Its reason, or its name when no reason is set, is what the customer reads, so write it as a plain statement about them, for example "You asked us to change your account details."

While they are not placed, the **BotShield Actions** tab offers **Add the three starter reasons**: three staff-sendable actions for account details, a support call and account recovery, which you can rename or turn off like any other.

A high-value action is never sent by staff, whatever this setting says.

## High-value actions

Mark an action **high-value** (`highValue: true`) when it should start only while your customer is signed in with you: a payout, a change of the account's email, closing the account. A high-value action is asked for only by your server naming the customer by your own reference:

| Way to ask | High-value action |
| - | - |
| A tap on your page, or `create-verification-link` with `partner_user_ref` | Allowed |
| [Ask through an agent](https://docs.botshield.ai/actions/ask-through-an-agent.md) with `partner_user_ref` | Allowed |
| [Ask by phone number](https://docs.botshield.ai/actions/ask-by-phone-number.md) | Refused with `action_requires_signed_in` |
| A staff send from the Console | Refused |

The refusal depends only on the action, so it comes back before anything about the number is looked up.

## Error codes

Errors arrive as `data.error` with HTTP `200`. The Gates API action operations also return `invalid_key`, `gates_scope_required`, `org_not_found` and `internal` as described in [Gates API](https://docs.botshield.ai/gate/gates-api.md#error-codes).

| `code` | `statusCode` | Operation | Cause |
| - | - | - | - |
| `action_key_taken` | 409 | `create` | An action with this key is already placed in this environment. |
| `action_not_found` | 404 | `update`, `set-state` | No action with this key is placed in the key's environment. |
| `nothing_to_change` | 400 | `update` | Send `name`, `staffCanSend` or `highValue`. |
| `action_console_only` | 409 | `update`, `set-state` | The key names your Recovery Action or Sign-on Action, which are changed in the Console only. |

An `actKey` that breaks the pattern, a `name` longer than 60 characters or a `whereUrl` that is not `https://` fails input validation with HTTP `400` before the operation runs.

## Next steps

> [card] [BotShield Actions](https://docs.botshield.ai/actions/overview.md)
>
> The act string, binding the terms, and a tap on your page.

> [card] [Ask through an agent](https://docs.botshield.ai/actions/ask-through-an-agent.md)
>
> Put an action in front of a BotShield Verified customer from your server.

> [card] [Ask by phone number](https://docs.botshield.ai/actions/ask-by-phone-number.md)
>
> Reach a customer by the number they gave you.

> [card] [Gates API](https://docs.botshield.ai/gate/gates-api.md)
>
> Authentication and the shared error codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.