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.
sent significa que a Meta aceitou a mensagem, não que o destinatário a recebeu. No Instagram, a entrega é, em última instância, ditada pela configuração Message requests 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
Um jitter de 20–60 segundos é aplicado ao engajamento para permanecer dentro das heurísticas antispam do Instagram. Em seguida, o mecanismo procura todas as regras que correspondem ao evento, verifica a desduplicação por action e seu limite diário de DMs e executa cada action.
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 campotype; os campos específicos do tipo ficam no mesmo nível. A coluna Plataformas mostra onde cada trigger está disponível; consulte Páginas do Facebook para saber o que o Facebook exige.
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.
Regras perenes com "all"
Defina postId (ou storyId) como a string literal em minúsculas "all" para disparar em toda publicação, reel ou story da conta conectada, em vez de em uma peça de conteúdo específica. É isso que você quer para uma regra que deve continuar funcionando conforme novos conteúdos são publicados, sem uma chamada de API por publicação:
"all". Uma variante como "ALL" ou " all" é rejeitada com um erro de validação em vez de ser salva como um ID de publicação que nunca corresponderia.
"all" nunca se estende além da conta conectada — uma regra em um perfil não pode disparar no conteúdo de outro perfil. Seu cap diário de DMs e as regras de envio ancoradas em engajamento se aplicam exatamente como em uma regra de publicação única.
Nos triggers de story, omitir
storyId se comporta da mesma forma que "all". Prefira "all" — ele declara a intenção explicitamente, e a omissão será aposentada em uma versão futura, com aviso antecipado em Upcoming API Changes.Páginas do Facebook
Definaplatform como facebook para executar uma automação na Página do Facebook vinculada ao perfil. As DMs são enviadas pela Página através do Messenger.
- Triggers:
dm_keywordedm_reaction. Os triggers de comentário e de story são exclusivos do Instagram por enquanto, e uma automação do Facebook que use um deles é rejeitada com um erro de validação. - Messaging: o perfil precisa ter o Messaging ativado para o Facebook, da mesma forma que para enviar uma DM do Facebook com a Messages API.
- Destinatário:
{{recipient_id}}é o ID do usuário com escopo da Página (PSID).{{recipient_username}}fica vazio, porque os webhooks do Messenger não incluem um nome de usuário.
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 superiordedupWindowMinutes que substitui a janela de dedup por destinatário padrão de 7 dias apenas para aquela action.
- Defina como
0para desabilitar o dedup inteiramente para essa action (típico parafire_webhook/send_email, onde o receptor espera todos os eventos). - Limitado a
525600(um ano).
Action with a 24h dedup override
Conteúdo dinâmico da mensagem
Por padrão,send_dm envia a mesma message para todos que disparam a regra. Placeholders como {{recipient_username}} são a única parte que muda de pessoa para pessoa. Defina messageUrl na action e o seu próprio servidor passa a escrever a DM para cada pessoa: toda vez que a regra corresponde, perguntamos ao seu endpoint o que dizer e enviamos a resposta dele como a DM.
Exemplo. Sua regra responde a qualquer pessoa que comente “LINK” em uma publicação, e messageUrl aponta para o seu servidor. Quando Ava comenta “LINK please!”:
- Fazemos
POSTdos detalhes para a suamessageUrl: quem comentou ("recipientUsername": "ava"), o que escreveu e em qual publicação. - Seu servidor escreve uma resposta para Ava, por exemplo com um link de rastreamento criado só para ela, e responde
{ "message": "Hi ava, here's your link: https://example.com/r/12345" }. - Enviamos esse texto para Ava como a DM, exatamente como você escreveu.
timeoutMs, retornar um erro ou retornar algo que não conseguimos usar, enviamos a Ava a message regular da action, para que ela ainda receba uma resposta.
Adicione-o a uma action send_dm assim:
send_dm with messageUrl
messageUrl é onde pedimos o texto. message continua obrigatório e é o fallback: ele nunca é enviado ao seu servidor, e o enviamos como DM sempre que o seu servidor não responde a tempo, retorna um erro ou retorna algo que não conseguimos usar (veja o aviso abaixo). timeoutMs é opcional (padrão 3000, máximo 5000).
O que enviamos ao seu endpoint. Um POST com este corpo JSON:
Callback request body
Se você registrou um segredo de webhook, o corpo é assinado com o mesmo segredo dos seus webhooks de
automations, da mesma forma: X-Authorization-Content-SHA256 é o HMAC-SHA256 do corpo bruto, e X-Authorization-Timestamp traz o timeStamp do corpo. O código de verificação que você já usa para os nossos webhooks funciona sem alterações. Se um segredo estiver registrado, mas não conseguirmos lê-lo naquele momento, não enviamos o callback sem assinatura; em vez disso, enviamos o seu template de message.
Para onde pode apontar. messageUrl deve ser um endereço HTTPS público. Uma URL que resolve para um endereço privado, de loopback, link-local ou de metadados de nuvem é recusada, e redirecionamentos não são seguidos — uma resposta 3xx conta como falha. Em ambos os casos, o template é enviado no lugar.
O que o seu endpoint retorna. Retorne 200 com um corpo JSON, de no máximo 16 KB, contendo uma string message de 1 a 1000 caracteres:
{{placeholder}} não é aplicada a ele, então um {{ literal no seu texto gerado chega ao destinatário exatamente como foi escrito.
timeoutMs tem como padrão 3000. O máximo é 5000: um valor maior é rejeitado com um erro de validação quando você cria ou atualiza a automação. Ele cobre toda a troca, incluindo a leitura do corpo da sua resposta. Planeje-se para isso: a DM é enviada depois que o seu endpoint responde, então um endpoint lento atrasa a mensagem.
Verifique qual caminho um disparo seguiu em GET /automations/:id/activity. Uma entrada send_dm em actionResults[] traz messageSource assim que o texto da DM é definido, inclusive quando o envio falha depois. Ele fica ausente quando a action parou antes disso, por exemplo uma DM skipped para a sua própria conta ou uma action deduplicated:
messageSource diz a partir de qual texto a DM foi construída, não se ela foi entregue. Para isso, leia o status da entrada.
Um fallback por si só não faz a action falhar: quando a DM do template é entregue, a entrada fica sent, com o motivo pelo qual o callback não foi usado em errorDetails. Se a DM do template também falhar, a entrada fica failed e errorDetails traz o erro de envio seguido do motivo do callback. Fique atento a isso: caso contrário, um callback que falha em todo disparo parece exatamente igual a um que está funcionando.
Mantenha a sua message enviável por conta própria. Se ela renderizar vazia para um destinatário, por exemplo {{recipient_username}} sozinho em um trigger de DM que não traz nome de usuário, e o texto do seu callback não for usado, nenhuma DM é enviada e a action fica failed, com o motivo em errorDetails.
Eventos de webhook
Dois eventos são entregues à ação de webhookautomations que você registra com POST /hook/webhook. Ambos carregam um campo type — faça o desvio por ele antes de ler qualquer outra coisa.
automation.completed está desligado por padrão. Ative-o para uma automação definindo "sendCompletedEvent": true na action fire_webhook dela. Caso contrário, ele permanece desligado, então um receptor construído para um payload por disparo continua recebendo exatamente um. automation.triggered não é um registro de cada correspondência: ele é enviado apenas quando o próprio fire_webhook é executado, então uma correspondência que termina em rate_limited ou deduplicated produz apenas automation.completed. Nenhum dos eventos é enviado para uma automação que foi desativada ou excluída antes de o despacho ser executado.automation.triggered
activityId é a linha que GET /automations/:id/activity retorna, para que você possa juntar as duas exatamente em vez de fazer correspondência por recipientId + triggerId + keyword — o que é ambíguo quando várias pessoas comentam a mesma palavra-chave ao mesmo tempo. actionId é a action fire_webhook que enviou o evento e corresponde a actionResults[].actionId; ele distingue duas actions fire_webhook na mesma regra.
Os campos que um trigger não preenche são null em vez de omitidos, então o formato é estável. recipientUsername é null para dm_keyword, dm_reaction e story_reply, porque o payload da Meta não inclui um. commentId é definido apenas para comment_keyword e story_comment, postId apenas para comment_keyword, e storyId apenas para os triggers de story. story_reply não tem keyword. Para dm_keyword, commentText é o texto da DM; para dm_reaction, commentText e keyword são ambos o emoji da reação.
automation.completed
Enviado apenas quando a automação opta por ele na sua action fire_webhook:
fire_webhook action with the outcome event on
status e cada actionResults[].status usam os mesmos valores do log de activity — sent, failed, rate_limited, deduplicated, skipped, auth_error — então, no caso normal, você fica sabendo como um despacho terminou sem fazer polling. A entrega deste evento, porém, é best-effort: se o processo parar entre registrar o resultado e enfileirar o evento, ele não é enviado. O log de activity é o registro de verdade, então, se você precisa de todos os resultados, reconcilie com GET /automations/:id/activity para qualquer activityId que não tenha reportado um. Um resultado de send_dm também traz messageSource, como no log de activity: template, callback ou fallback, para que você possa identificar uma messageUrl que continua caindo no fallback sem fazer polling. Associe os resultados às suas actions configuradas por actionId, não por posição — duas actions do mesmo tipo só são distinguíveis dessa forma. actionResults fica vazio em três casos, cada um com o motivo no errorDetails de nível superior quando houver um: rate_limited (seu cap diário foi atingido), deduplicated (todas as actions estavam dentro da sua janela de dedup) e failed depois que o despacho foi repetido o número máximo de vezes sem terminar. Nesse último caso, algumas actions podem já ter sido executadas, então uma DM pode ter sido enviada e automation.triggered pode já ter sido enviado.
A entrega de webhook é at-least-once, então o mesmo evento pode ocasionalmente chegar duas vezes, e um despacho que é repetido pode enviar automation.triggered novamente com um novo hookId. Nunca desduplique por hookId. Use uma chave separada para cada tipo de evento, para que processar um nunca suprima o outro: automation.completed por activityId (cada activity tem um resultado) e automation.triggered por activityId mais actionId (um por action fire_webhook). Os dois eventos são entregues de forma independente, então automation.completed pode ocasionalmente chegar antes de automation.triggered.
Se nenhum webhook estiver registrado
fire_webhook faz POST para a ação automations registrada no perfil, com fallback para o seu Primary Profile. Não há fallback para outra ação, como messages. Se nenhum dos dois registros existir, automation.triggered não é descartado silenciosamente: a action é registrada na linha de activity como failed, com o motivo em actionResults[].errorDetails. (automation.completed também não tem para onde ir, e não é registrado.) O status geral do despacho então segue a precedência habitual: auth_error se qualquer action teve erro de autenticação, caso contrário sent se qualquer action foi aceita, caso contrário failed. Portanto, o webhook ausente conta para as estatísticas de falha da automação apenas quando nada mais na regra enviou; quando outra action de fato enviou (e nenhuma teve erro de autenticação), o despacho termina em sent e o webhook com falha aparece apenas em actionResults[].
Um resultado sent de fire_webhook significa que o evento foi enfileirado para entrega à sua URL, não que seu endpoint o aceitou. A entrega é então repetida em seu próprio cronograma.
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.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 Launch/Business 10 ou 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.
O limite de conversas de mensagens também se aplica. send_dm precisa do add-on Messaging no perfil, e cada DM que ela envia conta para o limite de conversas mensal desse perfil, da mesma forma que uma DM que você mesmo envia. Quando o limite é atingido, um send_dm para um novo destinatário não é enviado e a linha de activity registra o status failed, com a mensagem do limite em actionResults[].errorDetails. DMs disparadas por um comentário (comment_keyword e story_comment) são a exceção: elas ainda são enviadas no limite, e ainda são contadas.
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 emGET /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. Uma action send_dm é marcada como sent no momento em que a Meta aceita a mensagem, seja ela enviada da sua conta do Instagram ou pelo Messenger a partir da sua Página do Facebook. A automação registra apenas essa aceitação; ela não acompanha a entrega. O Instagram não expõe a entrega de mensagens em nenhuma API, e 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
codede 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
473com um objetodetailsque lista os campos problemáticos.detailsé a saída do validador (formErrorsmaisfieldErrors). Faça branching pordetails, não por um code por condição. EmfieldErrors, 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 seuskeywords, é reportado sob esse campo (por exemplo,triggers), enquantoformErrorsguarda problemas em nível de objeto, como chaves não reconhecidas.
Os planos Launch estão incluídos. O Business Launch é resolvido para o tier Business, então as
automações estão disponíveis nos planos Launch, Business e Enterprise.
468 só é retornado para
planos que não incluem automações.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çalhoprofileKey. 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?
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 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.Por que uma activity diz sent mas o destinatário nunca recebeu a DM?
Por que uma activity diz sent mas o destinatário nunca recebeu a DM?
sent significa que a Meta aceitou a mensagem, não que ela foi entregue. Isso vale no Instagram e no Facebook (Messenger a partir da sua Página): a automação registra apenas a aceitação e não acompanha a entrega. No Instagram, 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.O que acontece se meu access token for inválido quando uma automação disparar?
O que acontece se meu access token for inválido quando uma automação disparar?
Se as credenciais do Instagram ou da Página do Facebook, 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.Por que há um atraso antes da DM ser enviada?
Por que há um atraso antes da DM ser enviada?
Cada despacho é agendado 20–60 segundos após o engajamento para que os envios de DM pareçam orgânicos aos sistemas antispam do Instagram. O atraso é aplicado ao engajamento antes de qualquer regra ser avaliada, então vale para todas as actions da regra, incluindo
fire_webhook e send_email — seu webhook chega 20–60 segundos após o comentário, não imediatamente. 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 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?
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çãoGET /automations— listar suas automaçõesGET /automations/:id— obter uma automação com seus triggers e actionsPUT /automations/:id— atualização parcial; pause viaactive: falseDELETE /automations/:id— soft-deleteGET /automations/:id/activity— log de auditoria de despachos paginado por cursor