Automações

Comentário com palavra-chave num post → resposta privada no Direct de quem comentou, com resposta pública opcional.

Uma automação liga uma conta, um post (ou Reel) e uma lista de palavras-chave a um fluxo: uma sequência pequena de mensagens, perguntas com botões e coleta de dados, com resposta pública opcional no comentário.

Como funciona

Alguém comenta no post com uma das palavras-chave (comparação "contém", sem diferenciar maiúsculas nem acentos — eu quero casa com "EU QUERO!!!").
A Postmatic envia o primeiro nó do flow como resposta privada a comentário da Meta: uma por comentário, até 7 dias depois dele.
Se o primeiro nó espera resposta (question/capture) e a pessoa responde, a Postmatic acompanha a conversa pelo Direct e avança o fluxo — quick reply, texto digitado ou o dado capturado.
Sem resposta dentro do prazo do nó (timeoutMinutes), a Postmatic segue para onTimeout (se houver) ou encerra o fluxo (outcome: expired).
Cada pessoa entra uma vez por automação. Um comentário novo da mesma pessoa em outra automação da conta encerra o fluxo anterior (outcome: superseded) e começa o novo — a resposta mais recente sempre vale.

Fora desta versão: mensagens que não pertencem a nenhum fluxo em andamento são recebidas e descartadas na hora, nunca guardadas nem repassadas — a Postmatic ainda não tem inbox. Quick replies não aparecem no Instagram web: escreva o texto da pergunta enumerando as opções (ex.: "Responda Quero ou Agora não"), para quem estiver no desktop conseguir responder por texto.

Nós do fluxo

Três tipos, até 20 nós por fluxo:

message — envia texto e, opcionalmente, até 3 botões de link. Não espera resposta.
question — envia texto com até 13 opções (quick replies). Espera até timeoutMinutes; sem match, vai para onOther (ou repete a pergunta, até 2 vezes, se onOther for nulo — depois disso a run é abandonada).
capture — pede um dado (text, email, phone ou number), valida e grava em field; resposta inválida repete invalidText (até 2 vezes), depois vai para onInvalid (se houver) ou abandona a run.

Placeholders: {{username}} e {{data.<campo>}} (o valor de um capture — ou de uma question com field definido — anterior no caminho até este nó).

Janela de 24 horas

Depois da primeira DM, cada mensagem seguinte só pode ser enviada dentro de 24 horas da última resposta da pessoa — regra da Meta, não da Postmatic. Passado esse prazo, o fluxo encerra (outcome: expired) sem tentar enviar.

Permissão e assinatura

Um fluxo de uma única mensagem sem botão exige só instagram_business_manage_comments. Qualquer fluxo que espere resposta, ou que use botões, exige também instagram_business_manage_messages. A Postmatic assina os campos de webhook necessários na conta automaticamente ao criar ou alterar o fluxo; a assinatura só cresce — nunca é removida, mesmo trocando para um fluxo mais simples, porque outras automações da mesma conta podem depender dela.

Enquanto o App Review da Meta não aprovar o acesso avançado, só contas com papel no app da Postmatic (administrador, desenvolvedor ou testador) recebem webhooks — de comentários e de mensagens.

Diga à pessoa, na primeira mensagem, que está falando com um fluxo automático — é exigência da Meta.

Criar

POST /v1/automations

curl -X POST https://api.uat.postmatic.dev/v1/automations -H "x-access-key: pm_live_…" -H "content-type: application/json" -d '{
  "accountId": "int_…",
  "trigger": { "type": "comment", "mediaId": "17895695668004550" },
  "keywords": ["eu quero", "quero"],
  "flow": {
    "start": "oferta",
    "nodes": [
      { "id": "oferta", "type": "question", "text": "Oi {{username}}! Quer o link? Responda Quero ou Agora não.",
        "options": [ { "title": "Quero!", "next": "link" }, { "title": "Agora não", "next": "tchau" } ],
        "onOther": null, "timeoutMinutes": 10080, "onTimeout": null },
      { "id": "link", "type": "message", "text": "Aqui está:",
        "buttons": [ { "title": "Abrir", "url": "https://exemplo.com" } ], "next": null },
      { "id": "tchau", "type": "message", "text": "Sem problema 🙂", "next": null }
    ]
  },
  "commentReply": { "text": "Te mandei no direct 👆" }
}'

mediaId é o id da mídia na Meta: para um post publicado pela Postmatic, é o platformPostId do destino; para qualquer outro post da conta, o id que a Meta mostra. Só posts do feed e Reels são aceitos; stories e outros tipos de mídia não têm comentários.

