Templates e canais

📡 Canal

channel_type é obrigatório em POST /api/v1/acceptances. Único valor válido hoje: whatsapp.

🧱 Template: estrutura de passos

Um template é composto por steps[] — cada um com step_id, sequence, type e, quando aplicável, transitions[]. O cadastro do template (nome, idioma, textos) é feito junto à Clicksign; o que você envia em POST /api/v1/acceptances é apenas o template_id e as variáveis de preenchimento por passo.

Passos sem transitions são enviados automaticamente em sequência — o destinatário recebe as mensagens sem precisar interagir com a primeira. Passos do tipo text (mensagens de confirmação automáticas) não precisam ser declarados em channel_params no momento da criação — o conteúdo fixo já vem do template armazenado.

🔀 Três padrões de fluxo

Padrão A — Passo único com botões de decisão (Módulo de Aceite)

Um único passo apresenta os botões de aceite/recusa diretamente. Ideal para termos simples ou confirmações pontuais.

{
  "steps": [
    {
      "step_id": "decisao",
      "sequence": 1,
      "type": "template",
      "content": {
        "template": { "variables": { "body": ["{{1}}", "{{2}}"] } }
      },
      "transitions": [
        { "button_text": "Aceitar", "outcome": "accepted" },
        { "button_text": "Recusar", "outcome": "declined" }
      ]
    }
  ]
}

Padrão B — Passo informativo (auto-enviado) + passo de decisão

O primeiro passo não tem transitions — é enviado junto com o segundo, sem esperar interação. Use quando o primeiro passo é puramente informativo (ex.: apresentar o contrato antes dos botões).

{
  "steps": [
    {
      "step_id": "informacao",
      "sequence": 1,
      "type": "template",
      "content": { "template": { "variables": { "body": ["{{1}}", "{{2}}", "{{3}}"] } } }
    },
    {
      "step_id": "decisao",
      "sequence": 2,
      "type": "template",
      "content": { "template": { "variables": { "body": ["{{1}}"] } } },
      "transitions": [
        { "button_text": "Aceitar", "outcome": "accepted" },
        { "button_text": "Recusar", "outcome": "declined" }
      ]
    }
  ]
}

Padrão C — Botão de navegação + passo de aceite

O primeiro passo tem um botão de navegação (next_step_id) que só libera o segundo passo quando o destinatário clicar. Use quando a confirmação de leitura do primeiro passo é pré-requisito (ex.: "li e aceito os termos" → botão para assinar).

{
  "steps": [
    {
      "step_id": "apresentacao",
      "sequence": 1,
      "type": "template",
      "content": { "template": { "variables": { "body": ["{{1}}", "{{2}}", "{{3}}"] } } },
      "transitions": [
        { "button_text": "Continuar", "next_step_id": "confirmacao" }
      ]
    },
    {
      "step_id": "confirmacao",
      "sequence": 2,
      "type": "template",
      "content": { "template": { "variables": { "body": ["{{1}}"] } } },
      "transitions": [
        { "button_text": "Confirmar e Assinar", "outcome": "accepted" }
      ]
    }
  ]
}

Módulo de Notificação — sem decisão

Para notificações puramente informativas, o passo final simplesmente não declara transitions. O aceite se encerra em SENT/DELIVERED — não há um botão de aceite/recusa a aguardar.

💬 Mensagens de fechamento automáticas

Um template pode declarar on_accepted_step_id / on_declined_step_id — o step_id de um passo type: "text" enviado automaticamente ao destinatário quando o aceite atinge ACCEPTED/DECLINED, antes da entrega do webhook. Passos text não têm variáveis — o conteúdo é fixo, definido no cadastro do template.

🧩 Pré-requisito: template aprovado no canal (WhatsApp)

Antes de um template estar disponível para uso, ele precisa existir e estar aprovado no provedor do canal (Meta Business Manager, no caso do WhatsApp). Pontos de atenção herdados do canal:

• Um template WhatsApp tem componentes HEADER (opcional, até uma variável {{1}}), BODY (obrigatório, {{1}}...{{N}}), FOOTER (estático) e BUTTONS (até 3 botões de Quick Reply ou CTA).
• Os textos dos botões são estáticos no canal — não são variáveis. O texto do transitions[].button_text precisa ser idêntico ao cadastrado.
• O template precisa estar com status APPROVED antes de ser usado — templates novos podem levar horas ou dias para aprovação.

O cadastro e a manutenção do template são feitos junto à Clicksign — o template_id fornecido no onboarding já reflete um template aprovado.

🏷️ Metadados

metadata (chave-valor livre) é opcional em POST /api/v1/acceptances. É devolvido no relatório (GET /api/v1/reports) e no recibo final via webhook — útil para correlacionar com um número de contrato, CPF, ou qualquer identificador do seu sistema.

Próximo passo ➡️

• Webhooks e relatórios — receba o recibo final e consulte o histórico da comunicação.
• Recipe: criar, disparar e consultar um aceite — acompanhe uma integração ponta a ponta.