Disparos de campanha pela API

Com a API de campanhas, sua integração faz os mesmos disparos do painel: escolhe a plataforma, o modelo de mensagem, a cadência de envio e o público, filtrado por etiquetas, funil, canal, datas e outros critérios. Este guia cobre o fluxo completo, da escolha do modelo ao acompanhamento do envio. Para chaves e autenticação, veja a Introdução à API. Para o disparo no produto, veja Disparos e Modelos de mensagem.

Pré-requisitos

Requisito	Detalhe
Chave secreta	Todas as rotas desta página exigem `sk_` no cabeçalho `X-API-Key`
Ambiente ativo	Habilite o ambiente em Configurações → Desenvolvedores
Assinatura ativa	Sem assinatura ativa, a API responde `403` com `SUBSCRIPTION_INACTIVE`
Modelo cadastrado	Crie o modelo pela API de modelos ou no painel, em Modelos de mensagem
Chats existentes	O público é formado por chats que já estão no CRM. Para incluir contatos novos, crie os chats antes com `POST /v1/chats` ou por formulários de captação

X-API-Key: sk_sua_chave_secreta
Content-Type: application/json

URL base: https://gateway.crmspark.com.br, com o prefixo /v1.

Como funciona

Toda campanha nasce como rascunho e é iniciada numa segunda chamada:

POST /v1/campaigns salva a campanha em draft, com modelo, plataforma, cadência e filtros.
POST /v1/campaigns/{id}/start confere as variáveis manuais, monta o público e começa o envio.

Entre as duas chamadas, você pode estimar o público com audience-preview. As variáveis manuais do modelo são informadas só no início, como no diálogo “Iniciar” do painel. Não há agendamento nem pausa. Um rascunho é iniciado uma vez, e uma campanha em andamento pode ser cancelada.

Endpoints

Método	Rota	Descrição
`GET`	`/v1/campaigns/filters/schema`	Catálogo de campos, operadores e formatos dos filtros
`POST`	`/v1/campaigns/audience-preview`	Estima quantos chats entram no público
`POST`	`/v1/campaigns`	Cria a campanha em rascunho (`201`)
`GET`	`/v1/campaigns`	Lista as campanhas da organização
`GET`	`/v1/campaigns/{id}`	Detalhe da campanha com o histórico de execuções
`POST`	`/v1/campaigns/{id}/start`	Inicia o envio (`202`)
`GET`	`/v1/campaigns/{id}/executions/{executionId}`	Progresso de uma execução
`POST`	`/v1/campaigns/{id}/cancel`	Cancela uma campanha em andamento (`204`)

Os modelos de mensagem usados nas campanhas são gerenciados pelos endpoints de modelos de mensagem. A referência interativa documenta cada campo, código de erro e exemplo.

Passo a passo

Escolha o modelo de mensagem

Liste os modelos e anote o id do que você vai usar:

curl -s https://gateway.crmspark.com.br/v1/message-templates \
  -H "X-API-Key: sk_…"

{
  "templates": [
    {
      "id": "message_template_abc123",
      "name": "Promoção VIP",
      "description": null,
      "isOfficial": true,
      "metaTemplateName": "promocao_vip",
      "metaTemplateStatus": "APPROVED",
      "category": "MARKETING",
      "language": "pt_BR",
      "metaRejectedReason": null,
      "createdAt": "2026-05-01T12:00:00.000Z",
      "updatedAt": "2026-05-10T08:30:00.000Z"
    }
  ]
}

isOfficial: true indica um modelo oficial, aprovado pela Meta. Modelos oficiais só podem ser usados com platform igual a whatsapp ou instagram.

Consulte as variáveis do modelo

Veja quais variáveis manuais você vai precisar informar:

curl -s https://gateway.crmspark.com.br/v1/message-templates/message_template_abc123 \
  -H "X-API-Key: sk_…"

{
  "id": "message_template_abc123",
  "name": "Promoção VIP",
  "isOfficial": true,
  "body": "Olá {{1}}, aproveite {{2}}!",
  "commonVariables": [
    { "key": "var2", "label": "Nome da promoção", "required": true }
  ]
}

