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

# Smart Actions

> Run an AI employee from an instruction written in your own words

<Info>
  **Endpoint** · `POST /conversation/smart-actions`
</Info>

Describe what you want to happen **in your own words** and let the AI employee decide how.
Instead of assembling an array of typed actions, you send a conversation, an employee and an
instruction:

```json theme={null}
{
  "conversation": { "uuid": "9f3c1a4e-…", "channel": "ch_7A9K2M4Q" },
  "ai_employee": { "name": "Sales Agent" },
  "instructions": "Check whether the quote is still pending; if so, send it and mark the follow-up."
}
```

The employee reads the conversation history, interprets your instruction and runs the action
sets it has assigned.

## When to use this endpoint and when to use action groups

<CardGroup cols={2}>
  <Card title="Use /conversation/actions" icon="list-check">
    When you already know exactly what should happen. It's cheaper, faster and more
    predictable: it runs the actions you name, in the order you name them.
  </Card>

  <Card title="Use Smart Actions" icon="wand-magic-sparkles">
    When you want to describe the intent and let the employee judge the case — especially when
    the decision depends on what the conversation history says.
  </Card>
</CardGroup>

The instruction is **required** and allows up to 4000 characters: room for real business
rules, not for a command.

## The key point: the instruction directs, it doesn't extend

<Warning>
  The employee runs **the action sets it has assigned**, and nothing else. Your
  instruction picks among what it already knows how to do; it doesn't grant new capabilities.

  If you ask for something with no matching action set, the run **replies and executes nothing,
  without returning an error**. You won't see a `4xx`: you'll see a conversation where what you
  expected didn't happen.
</Warning>

Before integrating, ask the business for the list of action sets the employee has assigned —
what it knows how to do comes from there and from its prompt, not from your instruction.
If you need something specific and guaranteed — apply a label, move to a mailbox, change the
status — use [`/conversation/actions`](/en/action-groups/overview), which runs exactly what you
ask for.

## `operative` employees only

A `json` employee returns `AI_EMPLOYEE_NOT_FOUND` (404). Discover the available ones with
`GET /ai-employees`, which reports each one's `type`.

To run a `json` employee, use `/conversation/actions` with the `run_ai` or `ai_assistance`
action.

## How to write the instruction

The employee can't guess the names of your labels, mailboxes or templates: **name them
explicitly**. Discover them with `GET /tags`, `GET /mailbox-categories`, `GET /quick-replies`
and `GET /templates/{name}/{language}`.

<CodeGroup>
  ```text Works theme={null}
  Check whether the customer asked about shipping and we haven't replied yet.
  If so, reply with the shipping details and label them "Follow-up".
  ```

  ```text Doesn't work theme={null}
  Do whatever is appropriate.
  ```
</CodeGroup>

The 4000 limit is measured in **UTF-16 units**. If you trim the text to fit, don't cut through
an emoji: a split character returns `400 INVALID_REQUEST`.

## The response

```json theme={null}
{
  "conversation": { "uuid": "9f3c1a4e-…" },
  "ai_employee": { "uuid": "4d81b0…", "name": "Sales Agent" },
  "status": "processing"
}
```

<Note>
  The `202` confirms **acceptance, not a result**. A run with reasoning can take minutes, so it
  runs in the background.

  **The detail of what happened isn't reported yet** — it will arrive via webhook (upcoming
  feature), same as in `/conversation/actions`. In the meantime, what ran is visible in the
  business panel's Activity Log.
</Note>

## The 24h window is checked before running

<Warning>
  If the [24h window](/en/conversations) is closed, this endpoint returns `422 WINDOW_CLOSED` and
  **doesn't run the employee**: no tokens spent, no message sent, no change to the conversation. The
  check is synchronous and up front, but the call still happened: it consumes one request of your
  [rate limit](/en/rate-limits) and is recorded in the panel's Activity Log as a rejected attempt,
  with its code.

  This **includes action sets whose send has a template configured**, which would go out on their own
  with the window closed: at preflight there's no way to know what the employee will decide, so the
  guard blocks them too. Smart Actions is not the way to reopen a closed window.

  This is deliberate. The most common thing this endpoint does is send the customer a message, and
  with the window closed Meta rejects it. Without this guard you'd get a `202`, the message would be
  marked as failed in the chat and the conversation would escalate to pending — all without any
  signal reaching you.

  **To reopen a closed window**, send a [template](/en/templates) first with
  [`/conversation/actions`](/en/action-groups/overview). Once the customer replies the window opens
  again and Smart Actions becomes available.

  To know beforehand, call `POST /conversation/status`: it returns `window.status` (`open` or
  `closed`) and `window.expires_at`.
</Warning>

## A duplicate call runs twice

<Warning>
  This endpoint **does not deduplicate**. It doesn't accept `Idempotency-Key`, and the `202` is
  not a promise of single execution.

  * Keep **one request in flight per conversation**.
  * **Don't blindly retry a `5xx`** from this endpoint, unlike what the general
    [errors](/en/errors) table suggests: the retry runs again and may send the customer another
    message.
  * The run can **overlap with the automatic reply** triggered by an inbound customer message.
</Warning>

## Errors

| Code                     | Status | When                                                                                                           |
| ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------- |
| `INVALID_REQUEST`        | 400    | `instructions` is missing, exceeds 4000, or carries a character we can't store (an emoji split while trimming) |
| `CONVERSATION_NOT_FOUND` | 404    | The conversation doesn't exist or was deleted                                                                  |
| `CHANNEL_NOT_FOUND`      | 404    | The `channel` key doesn't match an active channel                                                              |
| `AI_EMPLOYEE_NOT_FOUND`  | 404    | No active **`operative`** employee with that name                                                              |
| `AMBIGUOUS_AI_EMPLOYEE`  | 409    | The name resolves to more than one employee. Disambiguate with `uuid`                                          |
| `PHONE_NUMBER_AMBIGUOUS` | 409    | The phone matches more than one contact on that channel                                                        |
| `WALLET_BLOCKED`         | 402    | The token wallet for the employee's model is empty or blocked. Top up to continue                              |
| `VISION_WALLET_BLOCKED`  | 402    | The vision token wallet is empty. Vision processing needs a top-up                                             |
| `VISION_BLOCKED`         | 402    | The thread is blocked by vision, or its inbound media was left untranscribed after vision finished             |
| `WINDOW_CLOSED`          | 422    | The 24h window is closed. Send a template with `/conversation/actions` to reopen it                            |
| `ACTIONS_DEPTH_EXCEEDED` | 422    | The employee's action sets chain beyond the limit                                                              |

The full catalog is in [errors](/en/errors).