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

# Visão geral da Automations API

> Automações do Instagram acionadas por engajamento — dispare uma DM, webhook ou e-mail quando um usuário final comentar, responder a um story, reagir a uma DM ou enviar uma DM

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

<PlansAvailable plans={["business", "enterprise"]} maxPackRequired={false} />

<Note>
  **Beta.** A Automations API está em beta e estamos ativamente coletando feedback. Endpoints, payloads e limites podem mudar conforme iteramos. Envie feedback e relatórios de bugs para o suporte para que possamos priorizar as melhorias certas.
</Note>

Os endpoints de Automations permitem definir regras que reagem automaticamente ao engajamento recebido no Instagram. Cada automação combina um ou mais **triggers** (o evento que dispara a regra) com uma ou mais **actions** (o que acontece quando ela é disparada). Uma única regra pode escutar múltiplos triggers e despachar múltiplas actions — disparar um webhook para seu pipeline de análises E enviar uma DM a partir do mesmo engajamento.

O mecanismo é executado inteiramente dentro do envelope de políticas da Meta (sem DMs acionadas por follow, sem primeira mensagem a estranhos, sem envios em massa) e herda os limites de taxa por conta do Ayrshare, a desduplicação por destinatário e a ingestão idempotente de webhooks.

## Como funciona

<Steps>
  <Step title="Criar uma automação">
    `POST /automations` com os triggers e actions desejados. A automação é ativada imediatamente.
  </Step>

  <Step title="Um usuário final se engaja">
    Alguém comenta na sua publicação, responde ao seu story, envia uma DM ou reage a uma DM. A Meta entrega o webhook ao Ayrshare.
  </Step>

  <Step title="Ayrshare faz match e despacha">
    O mecanismo procura todas as regras que correspondem ao evento, verifica a desduplicação por action e seu limite diário de DMs e, em seguida, executa cada action. Um jitter de 20–60 segundos é aplicado aos envios de DM para permanecer dentro das heurísticas antispam do Instagram.
  </Step>

  <Step title="Inspecionar o que foi disparado">
    `GET /automations/:id/activity` retorna o log de auditoria — cada tentativa de despacho, os resultados por action e quaisquer erros.
  </Step>
</Steps>

## Triggers

Você pode anexar até **50 triggers** a uma única automação. Cada trigger é uma union discriminada pelo campo `type`; os campos específicos do tipo ficam no mesmo nível. Todos os triggers são exclusivos do Instagram na v1.

| Tipo              | Dispara quando                                                                       | Config                                                       |
| ----------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `comment_keyword` | Um comentário que corresponde a uma palavra-chave chega em uma publicação específica | `postId` (obrigatório); `keywords` (obrigatório, ≥1 entrada) |
| `story_reply`     | Um usuário responde a um story via DM                                                | `storyId` (opcional)                                         |
| `dm_reaction`     | Um usuário reage a uma das suas DMs com um emoji                                     | `emoji` (opcional — omita para disparar em qualquer emoji)   |
| `dm_keyword`      | Um usuário envia uma DM cujo texto corresponde a uma palavra-chave                   | `keywords` (obrigatório, ≥1 entrada)                         |

A correspondência de palavras-chave **não diferencia maiúsculas de minúsculas** e é por palavra inteira. Um evento satisfaz um trigger filtrado por palavras-chave se contiver qualquer uma das palavras-chave configuradas. Omita `storyId` em um trigger de story para disparar em todos os stories da conta conectada.

## Actions

Você pode anexar até **50 actions** a uma única automação. Elas são executadas sequencialmente; cada resultado é registrado na linha de activity.