Cada item de commonVariables é uma variável manual. As variáveis automáticas, como o nome do chat, não aparecem na lista: o Spark preenche para cada destinatário.

Monte os filtros de público

Consulte o catálogo de campos:

curl -s https://gateway.crmspark.com.br/v1/campaigns/filters/schema \
  -H "X-API-Key: sk_…"

Estime o tamanho do público antes de criar a campanha:

curl -s -X POST https://gateway.crmspark.com.br/v1/campaigns/audience-preview \
  -H "X-API-Key: sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "combinator": "and",
        "statements": [
          { "field": "chat.platform", "operator": "equals", "value": "whatsapp" },
          { "field": "chat.tagIds", "operator": "has-any", "value": ["tag_vip123"] }
        ]
      }
    ]
  }'

{ "estimatedCount": 142 }

Se estimatedCount for 0, revise os filtros.

Crie a campanha

curl -s -X POST https://gateway.crmspark.com.br/v1/campaigns \
  -H "X-API-Key: sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promoção maio 2026",
    "description": "Clientes VIP no WhatsApp Business",
    "platform": "whatsapp",
    "templateId": "message_template_abc123",
    "cadence": 10,
    "filters": [
      {
        "combinator": "and",
        "statements": [
          { "field": "chat.platform", "operator": "equals", "value": "whatsapp" },
          { "field": "chat.tagIds", "operator": "has-any", "value": ["tag_vip123"] }
        ]
      }
    ]
  }'

{
  "campaignId": "campaign_xyz789",
  "status": "draft"
}

Guarde o campaignId para as próximas chamadas.

Inicie o envio

Envie commonVariables se o modelo tiver variáveis manuais:

curl -s -X POST https://gateway.crmspark.com.br/v1/campaigns/campaign_xyz789/start \
  -H "X-API-Key: sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "commonVariables": {
      "var2": "Promoção de maio"
    }
  }'

{
  "executionId": "campaign_execution_def456",
  "status": "processing"
}

Se o modelo não tiver variáveis manuais, envie {}.

Acompanhe o progresso

Consulte a execução até status ser completed, failed ou canceled:

curl -s https://gateway.crmspark.com.br/v1/campaigns/campaign_xyz789/executions/campaign_execution_def456 \
  -H "X-API-Key: sk_…"

{
  "id": "campaign_execution_def456",
  "status": "processing",
  "targetCount": 142,
  "sentCount": 87,
  "failedCount": 2,
  "progress": 63
}

Consulte a cada 10 a 30 segundos.

Plataforma

O campo platform define o canal de envio, a velocidade máxima e quais modelos podem ser usados:

Valor	Canal	Modelos aceitos	Velocidade máxima
`whatsapp`	WhatsApp Business (API oficial)	Oficiais e internos	15 mensagens por minuto
`whatsapp_lite`	WhatsApp Lite	Só internos	4 mensagens por minuto
`instagram`	Instagram	Oficiais e internos	15 mensagens por minuto

Telegram não é aceito em campanhas novas. No WhatsApp Business, só modelos oficiais aprovados chegam a contatos fora da janela de 24 horas. Modelos internos funcionam como mensagens comuns e só são entregues dentro da janela de atendimento do canal. Um modelo oficial com platform: "whatsapp_lite" é recusado com CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH.

O campo platform não limita quais chats entram no público. Para enviar só para chats de um canal, inclua um filtro chat.platform ou chat.entrypointId. Veja Filtros de público.

Cadência

cadence é o número de mensagens por minuto que a campanha tenta enviar: um inteiro maior ou igual a 1. Com "cadence": 10, a campanha envia até 10 mensagens por minuto, em intervalos iguais. Valores acima da velocidade máxima da plataforma (veja a tabela acima) não aceleram o envio. O Spark respeita esse teto para reduzir o risco de bloqueio dos números.

Na primeira campanha, use uma cadência de 5 a 10 e aumente aos poucos, conforme a taxa de sucesso e as respostas dos contatos.

Variáveis do modelo

