---
title: "Criar automação"
method: POST
path: "/v1/automations"
tags: ["Automações"]
---

# Criar automação

`POST /v1/automations`

## Request

- Base URL: `https://api.ararahq.com`
- URL: `https://api.ararahq.com/v1/automations`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ararahq/apis/ararahq-api/docs/v1/automations/post.ts> (a function with typed inputs; its response is checked against the schema)

A automação nasce sempre desligada (`active: false`). Criar não conta no
teto de automações ativas do plano; ligar conta. Ligue com
`PUT /v1/automations/{id}/active`.

Com `Idempotency-Key`, repetir a chamada devolve a automação já criada.

Permissão: `AUTOMATIONS_MANAGE`. Essa permissão é opcional na chave:
chaves antigas não têm.

## Headers

- `Idempotency-Key` string

## Request body

- AutomationUpsertRequest
  - `name` string, required: Nome interno da automação.
  - `trigger` 'webhook' | 'cart.abandoned' | 'payment.failed' | 'tag.applied' | 'conversation.started' | 'button.replied' | 'charge.paid' | 'charge.expired', required: Gatilho que coloca um contato na automação. `webhook` é o link próprio da automação; `cart.abandoned` e `payment.failed` vêm da recuperação de receita; os demais são eventos internos da Arara.
  - `triggerConfig` object, nullable: Só `button.replied` exige: `{ "replyId": "...", "templateName"?: "..." }`. Os demais gatilhos ignoram o campo.
  - `steps` AutomationStep[]: Passos, na ordem de execução. A lista inteira é reescrita a cada `POST` ou `PUT`.
    - `type` 'message' | 'wait' | 'condition' | 'tag' | 'question' | 'wait_payment', required: - `message`: envia um template (`templateId`, `variables` e, opcionalmente, `charge`) ou um texto na janela de 24h (`sessionText`, até 1.024 caracteres). Nunca os dois. - `wait`: `{ "minutes": N }`, de 1 a 43.200 (30 dias). - `condition`: `{ "tag": "..." }`. Segue só se o contato ainda não tem a etiqueta. - `tag`: `{ "tag": "..." }`. Aplica a etiqueta no contato. - `question`: pergunta com opções; ramifica em `branches`. - `wait_payment`: `{ "timeoutMinutes": N, "referenceId"?: "..." }`; ramifica em `paid` e `unpaid`.
    - `config` object, nullable: Configuração do passo. O formato depende de `type`.
    - `branches` object, nullable: Só em `question` e `wait_payment`. Chave do ramo para a lista de passos daquele ramo. Em `question`: o `id` de cada opção, mais `__timeout` e `__other`. Em `wait_payment`: `paid` e `unpaid`.
    - `id` string, uuid, nullable: ID do passo na resposta. Muda a cada `PUT`.

## Response `201`

Automação criada

- Automation
  - `id` string, uuid, required
  - `name` string, required
  - `trigger` string, required
  - `triggerConfig` object, nullable
  - `active` boolean, required: `false` na criação. Mude em `PUT /v1/automations/{id}/active`.
  - `steps` AutomationStep[], required
    - `type` 'message' | 'wait' | 'condition' | 'tag' | 'question' | 'wait_payment', required: - `message`: envia um template (`templateId`, `variables` e, opcionalmente, `charge`) ou um texto na janela de 24h (`sessionText`, até 1.024 caracteres). Nunca os dois. - `wait`: `{ "minutes": N }`, de 1 a 43.200 (30 dias). - `condition`: `{ "tag": "..." }`. Segue só se o contato ainda não tem a etiqueta. - `tag`: `{ "tag": "..." }`. Aplica a etiqueta no contato. - `question`: pergunta com opções; ramifica em `branches`. - `wait_payment`: `{ "timeoutMinutes": N, "referenceId"?: "..." }`; ramifica em `paid` e `unpaid`.
    - `config` object, nullable: Configuração do passo. O formato depende de `type`.
    - `branches` object, nullable: Só em `question` e `wait_payment`. Chave do ramo para a lista de passos daquele ramo. Em `question`: o `id` de cada opção, mais `__timeout` e `__other`. Em `wait_payment`: `paid` e `unpaid`.
    - `id` string, uuid, nullable: ID do passo na resposta. Muda a cada `PUT`.
  - `costPerRunBrl` number, required: Custo estimado, em reais, de cada pessoa que entrar na automação.
  - `stats` object, nullable
    - `runsLast30Days` integer
    - `inFlight` integer
    - `completed` integer
    - `stopped` integer
  - `webhookUrl` string, nullable: URL que o seu sistema precisa chamar, quando o gatilho depende disso.
  - `hook` AutomationHook
    - `url` string, required: Link próprio da automação (`https://api.ararahq.com/hooks/a/ara_hook_...`).
    - `signatureEnabled` boolean, required
    - `hasSecret` boolean, required: Diz só se o segredo existe. O valor nunca volta em leitura.

## Other responses

- `400`: `AUTOMATION_TRIGGER_INVALID` (gatilho inexistente), `AUTOMATION_TRIGGER_CONFIG_INVALID` (`button.replied` sem `replyId`), `AUTOMATION_STEP_INVALID` (passo com `type` ou `config` inválido) ou `INVALID_JSON`.
- `401`: Chave inexistente, revogada, expirada, com prefixo errado (`ara_` sem `ara_live_`) ou vinda de IP fora da allowlist. O corpo é o JSON padrão do Spring, sem `error.code`.
- `403`: Dois casos, com corpos diferentes: - Autenticação: header `Authorization` ausente, Bearer que não começa com `ara_`, chave sem a permissão da rota ou rota que não aceita chave de API. Corpo no formato padrão do Spring, sem `error.code`. - Regra de negócio, no formato `{ "error": { ... } }`: `PLAN_FEATURE_LOCKED`, `PLAN_LIMIT_REACHED`, `ACCOUNT_NOT_ACTIVATED`, `NO_DEDICATED_NUMBER`, `ORGANIZATION_SUSPENDED`, `NUMBER_BLOCKED`, `FRAUD_SUSPECTED`, `RESOURCE_FORBIDDEN`, `VIEWER_READ_ONLY`.
- `429`: `RATE_LIMIT_EXCEEDED`: limite geral da API (1.200 leituras ou 3.000 escritas por minuto, por usuário da chave).

## Changes

- **2026-10-12** `d576cd28afc0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ararahq/apis/ararahq-api/changes/v1/automations/post.md)

---

[API](https://skmtc.dev/ararahq/apis/ararahq-api.md) - [All operations](https://skmtc.dev/ararahq/apis/ararahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ararahq/apis/ararahq-api/revisions/d576cd28afc0?raw)