Visão geral da Automations API - Ayrshare API Documentation

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.

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

Criar uma automação

POST /automations com os triggers e actions desejados. A automação é ativada imediatamente.

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.

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.

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.

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.	`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`).	(nenhuma — o formato do payload é fixo; veja abaixo)
`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).

Action with a 24h dedup override

{
  "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:

{
  "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`)

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.

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

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

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.

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.

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

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.

Endpoints

POST /automations — criar uma nova automação
GET /automations — listar suas automações
GET /automations/:id — obter uma automação com seus triggers e actions
PUT /automations/:id — atualização parcial; pause via active: false
DELETE /automations/:id — soft-delete
GET /automations/:id/activity — log de auditoria de despachos paginado por cursor

​Como funciona

​Triggers

​Actions

​Janela de dedup por action

​Payload do fire_webhook

​Variáveis de template

​Limites de taxa e caps

​Status de activity

​Códigos de erro

​O que a Meta NÃO permite

​Uso multi-perfil

​Perguntas frequentes

​Endpoints

Como funciona

Triggers

Actions

Janela de dedup por action

Payload do `fire_webhook`

Variáveis de template

Limites de taxa e caps

Status de activity

Códigos de erro

O que a Meta NÃO permite

Uso multi-perfil

Perguntas frequentes

Endpoints