Os modelos podem ter trechos variáveis ({{1}}, {{2}}, …) de dois tipos.

Variáveis manuais (`commonVariables`)

Você informa o valor uma vez, no início, e ele vale para todos os destinatários da execução.

No modelo	Chave na API	Exemplo
`{{1}}`	`var1`	`"Promoção de maio"`
`{{2}}`	`var2`	`"15OFF"`
`{{3}}`	`var3`	`"https://loja.com/promo"`

{
  "commonVariables": {
    "var1": "Promoção de maio",
    "var2": "15OFF"
  }
}

Para saber o que enviar, chame GET /v1/message-templates/{id} e leia commonVariables. Cada item tem key (por exemplo var1), label (nome da variável) e required. Se faltar alguma variável manual, o início falha com CAMPAIGN_MISSING_COMMON_VARIABLES.

Variáveis automáticas

São as variáveis configuradas como “Automático — dados do chat” (nome, contato, aniversário ou campo personalizado). O Spark preenche cada uma com os dados de cada destinatário no momento do envio. Não envie essas variáveis no corpo.

Se um chat não tiver o dado (por exemplo, sem nome ou com o campo personalizado vazio), a variável sai em branco. Antes de um disparo grande, confira os dados ou use filtros para excluir chats incompletos.

Exemplo com os dois tipos

Modelo: "Olá {{1}}, aproveite {{2}} com desconto exclusivo!"

{{1}}: automática (nome do chat). Não envie.
{{2}}: manual (nome da promoção). Envie como "var2": "Black Friday".

Corpo do início:

{
  "commonVariables": {
    "var2": "Black Friday"
  }
}

Cada destinatário recebe, por exemplo, "Olá Maria, aproveite Black Friday com desconto exclusivo!". “Maria” vem do chat e “Black Friday” é igual para todos.

Filtros de público

Os filtros definem quais chats recebem a campanha. A estrutura é a mesma dos filtros do painel de disparos.

Estrutura

{
  "filters": [
    {
      "combinator": "and",
      "statements": [
        {
          "field": "chat.platform",
          "operator": "equals",
          "value": "whatsapp"
        },
        {
          "field": "chat.tagIds",
          "operator": "has-any",
          "value": ["tag_abc", "tag_def"]
        }
      ]
    }
  ]
}

Regras de combinação

Nível	Regra
Entre grupos (`filters[]`)	AND: o chat precisa atender a todos os grupos
Dentro de um grupo	`combinator: "and"` ou `"or"` entre as condições (`statements`)

Exemplo: chats com a etiqueta VIP ou Premium, desde que sejam do WhatsApp Business.

{
  "filters": [
    {
      "combinator": "or",
      "statements": [
        { "field": "chat.tagIds", "operator": "has-any", "value": ["tag_vip"] },
        { "field": "chat.tagIds", "operator": "has-any", "value": ["tag_premium"] }
      ]
    },
    {
      "combinator": "and",
      "statements": [
        { "field": "chat.platform", "operator": "equals", "value": "whatsapp" }
      ]
    }
  ]
}

Campos

A lista atualizada está sempre em GET /v1/campaigns/filters/schema.

Campo	Tipo	Formato do valor	Descrição
`chat.platform`	string	string	Plataforma: `whatsapp`, `whatsapp_lite`, `instagram` ou `telegram`
`chat.status`	string	string	Situação do chat: `ongoing`, `completed` ou `ignored`
`chat.monetization`	number	number	Valor de monetização
`chat.entrypointId`	string	ID	Canal do chat
`chat.funnelStepId`	string	ID	Etapa do funil
`chat.trackingLinkId`	string	ID	Link de rastreamento
`chat.isGroupChat`	boolean	boolean	Se o chat é um grupo
`chat.isAnswered`	boolean	boolean	Se a equipe já respondeu
`chat.needsHumanAttention`	boolean	boolean	Se o chat precisa de atenção humana
`chat.attentionReason`	string	string	Motivo da atenção
`chat.tagIds`	array	lista de IDs	Etiquetas do chat
`chat.assignedUserId`	string	ID	Responsável pelo chat
`chat.virtual.participants-count`	number	number	Quantidade de participantes
`chat.virtual.dm-participant.contact`	string	string	Telefone ou identificador do contato (conversas individuais)
`chat.virtual.dm-participant.birthDate`	date	ISO 8601	Data de nascimento do contato
`chat.virtual.lastMessageAt`	date	ISO 8601	Data da última mensagem
`chat.virtual.lastUpdateAt`	date	ISO 8601	Data da última atualização

