Skip to main content
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 só reage ao engajamento que um usuário direciona a você (um comentário, resposta a story, DM ou reação) — ele nunca envia DMs acionadas por follow, DMs de primeira mensagem a estranhos ou 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.
sent significa que a Meta aceitou a mensagem, não que o destinatário a recebeu. A entrega é, em última instância, ditada pela configuração Message requests do Instagram do destinatário: se ele não permite solicitações de mensagem de qualquer pessoa, a Meta retorna uma resposta de sucesso e descarta silenciosamente a mensagem, e isso é invisível em toda camada de API. Mesmo uma DM entregue, acionada por comentário, chega como uma solicitação de mensagem que o destinatário precisa aceitar (a menos que já exista uma conversa entre as duas contas). Consulte Automation DM Sent but Not Delivered para a explicação completa.

​
Como funciona

1

Criar uma automação

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

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

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

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

​
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

​
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:
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.
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:

​
Limites de taxa e caps

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[]: pending e in_flight são transitórios; todos os outros são terminais. Quando uma automação tem mais de uma action, o status de nível superior é derivado dos resultados por action nesta ordem: auth_error se qualquer action teve erro de autenticação, depois sent se qualquer action foi aceita, depois deduplicated se todas as actions foram deduplicadas, depois skipped se todas as actions foram deliberadamente suprimidas (skipped ou deduplicated), caso contrário failed. Leia actionResults[] para o detalhe por action.
sent é um recibo de aceitação pela plataforma, não um recibo de entrega. O Instagram não expõe a entrega de mensagens em nenhuma API. Uma action send_dm é marcada como sent no momento em que o Instagram aceita a mensagem; se o destinatário realmente a recebe depende da configuração Message requests do Instagram dele, que a Ayrshare não consegue ler nem influenciar. Consulte Automation DM Sent but Not Delivered.

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

​
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 tenha se engajado primeiro (comentário, resposta, DM, reação) antes que uma conta business possa mandar mensagem. Todo trigger suportado é ancorado a esse engajamento — mas note que estar autorizado a enviar não é o mesmo que a mensagem ser entregue: a configuração Message requests do Instagram do destinatário ainda pode fazer com que a Meta aceite e depois descarte silenciosamente a mensagem (consulte Automation DM Sent but Not Delivered).
  • 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

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 se engajou primeiro. Cada trigger suportado (comment_keyword, story_reply, dm_reaction, dm_keyword) é ancorado a esse engajamento, o que é o que torna o envio permitido.
sent significa que o Instagram aceitou a mensagem, não que ela foi entregue. A entrega depende da configuração Message requests do Instagram do destinatário — se ele não permite solicitações de mensagem de qualquer pessoa, a Meta retorna uma resposta de sucesso e descarta silenciosamente a mensagem, sem erro, webhook ou qualquer outro sinal em nenhuma superfície de API. Uma DM acionada por comentário bem-sucedida também chega como uma solicitação de mensagem que o destinatário precisa aceitar (a menos que já exista uma conversa). Essa é uma limitação permanente da plataforma Instagram. Consulte Automation DM Sent but Not Delivered.
Se as credenciais do Instagram ou as permissões de mensagens da conta genuinamente falharem — por exemplo, um access token expirado ou revogado, uma seleção ausente de Facebook Page, ou Messaging não ativado para o perfil — a linha de activity registra o status auth_error e a DM não é reenviada. Resolver o estado da conta (revincular, selecionar uma Page ou ativar Messaging) permite que o próximo engajamento correspondente dispare normalmente. Isso só se aplica a falhas genuínas de credenciais e permissões: se uma DM específica não pôde ser entregue por outro motivo — por exemplo, o destinatário não pôde ser encontrado, ou o engajamento que a disparou veio da conta que enviaria a DM — a linha é registrada como failed ou skipped com o motivo em actionResults[].errorDetails, e revincular não mudará o resultado.
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 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.)
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