Skip to main content
Este guia monta um fluxo bem comum: alguém entra no produto → recebe boas-vindas na hora → três dias depois recebe outro e-mail (por exemplo com dicas). A mesma lógica serve para lembrete, NPS depois de uma semana, etc.

​
Pré-requisitos

  • Uma API Key com escopos events:write, events:read, automations:write, automations:read (ou acesso total).
  • Na mesma chave (ou outra que o motor use ao enviar), os escopos de envio dos canais que o template usar (email:send, whatsapp:send, etc.), como no Quick Start de templates.
  • Host: https://api.notifique.dev
  • Auth: Authorization: Bearer sk_live_xxxxx ou x-api-key: sk_live_xxxxx
  • Um template já criado no workspace (anote o id para usar abaixo).

​
1. Registrar o evento (“quando isso acontecer…”)

No dia a dia: o seu backend decide o momento — por exemplo logo após criar a conta — e vai chamar a API com um nome estável de evento. Aqui cadastramos a definição desse nome. POST /v1/events — escopo events:write. O schemaJson é opcional: um objeto com tipo por campo ("string", "number" ou "boolean"). Se existir, o payload do disparo é validado antes de criar as runs. 
POST /v1/events
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "user.created",
  "schemaJson": {
    "userId": "string",
    "plan": "string"
  }
}
Resposta típica: { "success": true, "data": { "id": "...", "name": "user.created", "createdAt": "..." } }.

​
2. Criar a automação (“…faça esta sequência”)

No dia a dia: você descreve o roteiro em sequência: gatilho → primeiro e-mail (boas-vindas) → espera de 3 dias → segundo e-mail (dicas). POST /v1/automations — escopo automations:write. O graph tem steps (cada passo com stepKey, stepType, config) e connections (from / to). Deve existir exatamente um passo trigger com config.eventName igual ao evento já cadastrado. Duração de 3 dias em milissegundos: 259200000 (= 3 × 24 × 60 × 60 × 1000). 
POST /v1/automations
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Boas-vindas e dicas em 3 dias",
  "status": "ENABLED",
  "graph": {
    "steps": [
      {
        "stepKey": "t1",
        "stepType": "trigger",
        "config": { "eventName": "user.created" }
      },
      {
        "stepKey": "sWelcome",
        "stepType": "sendTemplate",
        "config": {
          "templateId": "YOUR_WELCOME_TEMPLATE_ID",
          "channels": ["email"],
          "variables": { "name": "{{plan}}" }
        }
      },
      {
        "stepKey": "d1",
        "stepType": "delay",
        "config": { "durationMs": 259200000 }
      },
      {
        "stepKey": "sTips",
        "stepType": "sendTemplate",
        "config": {
          "templateId": "YOUR_TIPS_TEMPLATE_ID",
          "channels": ["email"],
          "variables": { "name": "{{plan}}" }
        }
      }
    ],
    "connections": [
      { "from": "t1", "to": "sWelcome" },
      { "from": "sWelcome", "to": "d1" },
      { "from": "d1", "to": "sTips" }
    ]
  }
}
Substitua YOUR_WELCOME_TEMPLATE_ID e YOUR_TIPS_TEMPLATE_ID pelos ids (cuid) dos templates — podem ser dois templates diferentes ou o mesmo, conforme o que você cadastrou. Campos úteis em sendTemplate: fromEmail, instanceId, telegramInstanceId (mesma ideia do envio manual de template). Fluxos mais ricos (vários envios, condição se/senão, atualizar contato, outros canais) usam o mesmo formato de grafo com mais passos e conexões; muitas equipes montam isso primeiro no painel e depois alinham com a API, se precisarem.

​
3. Disparar (“agora aconteceu de verdade”)

No dia a dia: no momento do cadastro (ou outro gatilho), o seu servidor chama POST /v1/events/send com quem é a pessoa e quais dados vão junto (payload). POST /v1/events/send — escopo events:write.
  • event: mesmo nome cadastrado (user.created).
  • payload: objeto; se houver schemaJson, precisa bater com os campos.
  • Destinatário: um entre contactId, email, phone.
POST /v1/events/send
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
Idempotency-Key: onboarding-user-created-001

{
  "event": "user.created",
  "email": "nova.pessoa@example.com",
  "payload": {
    "userId": "usr_123",
    "plan": "pro"
  }
}
Resposta de sucesso (trecho): 
{
  "success": true,
  "data": {
    "runs": [
      {
        "runId": "clxxxxxxxxxxxxxxxx",
        "automationId": "clyyyyyyyyyyyyyyyy"
      }
    ]
  }
}
Reenviar com o mesmo Idempotency-Key ajuda a não duplicar a jornada se houver retry de rede (idempotentReplay quando aplicável).

​
4. Conferir se a jornada rodou

No dia a dia: suporte ou você mesmo quer ver “já mandou o segundo e-mail?”.
  • GET /v1/automations/:id/runs?page=1&limit=20 — lista runs — escopo automations:read.
  • GET /v1/automations/:id/runs/:runId — detalhe com passos e status — escopo automations:read.
Use o automationId devolvido ao criar a automação (ou listando GET /v1/automations).