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

# Assign and unassign AI employee

> Assigns or removes the conversation's AI employee

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

Two actions manage which AI employee handles the conversation:
`assign_ai_employee` **assigns** it (optionally running it) and `unassign_ai`
**removes** it (the conversation hands off to a human).

## `assign_ai_employee`

Assigns an AI employee to the conversation. With `run: true`, it also runs it
immediately (only then does it count as an AI-triggering action).

**Fields**

* `ai_employee` — `{ name }` of the AI employee (required).
* `run` — boolean (optional, default `false`). With `true` it runs the employee
  immediately after assigning it.
* `instructions` — optional text with specific instructions for that run. Only
  applies with `run: true`.
* `scheduled_message_action` — `reassign` | `cancel`. What to do with the
  conversation's active scheduled message. Send `cancel` by default (see the warning).

<Warning>
  **Active schedule when reassigning.** If the conversation is handled by an AI
  employee that left a pending **scheduled message** and you reassign it to
  **another** AI employee, the API requires you to decide what happens to that
  schedule: without `scheduled_message_action` the action fails with
  `SCHEDULED_MESSAGE_ACTION_REQUIRED`.

  * `cancel` — cancels the scheduled message; the new AI employee starts without it.
  * `reassign` — keeps the schedule and repoints it to the new AI employee.

  Since the API doesn't expose whether a conversation has an active schedule, the
  robust approach is to **always send `"scheduled_message_action": "cancel"`**: it's
  valid on any assignment and does nothing when there's no schedule to cancel. Use
  `reassign` only when you reassign from one AI employee to another and want to keep
  the schedule — sending it in any other case fails with
  `SCHEDULED_MESSAGE_ACTION_INVALID`.
</Warning>

```jsonc theme={null}
// Assign — `cancel` is the safe value for any assignment
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": false,
  "scheduled_message_action": "cancel"
}
```

```jsonc theme={null}
// Reassign from one AI employee to ANOTHER, keeping its scheduled message
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Soporte" },
  "scheduled_message_action": "reassign"
}
```

```jsonc theme={null}
// Assign and run immediately
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": true,
  "instructions": "Greet and confirm the delivery time.",
  "scheduled_message_action": "cancel"
}
```

## `unassign_ai`

Removes the AI employee (the conversation hands off to a human). No fields;
idempotent (a successful no-op if the conversation already has no AI). Cancels
the AI's active scheduled message, if any.

```jsonc theme={null}
{
  "type": "unassign_ai"
}
```

In a list, these objects go in the `actions` array of a `POST /conversation/actions` — see [Assembling an action list](/en/action-groups/overview#assembling-an-action-list).

## Executable example

Two actions manage the AI employee of a conversation identified by phone and
channel: `assign_ai_employee` assigns it (with `run: true` it also runs it) and
`unassign_ai` removes it. Send `scheduled_message_action: cancel` by default; use
`reassign` only when reassigning from one AI employee to another while keeping its
scheduled message.

### Request

<CodeGroup>
  ```bash Assign theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+5215512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "assign_ai_employee",
          "ai_employee": { "name": "Agente Ventas" },
          "run": false,
          "scheduled_message_action": "cancel"
        }
      ]
    }'
  ```

  ```bash Reassign theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+5215512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "assign_ai_employee",
          "ai_employee": { "name": "Agente Soporte" },
          "scheduled_message_action": "reassign"
        }
      ]
    }'
  ```

  ```bash Assign and run theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+5215512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "assign_ai_employee",
          "ai_employee": { "name": "Agente Ventas" },
          "run": true,
          "instructions": "Greet and confirm the delivery time.",
          "scheduled_message_action": "cancel"
        }
      ]
    }'
  ```

  ```bash Unassign theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+5215512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "unassign_ai"
        }
      ]
    }'
  ```
</CodeGroup>

### Response

`202 Accepted` — the group was accepted and runs in the **background**. The
per-action result does not travel in the response (query it later — see [How it runs](/en/action-groups/overview#how-it-runs)).

```json theme={null}
{
  "status": "processing",
  "actions_accepted": 1
}
```

<ResponseField name="status" type="string">
  Always `processing`: confirms the group was accepted and is running.
</ResponseField>

<ResponseField name="actions_accepted" type="integer">
  How many actions in the array were **admitted** for execution — not how many
  succeeded.
</ResponseField>