Os IDs (tag_…, funnel_step_…, wa_entrypoint_… e outros) são os mesmos devolvidos pela API.

Operadores por tipo

Tipo	Operadores
string	`equals`, `not-equals`, `contains`, `not-contains`, `in`, `not-in`, `exists`, `not-exists`, `starts-with`, `ends-with`, `not-starts-with`, `not-ends-with`
number	`equals`, `not-equals`, `in`, `not-in`, `greater-than`, `less-than`, `greater-than-or-equal`, `less-than-or-equal`, `exists`, `not-exists`, `between`, `not-between`
boolean	`equals`, `not-equals`, `exists`, `not-exists`
date	`equals`, `not-equals`, `in`, `not-in`, `greater-than`, `less-than`, `greater-than-or-equal`, `less-than-or-equal`, `exists`, `not-exists`, `between`, `not-between`
array (etiquetas)	`has-any`, `has-all`, `has-none`, `exists`, `not-exists`

exists e not-exists não usam value. between e not-between usam value e value2.

Exemplos de filtros

Só WhatsApp Business:

{ "field": "chat.platform", "operator": "equals", "value": "whatsapp" }

Chats com a etiqueta “Cliente ativo”:

{ "field": "chat.tagIds", "operator": "has-all", "value": ["tag_cliente_ativo"] }

Chats sem as etiquetas “Inativo” e “Bloqueado”:

{ "field": "chat.tagIds", "operator": "has-none", "value": ["tag_inativo", "tag_bloqueado"] }

Última mensagem depois de uma data (calcule a data no seu código, por exemplo hoje menos 7 dias):

{
  "field": "chat.virtual.lastMessageAt",
  "operator": "greater-than",
  "value": "2026-05-20T00:00:00.000Z"
}

Nascidos entre duas datas:

{
  "field": "chat.virtual.dm-participant.birthDate",
  "operator": "between",
  "value": "1990-05-01T00:00:00.000Z",
  "value2": "1990-05-31T23:59:59.999Z"
}

Chats numa etapa do funil:

{ "field": "chat.funnelStepId", "operator": "equals", "value": "funnel_step_novo_lead" }

Chats que a equipe ainda não respondeu:

{ "field": "chat.isAnswered", "operator": "equals", "value": false }

Chats de canais específicos:

{ "field": "chat.entrypointId", "operator": "in", "value": ["wa_entrypoint_loja", "wa_entrypoint_suporte"] }

Estimar o público

POST /v1/campaigns/audience-preview calcula quantos chats atendem aos filtros, sem criar campanha e sem enviar mensagens. Aceita os mesmos filtros de POST /v1/campaigns.

curl -s -X POST https://gateway.crmspark.com.br/v1/campaigns/audience-preview \
  -H "X-API-Key: sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "combinator": "and",
        "statements": [
          { "field": "chat.platform", "operator": "equals", "value": "whatsapp" },
          { "field": "chat.isAnswered", "operator": "equals", "value": true }
        ]
      }
    ]
  }'

{ "estimatedCount": 142 }

Sem filters, a contagem inclui todos os chats da organização.

Status e acompanhamento

Status da campanha

Status	Significado
`draft`	Criada e ainda não iniciada
`processing`	Enviando
`completed`	Todos os envios terminaram
`canceled`	Cancelada durante o envio
`failed`	Nenhum envio teve sucesso

Detalhe com execuções

GET /v1/campaigns/{id} retorna a campanha e o histórico de execuções:

