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

> Execute um funcionário de IA a partir de uma instrução escrita com suas palavras

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

Descreva o que você quer que aconteça **com suas palavras** e deixe o funcionário de IA decidir
como. Em vez de montar um array de ações tipadas, você envia uma conversa, um funcionário e uma
instrução:

```json theme={null}
{
  "conversation": { "uuid": "9f3c1a4e-…", "channel": "ch_7A9K2M4Q" },
  "ai_employee": { "name": "Agente de Vendas" },
  "instructions": "Verifique se o orçamento ficou pendente; se sim, envie-o e marque o acompanhamento."
}
```

O funcionário lê o histórico da conversa, interpreta sua instrução e executa os action sets
que ele tem atribuídos.

## Quando usar este endpoint e quando usar o grupo de ações

<CardGroup cols={2}>
  <Card title="Use /conversation/actions" icon="list-check">
    Quando você já sabe exatamente o que deve acontecer. É mais barato, mais rápido e mais
    previsível: executa as ações que você nomeia, na ordem em que as nomeia.
  </Card>

  <Card title="Use Smart Actions" icon="wand-magic-sparkles">
    Quando você quer descrever a intenção e deixar o funcionário avaliar o caso — sobretudo se a
    decisão depender do que diz o histórico da conversa.
  </Card>
</CardGroup>

A instrução é **obrigatória** e admite até 4000 caracteres: espaço para regras de negócio de
verdade, não para um comando.

## O mais importante: a instrução direciona, não amplia

<Warning>
  O funcionário executa **os action sets que ele tem atribuídos**, e nada mais. Sua instrução
  escolhe entre o que ele já sabe fazer; não lhe acrescenta capacidades.

  Se você pedir algo para o qual não existe um action set, a execução **responde e não executa
  nada, sem devolver erro**. Você não verá um `4xx`: verá uma conversa onde não aconteceu o que
  você esperava.
</Warning>

Antes de integrar, peça ao negócio a lista de action sets que o funcionário tem atribuídos —
o que ele sabe fazer vem dali e do prompt dele, não da sua instrução. Se
você precisa que algo concreto aconteça de forma garantida — aplicar uma etiqueta, mover de
caixa, mudar o status — use [`/conversation/actions`](/pt/action-groups/overview), que executa
exatamente o que você pede.

## Somente funcionários `operative`

Um funcionário `json` devolve `AI_EMPLOYEE_NOT_FOUND` (404). Descubra os disponíveis com
`GET /ai-employees`, que informa o `type` de cada um.

Para executar um funcionário `json`, use `/conversation/actions` com a ação `run_ai` ou
`ai_assistance`.

## Como escrever a instrução

O funcionário não consegue adivinhar os nomes das suas etiquetas, caixas ou modelos:
**nomeie-os explicitamente**. Descubra-os com `GET /tags`, `GET /mailbox-categories`,
`GET /quick-replies` e `GET /templates/{name}/{language}`.

<CodeGroup>
  ```text Funciona theme={null}
  Verifique se o cliente perguntou sobre a entrega e ainda não respondemos.
  Se sim, responda com as informações de entrega e etiquete como "Acompanhamento".
  ```

  ```text Não funciona theme={null}
  Faça o que for necessário.
  ```
</CodeGroup>

O limite de 4000 é medido em **unidades UTF-16**. Se você cortar o texto para respeitá-lo, não o
corte no meio de um emoji: um caractere partido devolve `400 INVALID_REQUEST`.

## A resposta

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

<Note>
  O `202` confirma **aceitação, não resultado**. Uma execução com raciocínio pode levar minutos,
  por isso roda em segundo plano.

  **O detalhe do que aconteceu ainda não é notificado** — chegará por webhook (funcionalidade
  futura), assim como em `/conversation/actions`. Enquanto isso, o que foi executado aparece no
  Registro de Atividade do painel do negócio.
</Note>

## A janela de 24h é verificada antes de executar

<Warning>
  Se a [janela de 24h](/pt/conversations) estiver fechada, este endpoint responde
  `422 WINDOW_CLOSED` e **não executa o funcionário**: nenhum token gasto, nenhuma mensagem enviada,
  nenhuma mudança na conversa. O corte é síncrono e prévio, mas a chamada aconteceu: consome uma
  requisição do seu [rate limit](/pt/rate-limits) e fica no Registro de Atividade do painel como uma
  tentativa rejeitada, com seu código.

  Isso **inclui os action sets cujo envio tem um template configurado**, que com a janela fechada
  sairiam por conta própria: no preflight não dá para saber o que o funcionário vai decidir, então o
  guard bloqueia esses também. O Smart Actions não serve para reabrir uma janela fechada.

  É deliberado. O mais comum que este endpoint faz é enviar uma mensagem ao cliente, e com a janela
  fechada a Meta rejeita. Sem essa verificação você receberia um `202`, a mensagem ficaria marcada
  como falha no chat e a conversa escalaria para pendente — tudo sem nenhum sinal chegar até você.

  **Para reabrir uma janela fechada**, envie primeiro um [template](/pt/templates) com
  [`/conversation/actions`](/pt/action-groups/overview). Quando o cliente responder, a janela abre de
  novo e o Smart Actions fica disponível.

  Para saber de antemão, consulte `POST /conversation/status`: devolve `window.status` (`open` ou
  `closed`) e `window.expires_at`.
</Warning>

## Uma chamada duplicada é executada duas vezes

<Warning>
  Este endpoint **não deduplica**. Não aceita `Idempotency-Key`, e o `202` não é promessa de
  execução única.

  * Mantenha **uma única requisição em andamento por conversa**.
  * **Não repita às cegas um `5xx`** deste endpoint, ao contrário do que sugere a tabela geral de
    [erros](/pt/errors): a nova tentativa executa de novo e pode enviar outra mensagem ao cliente.
  * A execução pode **se sobrepor à resposta automática** disparada por uma mensagem recebida do
    cliente.
</Warning>

## Erros

| Código                   | Status | Quando                                                                                                                |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------- |
| `INVALID_REQUEST`        | 400    | Falta `instructions`, ou excede 4000, ou traz um caractere que não conseguimos armazenar (um emoji partido ao cortar) |
| `CONVERSATION_NOT_FOUND` | 404    | A conversa não existe ou foi excluída                                                                                 |
| `CHANNEL_NOT_FOUND`      | 404    | A chave de `channel` não corresponde a um canal ativo                                                                 |
| `AI_EMPLOYEE_NOT_FOUND`  | 404    | Não existe funcionário **`operative`** ativo com esse nome                                                            |
| `AMBIGUOUS_AI_EMPLOYEE`  | 409    | O nome resolve para mais de um funcionário. Desambigue com `uuid`                                                     |
| `PHONE_NUMBER_AMBIGUOUS` | 409    | O telefone corresponde a mais de um contato nesse canal                                                               |
| `WALLET_BLOCKED`         | 402    | A wallet de tokens do modelo do funcionário está vazia ou bloqueada. Recarregue para continuar                        |
| `VISION_WALLET_BLOCKED`  | 402    | A wallet de vision tokens está vazia. O processamento de visão exige recarga                                          |
| `VISION_BLOCKED`         | 402    | O thread está bloqueado por visão, ou sua mídia recebida ficou sem transcrição depois que a visão terminou            |
| `WINDOW_CLOSED`          | 422    | A janela de 24h está fechada. Envie um template com `/conversation/actions` para reabri-la                            |
| `ACTIONS_DEPTH_EXCEEDED` | 422    | Os action sets do funcionário encadeiam além do limite                                                                |

O catálogo completo está em [erros](/pt/errors).