> ## 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.

# Atribuir e desatribuir funcionário AI

> Atribui ou remove o funcionário AI da conversa

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

Duas ações gerenciam qual funcionário AI atende a conversa:
`assign_ai_employee` o **atribui** (opcionalmente o executa) e `unassign_ai` o
**remove** (a conversa passa para um humano).

## `assign_ai_employee`

Atribui um funcionário AI à conversa. Com `run: true`, além disso o executa de
imediato (só então conta como ação que dispara AI).

**Campos**

* `ai_employee` — `{ name }` do funcionário AI (obrigatório).
* `run` — booleano (opcional, padrão `false`). Com `true` executa o funcionário de
  imediato após atribuí-lo.
* `instructions` — texto opcional com instruções pontuais para essa execução.
  Só se aplica com `run: true`.
* `scheduled_message_action` — `reassign` | `cancel`. O que fazer com a mensagem
  agendada ativa da conversa. Envie `cancel` por padrão (veja o aviso).

<Warning>
  **Agendamento ativo ao reatribuir.** Se a conversa é atendida por um funcionário AI
  que deixou uma **mensagem agendada** pendente e você a reatribui para **outro**
  funcionário AI, a API exige que você decida o que acontece com esse agendamento:
  sem `scheduled_message_action` a ação falha com
  `SCHEDULED_MESSAGE_ACTION_REQUIRED`.

  * `cancel` — cancela a mensagem agendada; o novo funcionário AI começa sem ela.
  * `reassign` — mantém o agendamento e o reaponta para o novo funcionário AI.

  Como a API não expõe se uma conversa tem um agendamento ativo, o mais robusto é
  **enviar sempre `"scheduled_message_action": "cancel"`**: é válido em qualquer
  atribuição e não faz nada quando não há agendamento para cancelar. Use `reassign`
  apenas quando reatribui de um funcionário AI para outro e quer manter o
  agendamento — enviá-lo em qualquer outro caso falha com
  `SCHEDULED_MESSAGE_ACTION_INVALID`.
</Warning>

```jsonc theme={null}
// Atribuir — `cancel` é o valor seguro para qualquer atribuição
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": false,
  "scheduled_message_action": "cancel"
}
```

```jsonc theme={null}
// Reatribuir de um funcionário AI para OUTRO mantendo sua mensagem agendada
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Soporte" },
  "scheduled_message_action": "reassign"
}
```

```jsonc theme={null}
// Atribuir e executar de imediato
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": true,
  "instructions": "Cumprimente e confirme o horário de entrega.",
  "scheduled_message_action": "cancel"
}
```

## `unassign_ai`

Remove o funcionário AI (a conversa passa para um humano). Sem campos; idempotente
(no-op bem-sucedido se a conversa já não tiver AI). Cancela a mensagem agendada
ativa do AI, se houver.

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

Em uma lista, estes objetos vão no array `actions` de um `POST /conversation/actions` — veja [Montar uma lista de ações](/pt/action-groups/overview#montar-uma-lista-de-ações).

## Exemplo executável

Duas ações gerenciam o funcionário AI de uma conversa identificada por telefone e
canal: `assign_ai_employee` o atribui (com `run: true` também o executa) e
`unassign_ai` o remove. Envie `scheduled_message_action: cancel` por padrão; use
`reassign` apenas ao reatribuir de um funcionário AI para outro mantendo sua
mensagem agendada.

### Request

<CodeGroup>
  ```bash Atribuir theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_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 Reatribuir theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_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 Atribuir e executar theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_sua_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": "Cumprimente e confirme o horário de entrega.",
          "scheduled_message_action": "cancel"
        }
      ]
    }'
  ```

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

### Resposta

`202 Accepted` — o grupo foi aceito e roda em **background**. O resultado por
ação não viaja na resposta (consulte-o depois — veja [Como é executado](/pt/action-groups/overview#como-é-executado)).

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

<ResponseField name="status" type="string">
  Sempre `processing`: confirma que o grupo foi aceito e está em execução.
</ResponseField>

<ResponseField name="actions_accepted" type="integer">
  Quantas ações do array foram **admitidas** para execução — não quantas tiveram
  sucesso.
</ResponseField>