Skip to main content
Este guia monta um exemplo bem comum: alguém entra no produto → recebe e-mail de boas-vindas na hora → três dias depois recebe outro e-mail (dicas, NPS, etc.). A mesma lógica vale para outros gatilhos e canais, desde que os templates e permissões existam.

​
Antes de começar

Você vai precisar de:
  • Uma chave de API com permissão para eventos e automações (na doc técnica: events:read, events:write, automations:read, automations:write — ou uma chave “completa” se a sua política permitir).
  • Na mesma conta, escopos de envio dos canais que os templates usarem (email:send, whatsapp:send, …), como no Quick Start de templates.
  • Pelo menos um template já criado no workspace (anote os ids).
  • URL base da API (ex.: https://api.notifique.dev).
  • Autenticação: Authorization: Bearer sk_live_... ou cabeçalho x-api-key.
Substitua sk_live_xxxxx pela sua chave.

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

O seu backend escolhe o nome estável do fato (ex.: user.created). Aqui você só cadastra esse nome na API. POST /v1/events — escopo events:write. O campo schemaJson é opcional: tipos por campo (string, number, boolean). Se existir, o payload do disparo é conferido antes de criar execuções. Pedido 
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 e data com id, name, createdAt.

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

POST /v1/automations — escopo automations:write. O graph tem steps (cada um com stepKey, stepType, config) e connections (from / to). Deve existir exatamente um passo trigger com config.eventName igual ao evento já cadastrado. Três dias em milissegundos: 259200000 (= 3 × 24 × 60 × 60 × 1000). Pedido 
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" }
    ]
  }
}
Troque YOUR_WELCOME_TEMPLATE_ID e YOUR_TIPS_TEMPLATE_ID pelos ids reais. Em sendTemplate, campos como fromEmail, instanceId ou telegramInstanceId seguem a mesma ideia do envio manual de template. Fluxos maiores (vários envios, condição se/senão, atualizar contato, encerrar fluxo) usam o mesmo formato de grafo; muitas equipes desenham primeiro no painel e depois espelham na API.

​
Condições, fim de ramo e gatilho por mensagem (cola rápida)

  • condition — sempre duas saídas do mesmo passo, com branch "true" e "false". Dá para empilhar várias condições (uma filha da outra num ramo).
  • Gatilho por evento — em condition.config use source "event" ou "contact", propertyKey, operator e, se precisar, compareValue.
  • Gatilho por mensagem recebida — use source": "message"; não use propertyKey — o texto comparado é o da mensagem recebida.
  • endFlow — passo terminador: "stepType": "endFlow", "config": {}, sem conexão saindo desse passo. Só encerra aquele caminho.
Mais contexto conceitual: Introdução.

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

POST /v1/events/send — escopo events:write.
  • event — mesmo nome cadastrado.
  • payload — dados que o schema (se houver) aceita.
  • Destinatário — um entre contactId, email ou phone (telefone no formato internacional E.164).
Pedido 
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"
      }
    ]
  }
}
Repetir o pedido com o mesmo Idempotency-Key ajuda a não duplicar a jornada em retry de rede (idempotentReplay quando aplicável).

​
4. Ver se a jornada rodou

  • GET /v1/automations/:id/runs?page=1&limit=20 — lista execuções — escopo automations:read.
  • GET /v1/automations/:id/runs/:runId — detalhe com passos e status — escopo automations:read.
Use o automationId que voltou ao criar a automação (ou liste com GET /v1/automations).

​
Continuar