| Tipo           | Efeito                                                                                                                                     | Config                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `send_dm`      | Envia uma DM do Instagram para o usuário que disparou a regra, usando uma [mensagem com template](#template-variables).                    | `message` (obrigatório, com template)                                                                 |
| `fire_webhook` | Faz POST do contexto da automação para a URL de webhook em nível de conta (configure via [`POST /hook/webhook`](/apis/webhooks/register)). | *(nenhuma — o formato do payload é fixo; veja [abaixo](#fire_webhook-payload))*                       |
| `send_email`   | Coloca um e-mail na fila via o pipeline de e-mail da plataforma.                                                                           | `to` (obrigatório, e-mail); `subject` (opcional, com template); `message` (obrigatório, com template) |

### Janela de dedup por action

Toda action — independentemente do tipo — aceita adicionalmente um campo opcional de nível superior `dedupWindowMinutes` que substitui a janela de dedup por destinatário **padrão de 7 dias** apenas para aquela action.

* Defina como `0` para **desabilitar** o dedup inteiramente para essa action (típico para `fire_webhook` / `send_email`, onde o receptor espera todos os eventos).
* Limitado a `525600` (um ano).

```json Action with a 24h dedup override theme={"system"}
{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}
```

### Payload do `fire_webhook`

Quando `fire_webhook` é executado, ele faz POST de um corpo JSON para sua URL de webhook em nível de conta:

```json theme={"system"}
{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "timestamp":         "2026-05-12T09:14:22.000Z"
}
```

`recipientUsername` e `keyword` são `null` quando o trigger não os preenche (por exemplo, `dm_keyword` não carrega um username no payload da Meta; `story_reply` não tem uma palavra-chave).

## Variáveis de template

`send_dm.message`, `send_email.subject` e `send_email.message` suportam substituição via `{{placeholder}}`. **Placeholders desconhecidos são rejeitados no momento de criação/atualização** (como erro de validação `473`), para que um erro de digitação nunca vaze silenciosamente o literal `{{foo}}` em uma mensagem voltada ao cliente.

| Placeholder              | Resolve para                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `{{recipient_username}}` | O @ do Instagram do usuário engajador (quando o webhook o carrega)                  |
| `{{recipient_id}}`       | O ID de participante do Instagram (IGSID) do usuário engajador                      |
| `{{recipient_name}}`     | Reservado; resolve para vazio até que uma fonte futura de enriquecimento o preencha |
| `{{sender_username}}`    | Seu username do Instagram vinculado                                                 |
| `{{sender_name}}`        | Seu nome de exibição do Instagram vinculado                                         |
| `{{comment_text}}`       | O texto do comentário / DM / resposta de story que disparou o trigger               |
| `{{comment_id}}`         | O ID da plataforma do comentário / mensagem que disparou                            |
| `{{comment_sent_at}}`    | Timestamp ISO 8601 do evento (quando disponível)                                    |
| `{{matched_keyword}}`    | A palavra-chave que correspondeu (ou a string do emoji para `dm_reaction`)          |
| `{{platform}}`           | Identificador da plataforma (por exemplo, `instagram`)                              |
| `{{trigger_type}}`       | Tipo de trigger (por exemplo, `comment_keyword`)                                    |

<Note>
  **Sem `sender_email` / `recipient_email`.** Estes não são expostos deliberadamente — seu e-mail de cobrança não tem lugar legítimo em uma DM para um estranho, e a Meta não fornece o e-mail do destinatário em nenhum webhook do IG. Evitar esses placeholders previne divulgação acidental.
</Note>

Exemplo de template:

```
Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com
```

## Limites de taxa e caps

| Plano      | Automações ativas (por perfil) | Cap diário de DMs (por conta) |
| ---------- | ------------------------------ | ----------------------------- |
| Business   | 10                             | 1.000                         |
| Enterprise | 50                             | 5.000                         |

O cap de automações ativas é contado **por [User Profile](/apis/profiles/overview)**, não por conta pai. Cada perfil da sua conta recebe seu próprio Business 10 / Enterprise 50, então uma conta com muitos perfis pode rodar essa quantidade de automações em cada um. Ele conta automações ativas e é aplicado tanto em `POST` (criar) quanto em reativações via `PUT` (`active: false → true`), cada um retornando o código de erro `470`. Precisa de um limite maior por perfil? [Entre em contato com o suporte](mailto:support@ayrshare.com) para aumentá-lo em sua conta.

O **cap diário de DMs** se aplica por conta pai do Ayrshare, compartilhado entre todos os seus perfis, com um subcap por perfil para que um perfil movimentado não consuma toda a cota da conta. Quando um cap de DM é atingido, a linha de activity registra o status `rate_limited` e nenhuma DM é enviada.

Caps estruturais em uma única automação: **1–50 triggers**, **1–50 actions**.

O próprio Instagram limita DMs a aproximadamente 200/hora por conta. O mecanismo faz o pacing do despacho com um jitter de 20–60 segundos para ficar seguramente abaixo desse limite.

## Status de activity

Uma linha em `GET /automations/:id/activity` carrega um `status` de nível superior mais um `status` por action dentro de `actionResults[]`:

| Status         | Significado                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| `pending`      | Recém-gravado; o worker ainda não o pegou                                         |
| `in_flight`    | O worker está despachando no momento                                              |
| `sent`         | Todas as actions foram bem-sucedidas                                              |
| `failed`       | Pelo menos uma action falhou (e nenhuma teve erro de autenticação)                |
| `auth_error`   | O access token do Instagram era inválido; a DM não foi reenviada                  |
| `rate_limited` | O cap diário de DMs (por tier ou por perfil) foi atingido; nenhuma DM foi enviada |
| `deduplicated` | Esta action já foi disparada para este destinatário dentro da sua janela de dedup |
| `skipped`      | A automação ficou inativa ou foi excluída entre o fan-out e o despacho            |

`pending` e `in_flight` são transitórios; todos os outros são terminais.

## Códigos de erro

A API retorna dois formatos de erro:

* **Erros de regra de negócio** carregam um `code` de automação numerado (por exemplo, `{ "action": "automation", "code": 469, ... }`).
* **Erros de validação** — qualquer corpo de requisição malformado (campos ausentes ou inválidos, variáveis de template desconhecidas, chaves não reconhecidas) — são retornados como uma única resposta **`473`** com um objeto `details` que lista os campos problemáticos. `details` é a saída do validador (`formErrors` mais `fieldErrors`). Faça branching por `details`, não por um code por condição. Em `fieldErrors`, as chaves são os campos de nível superior da requisição (`triggers`, `actions`): um problema dentro de uma entrada específica, como um trigger sem seus `keywords`, é reportado sob esse campo (por exemplo, `triggers`), enquanto `formErrors` guarda problemas em nível de objeto, como chaves não reconhecidas.

| Code | HTTP | Significado                                                                    |
| ---- | ---- | ------------------------------------------------------------------------------ |
| 468  | 403  | Requer plano Business ou Enterprise                                            |
| 469  | 404  | Automação não encontrada (também retornado quando o chamador não é dono)       |
| 470  | 429  | Cap de automações ativas atingido para o seu tier de plano                     |
| 471  | 400  | Nenhuma conta social vinculada na plataforma solicitada para este perfil       |
| 472  | 403  | Recurso ainda não disponível na sua conta — contate-nos para acesso antecipado |
| 473  | 400  | Falha de validação (corpo de requisição malformado) — inspecione `details`     |

## O que a Meta NÃO permite

Algumas capacidades comumente solicitadas não são suportadas porque a Meta não as permite na API pública do Instagram:

* **Auto-DM para novos seguidores.** O Instagram não publica um webhook de follow.
* **DMs de primeira mensagem para estranhos.** A Meta exige que o destinatário inicie o contato (comentário, resposta, DM, reação) antes que uma conta business possa mandar mensagem — o que é exatamente o que cada trigger suportado aqui representa.
* **Campanhas de outbound em massa.** Caps de DM por hora e heurísticas anti-abuso se aplicam no nível da plataforma.

## Uso multi-perfil

Os endpoints respeitam o cabeçalho `profileKey`. Passe a chave de um perfil filho e a automação é criada/gerenciada sob esse perfil. Os limites de taxa são divididos entre perfis via um subcap por perfil, para que um perfil tagarela não drene a cota da conta pai.

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Posso disparar em um novo seguidor?">
    Não. O Instagram não publica um webhook de follow, e a Meta não permite que apps de terceiros enviem uma DM para um usuário que não iniciou uma conversa. Cada trigger suportado (`comment_keyword`, `story_reply`, `dm_reaction`, `dm_keyword`) satisfaz o requisito de "o usuário te contatou primeiro".
  </Accordion>

  <Accordion title="O que acontece se meu access token for inválido quando uma automação disparar?">
    A linha de activity registra o status `auth_error` e a DM não é reenviada. Revincule a conta e o próximo engajamento correspondente disparará normalmente.
  </Accordion>

  <Accordion title="Por que há um atraso antes da DM ser enviada?">
    Cada despacho de `send_dm` é agendado 20–60 segundos após o engajamento para parecer orgânico aos sistemas antispam do Instagram. Actions `fire_webhook` e `send_email` NÃO têm jitter. O timestamp `created` da linha de activity é quando o trigger correspondeu; `completedAt` é quando o despacho terminou.
  </Accordion>

  <Accordion title="As linhas de activity são mantidas para sempre?">
    As linhas de activity são retidas indefinidamente para trace e análises. O endpoint `GET /automations/:id/activity` retorna linhas dos últimos 30 dias por questões de desempenho. (A guarda de dedup usa sua própria janela por action — padrão de 7 dias — que não está relacionada ao lookback de activity.)
  </Accordion>

  <Accordion title="Excluir uma automação remove seu histórico de activity?">
    Não. Delete é soft-delete: a linha mestre é marcada como `deleted`, nenhum novo despacho ocorre, mas as linhas de activity históricas permanecem legíveis via o endpoint de activity.
  </Accordion>
</AccordionGroup>

## Endpoints

* [`POST /automations`](/apis/automations/create-automation) — criar uma nova automação
* [`GET /automations`](/apis/automations/list-automations) — listar suas automações
* [`GET /automations/:id`](/apis/automations/get-automation) — obter uma automação com seus triggers e actions
* [`PUT /automations/:id`](/apis/automations/update-automation) — atualização parcial; pause via `active: false`
* [`DELETE /automations/:id`](/apis/automations/delete-automation) — soft-delete
* [`GET /automations/:id/activity`](/apis/automations/get-activity) — log de auditoria de despachos paginado por cursor