POST /automation-trigger

Dispara uma execução de fluxo de automação (drip de mensagens WhatsApp) pra um contato específico. Use quando algo no seu sistema externo precisa iniciar uma sequência automatizada (compra finalizada, abandono de carrinho, expiração de trial, etc).

Campo	Valor
URL	`https://api.wevi.chat/functions/v1/automation-trigger`
Método	`POST`
Auth	`Authorization: Bearer TOKEN_DO_FLUXO`
Content-Type	`application/json`
Rate limit	sem limite explícito (use com bom senso)

Pré-requisitos

Crie o fluxo em Automações no app.
Ative o gatilho "Webhook" nas configurações do trigger.
Copie o token mostrado nessa tela. Cada fluxo tem o seu próprio token, específico para disparar esse fluxo. Use-o como Bearer no header Authorization.

Body

Campo	Tipo	Obrigatório	Descrição
`phone`	string	sim	Telefone do contato. Aceita formato brasileiro com ou sem `+55` (é normalizado).
`name`	string	não	Nome do contato. Vai pra `contacts.name` se contato for novo ou se ainda não tiver nome.
`custom_fields`	object	não	Pares chave/valor. Os valores ficam disponíveis nas mensagens via `{{custom_fields.chave}}`.

Exemplos

curl -X POST https://api.wevi.chat/functions/v1/automation-trigger \
  -H "Authorization: Bearer TOKEN_DO_FLUXO" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511999999999",
    "name": "João Silva",
    "custom_fields": {
      "pedido": "12345",
      "valor": "297.00"
    }
  }'

await fetch("https://api.wevi.chat/functions/v1/automation-trigger", {
  method: "POST",
  headers: {
    "Authorization": "Bearer TOKEN_DO_FLUXO",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone: "+5511999999999",
    name: "João Silva",
    custom_fields: { pedido: "12345", valor: "297.00" },
  }),
});

Resposta

Sucesso (200)

{ "ok": true, "run_id": "uuid-da-run" }

A run_id identifica essa execução específica do fluxo. A primeira mensagem é disparada imediatamente; as próximas seguem o cronograma configurado.

Erros

Status	`error`	Causa
400	`phone is required`	Body sem `phone`.
400	`Invalid JSON`	Body não é JSON válido.
401	`Missing Authorization header`	Header faltando.
401	`Invalid token`	Token errado ou fluxo deletado.
403	`Webhook trigger disabled for this flow`	Fluxo não tem webhook habilitado nas configurações.
403	`opted_out`	Contato fez opt-out global (respondeu "PARAR" anteriormente).
409	`Flow is not active`	Fluxo está em draft ou pausado.
409	`Already in flow`	Contato já tem uma run ativa desse mesmo fluxo. Espere a anterior terminar ou cancele-a. Resposta inclui `reason: "active_run_exists"`.
409	(cooldown)	Contato saiu desse fluxo há menos tempo que o cooldown configurado. Resposta inclui `reason: "cooldown"` e `retry_at` (ISO8601).

Padrões de uso

Loop com retry inteligente

async function startFlow(phone, customFields) {
  const res = await fetch("https://api.wevi.chat/functions/v1/automation-trigger", {
    method: "POST",
    headers: { "Authorization": "Bearer ...", "Content-Type": "application/json" },
    body: JSON.stringify({ phone, custom_fields: customFields }),
  });
  const data = await res.json();
  if (res.status === 409 && data.reason === "cooldown") {
    console.log(`Em cooldown até ${data.retry_at}, ignorando.`);
    return;
  }
  if (!res.ok) throw new Error(data.error);
  return data.run_id;
}

Diferença pro `/contacts`

	`/automation-trigger`	`/contacts`
Pra quê	Iniciar fluxo de mensagens	Criar/atualizar contato
Auth	`Authorization: Bearer` (token do fluxo)	`Authorization: Bearer` (token da org)
Cria contato?	Sim, se não existir	Sim, se não existir
Envia mensagem?	Sim (a primeira do fluxo)	Não
Suporta tags?	Não	Sim
Suporta carteira?	Não	Sim (`assigned_user_email`)

Você pode usar os dois em sequência: primeiro /contacts pra atualizar dados completos do contato, depois /automation-trigger pra disparar o fluxo.

/automations

→