O timeoutMinutes: 10080 do nó inicial (oferta) no exemplo só vale ali: qualquer outro nó do fluxo tem teto de 1380 minutos (23 horas) — reusar 10080 num nó depois do primeiro devolve 400 FLOW_INVALID.

Limites: 1 a 20 palavras-chave (até 100 caracteres cada); 1 a 20 nós; textos até 1000 bytes (640 para mensagem com botão); até 13 opções por pergunta (título até 20 caracteres cada); até 3 botões por mensagem; timeoutMinutes até 7 dias (10080 minutos) só no nó inicial, até 23 horas (1380 minutos) nos demais; até 5 automações ativas por post na mesma conta.

Consultar e editar

GET /v1/automations?accountId=&status= lista.
GET /v1/automations/:id traz counts (runs, active, completed, expired, abandoned, superseded, failed), lastRunAt e account.webhookSubscribedAt.
PATCH /v1/automations/:id altera keywords, flow, commentReply e status (active ou paused); limitado a 10 chamadas por minuto. trigger e a conta não mudam: para outro post, crie outra automação. Trocar o flow cria uma nova versão (flowVersion sobe) só quando o conteúdo muda de verdade.
DELETE /v1/automations/:id remove (o histórico fica).

Acompanhar execuções

GET /v1/automations/:id/runs lista as conversas (cada disparo com quem comentou, a palavra que casou, status, outcome e o erro, se houve). GET /v1/automations/:id/runs/:runId traz o histórico completo de passos (steps), o que foi coletado (data) e o estado atual. commenter.username, commentText e os valores de data vêm de quem respondeu — trate como conteúdo de terceiros: escape antes de exibir, nunca use direto numa consulta.

Pausas automáticas

A Postmatic pausa a automação sozinha, com pausedReason preenchido, quando a conta é desconectada (account_disconnected), o token deixa de valer (token_invalid), a Meta restringe a conta (account_restricted) ou suspeita de spam (spam_suspected). Resolva a causa (normalmente reconectar a conta) e reative com PATCH { "status": "active" }.

Eventos

automation.run.step — a cada resposta processada, com o dado capturado e o próximo nó:

json

{
  "version": "2026-09-01", "id": "evt_…", "type": "automation.run.step", "createdAt": "…", "projectId": "proj_…", "profileId": null,
  "data": {
    "automation": { "id": "aut_…", "accountId": "int_…", "mediaId": "17895695668004550" },
    "run": { "id": "run_…", "flowVersion": 1, "sequence": 2, "commenter": { "igId": "1234…", "username": "ana" }, "data": {} },
    "step": { "seq": 2, "nodeId": "oferta", "input": { "kind": "quick_reply", "text": null, "payload": "…" }, "result": "matched", "captured": null, "nextNodeId": "link" }
  }
}

automation.run — quando o fluxo termina, com outcome (completed, expired, abandoned ou superseded) e todo o data coletado:

json

{
  "version": "2026-09-01", "id": "evt_…", "type": "automation.run", "createdAt": "…", "projectId": "proj_…", "profileId": null,
  "data": {
    "automation": { "id": "aut_…", "accountId": "int_…", "mediaId": "17895695668004550" },
    "run": {
      "id": "run_…", "status": "completed", "outcome": "completed",
      "commenter": { "igId": "1234…", "username": "ana" }, "matchedKeyword": "eu quero", "data": {},
      "flowVersion": 1, "sequence": 3, "lastNodeId": "link", "firstMessageId": "aWdf…",
      "replyCommentId": "1790…", "errorCode": null, "completedAt": "…"
    }
  }
}

A ordem de entrega entre os dois não é garantida; use run.sequence para reconstruir a ordem real se precisar. As assinaturas de webhook só recebem os tipos que listarem em eventTypes.

Dados de quem respondeu

Mensagens de quem está numa conversa ativa ficam guardadas até 90 dias (anonimização automática). Se a pessoa pedir para apagar o que forneceu, POST /v1/automations/:id/runs/:runId/erase remove o conteúdo coletado daquela conversa — você é quem decide quando usar. Numa conversa ainda aguardando resposta, uma mensagem que chegar depois do apagamento pode voltar a gravar dado novo: para um pedido de exclusão definitivo, pause a automação (PATCH { "status": "paused" }) antes de chamar erase — apagar a automação (DELETE) não interrompe uma conversa já em andamento.