{
  "id": "campaign_xyz789",
  "name": "Promoção maio 2026",
  "description": "Clientes VIP no WhatsApp Business",
  "status": "processing",
  "platform": "whatsapp",
  "templateId": "message_template_abc123",
  "cadence": 10,
  "executions": [
    {
      "id": "campaign_execution_def456",
      "status": "processing",
      "targetCount": 142,
      "sentCount": 87,
      "failedCount": 2,
      "startedAt": "2026-05-28T14:00:00.000Z",
      "completedAt": null
    }
  ]
}

Progresso de uma execução

GET /v1/campaigns/{id}/executions/{executionId}:

Campo	Descrição
`targetCount`	Chats que entraram no público no início
`sentCount`	Mensagens enviadas ou entregues
`failedCount`	Envios que falharam (canal, janela de atendimento, modelo e outros motivos)
`progress`	Percentual concluído, de 0 a 100. Conta enviados, falhas e destinatários ignorados

Cancelar

curl -s -X POST https://gateway.crmspark.com.br/v1/campaigns/campaign_xyz789/cancel \
  -H "X-API-Key: sk_…"

Resposta: 204 No Content. Só campanhas em processing podem ser canceladas. As mensagens ainda na fila não são enviadas; as que já estavam sendo enviadas podem chegar ao destino.

Limite de destinatários

Cada campanha tem um tamanho máximo, igual a 24 horas de envio na velocidade máxima da plataforma: cerca de 21.600 chats no WhatsApp Business e no Instagram e 4.800 no WhatsApp Lite. O limite é conferido depois do início. Se o público passar dele, a execução termina em failed sem enviar mensagens e a campanha volta para draft. Use audience-preview antes de iniciar e, para públicos maiores, divida o envio em campanhas com filtros diferentes (por etiqueta, funil ou data).

Exemplo completo com o SDK TypeScript

import SparkCRM from "sparkcrm";

const client = new SparkCRM({ apiKey: process.env.SPARK_API_KEY });

const filters = [
  {
    combinator: "and" as const,
    statements: [
      { field: "chat.platform" as const, operator: "equals" as const, value: "whatsapp" },
      { field: "chat.tagIds" as const, operator: "has-any" as const, value: ["tag_vip123"] },
    ],
  },
];

// 1. Escolher o modelo
const { templates } = await client.messageTemplates.list();
const template = templates.find((t) => t.name === "Promoção VIP");
if (!template) throw new Error("Modelo não encontrado");

// 2. Ver as variáveis manuais
const detail = await client.messageTemplates.retrieve(template.id);
console.log(detail.commonVariables);

// 3. Estimar o público
const preview = await client.campaigns.previewAudience({ filters });
console.log(`Público estimado: ${preview.estimatedCount} chats`);

// 4. Criar o rascunho
const { campaignId } = await client.campaigns.create({
  name: "Promoção maio 2026",
  platform: "whatsapp",
  templateId: template.id,
  cadence: 10,
  filters,
});

// 5. Iniciar
const { executionId } = await client.campaigns.start(campaignId, {
  commonVariables: { var2: "Promoção de maio" },
});

// 6. Acompanhar
while (true) {
  const execution = await client.campaigns.retrieveExecution(executionId, {
    id: campaignId,
  });
  console.log(
    `Progresso: ${execution.progress}% (${execution.sentCount}/${execution.targetCount})`,
  );
  if (["completed", "failed", "canceled"].includes(execution.status)) break;
  await new Promise((resolve) => setTimeout(resolve, 15_000));
}

Veja Começar com TypeScript para instalar e configurar o SDK.

Erros comuns

As respostas de erro seguem o formato { statusCode, code, message }. Use code na lógica do seu código, não a mensagem.

Código	HTTP	Quando ocorre	O que fazer
`CAMPAIGN_NAME_ALREADY_EXISTS`	400	Já existe uma campanha com esse nome na organização	Use outro `name`
`MESSAGE_TEMPLATE_NOT_FOUND`	404	O `templateId` não existe na organização	Liste os modelos e use um ID válido
`CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH`	400	Modelo oficial com `platform: "whatsapp_lite"`	Use `whatsapp` ou `instagram`, ou um modelo interno
`CAMPAIGN_INVALID_FILTERS`	422	Campo, operador ou valor incompatível nos filtros	Consulte `filters/schema` e corrija
`CAMPAIGN_MISSING_COMMON_VARIABLES`	400	Faltam variáveis manuais no início	Envie todas as chaves de `commonVariables` do modelo
`CAMPAIGN_NOT_DRAFT`	422	A campanha não está em `draft` (já foi iniciada, concluída ou cancelada)	Crie outra campanha
`CAMPAIGN_ALREADY_PROCESSING`	422	A campanha já tem uma execução em andamento	Aguarde o fim ou cancele
`CAMPAIGN_NOT_FOUND`	404	O ID da campanha não existe na organização	Confira o `campaignId`
`VALIDATION_ERROR`	400	Corpo fora do formato esperado, ou cancelamento de campanha que não está em `processing`	Revise os campos e o status da campanha
`SUBSCRIPTION_INACTIVE`	403	A organização não tem assinatura ativa	Regularize a assinatura no painel

Boas práticas

Segmente o público com etiquetas, funil e datas. Públicos menores e relevantes respondem melhor.
Chame audience-preview antes de criar a campanha, para evitar público vazio ou maior do que o esperado.
Consulte GET /v1/message-templates/{id} antes de iniciar. Erros de variável só aparecem no início.
Fora da janela de atendimento, use modelos oficiais. Modelos internos só chegam dentro da janela.
Acompanhe failedCount. Falhas podem indicar chats fora da janela, números inválidos ou problemas no modelo.
Comece com cadência de 5 a 10 mensagens por minuto e ajuste conforme os resultados.
Use nomes únicos e descritivos, como “Promoção maio VIP”.
Se o início falhar por timeout de rede, consulte GET /v1/campaigns/{id} antes de tentar de novo. Se a campanha já estiver em processing, a nova tentativa devolve CAMPAIGN_NOT_DRAFT.

Leitura adicional

Disparos: campanhas no painel.
Modelos de mensagem: variáveis manuais e automáticas, modelos oficiais e internos.
Modelos de mensagem pela API: criar e editar modelos.
Modo Desenvolvedores: chaves e ambiente de API.
SDK TypeScript: cliente oficial sparkcrm.

Documentação

Entrypoints

Forms

Chats

Campaigns

Message Templates

Messaging

Pré-requisitos

Como funciona

Endpoints

Passo a passo

Plataforma

Cadência

Variáveis do modelo

Variáveis manuais (`commonVariables`)

Variáveis automáticas

Exemplo com os dois tipos

Filtros de público

Estrutura

Regras de combinação

Campos

Operadores por tipo

Exemplos de filtros

Estimar o público

Status e acompanhamento

Status da campanha

Detalhe com execuções

Progresso de uma execução

Cancelar

Limite de destinatários

Exemplo completo com o SDK TypeScript

Erros comuns

Boas práticas

Leitura adicional

​Pré-requisitos

​Como funciona

​Endpoints

​Passo a passo

​Plataforma

​Cadência

​Variáveis do modelo

​Variáveis manuais (commonVariables)

​Variáveis automáticas

​Exemplo com os dois tipos

​Filtros de público

​Estrutura

​Regras de combinação

​Campos

​Operadores por tipo

​Exemplos de filtros

​Estimar o público

​Status e acompanhamento

​Status da campanha

​Detalhe com execuções

​Progresso de uma execução

​Cancelar

​Limite de destinatários

​Exemplo completo com o SDK TypeScript

​Erros comuns

​Boas práticas

​Leitura adicional

Pré-requisitos

Como funciona

Endpoints

Passo a passo

Plataforma

Cadência

Variáveis do modelo

Variáveis manuais (`commonVariables`)

Variáveis automáticas

Exemplo com os dois tipos

Filtros de público

Estrutura

Regras de combinação

Campos

Operadores por tipo

Exemplos de filtros

Estimar o público

Status e acompanhamento

Status da campanha

Detalhe com execuções

Progresso de uma execução

Cancelar

Limite de destinatários

Exemplo completo com o SDK TypeScript

Erros comuns

Boas práticas

Leitura adicional