Como disparar Mensagem Ativa via API pelo canal SMS – Blip | Blip Help

Objetivo

Este artigo mostra como usar a API de Campanhas (Active Campaign) para criar, configurar e disparar uma campanha de mensagem ativa pelo canal SMS. Ele cobre o fluxo passo a passo (/campaigns, /audiences, /messages, /dispatch) e os fluxos combinados (/campaign/full e /campaign/full/v2), que fazem tudo em uma única chamada.

Pré-requisitos

O canal SMS precisa estar habilitado para a sua conta/ambiente. Se não estiver, qualquer requisição com channelType = SMS será recusada com erro de validação.
As requisições são enviadas como comandos do protocolo LIME (Set/Get), autenticados com a identidade do bot.

Visão geral do fluxo

Existem dois jeitos de disparar uma campanha SMS:

Fluxo passo a passo — quatro chamadas separadas: criar campanha, cadastrar audiência, definir a mensagem e disparar. Dá mais controle sobre cada etapa antes do envio.
Fluxo combinado — uma única chamada que já cria a campanha, cadastra a audiência, define a mensagem e dispara. Use /campaign/full para a maioria dos casos, ou /campaign/full/v2 para bases grandes (via arquivo) ou filtro de usuários.

Criar a campanha — SET /campaigns

Cria o registro da campanha, definindo o canal como SMS.

Tipo de conteúdo (mime type): application/vnd.iris.activecampaign.campaign+json

Exemplo de requisição

{
  "id": "campaign-sms-001",
  "name": "Campanha SMS - Lembrete de pagamento",
  "campaignType": "INDIVIDUAL",
  "channelType": "SMS"
}

Campos

Campo	Obrigatório	Descrição
id	Sim	Identificador único da campanha, definido por você.
name	Sim	Nome descritivo da campanha.
campaignType	Sim	INDIVIDUAL (um destinatário), BATCH (vários destinatários).
channelType	Sim	Use SMS.
fileUrl	Não	URL de um arquivo CSV com a lista de destinatários, usado quando campaignType = BATCH.
scheduled	Não	Data/hora para agendar o envio. Se omitido, a campanha é tratada como imediata.
notificationEmail / notificationEmailLanguage	Não	E-mail (e idioma) para receber notificação caso a campanha falhe.
tags	Não	Lista de tags para agrupar e filtrar campanhas em relatórios.

Se o canal SMS não estiver habilitado no seu ambiente, essa chamada retorna erro de validação e a campanha não é criada.

Cadastrar a audiência — SET /audiences/{campaignId}

Adiciona os destinatários que vão receber a mensagem SMS.

Tipo de conteúdo: application/vnd.iris.activecampaign.audience+json

Exemplo de requisição (lista de destinatários)

[
  {
    "recipient": "+5511999990000",
    "recipientType": "PHONENUMBER",
    "channelType": "SMS",
    "messageParams": {
      "nome": "Maria",
      "valor": "R$ 150,00"
    }
  },
  {
    "recipient": "+5511988880000",
    "recipientType": "PHONENUMBER",
    "channelType": "SMS",
    "messageParams": {
      "nome": "João",
      "valor": "R$ 90,00"
    }
  }
]

Campos

Campo	Obrigatório	Descrição
recipient	Sim	Número de telefone no formato internacional, com + (ex.: +5511999990000).
recipientType	Não (padrão PHONENUMBER)	Tipo do destinatário.
channelType	Sim	Use SMS, igual ao definido na campanha.
messageParams	Não	Variáveis usadas para personalizar o texto da mensagem (ex.: {{nome}}, {{valor}}).
contextVariables	Não	Variáveis adicionais de contexto, não usadas no texto da mensagem.

Se você já informou fileUrl na campanha (campaignType = BATCH), não precisa chamar /audiences manualmente — os destinatários são carregados automaticamente a partir do arquivo.

Definir a mensagem — SET /messages/{campaignId}

Define o texto que será enviado por SMS.

Tipo de conteúdo: application/vnd.iris.activecampaign.message+json

Exemplo de requisição

{
  "channelType": "SMS",
  "messageContent": "Ola {{0}}, seu boleto de {{1}} vence amanha. Evite juros, pague em dia.",
  "messageParams": ["nome", "valor"]
}

Campos

Campo	Obrigatório	Descrição
channelType	Sim	Use SMS.
messageContent	Sim	Texto da mensagem. Use {{0}} para inserir os valores definidos em messageParams de cada destinatário.
messageParams	Não	Lista com os nomes dos parâmetros esperados no texto (referência/documentação).
messageTemplate / messageTemplateLanguage	Não se aplica ao SMS	Usados apenas em campanhas de WhatsApp; para SMS, esses campos são ignorados.

Dica: evite acentos e caracteres especiais no texto da mensagem. Eles podem aumentar o número de partes em que o SMS é dividido pela operadora, encarecendo o envio.

Disparar a campanha — SET /dispatch

Inicia o envio efetivo das mensagens da campanha já criada.

Tipo de conteúdo: application/vnd.iris.activecampaign.campaign+json (apenas os campos abaixo são considerados)

Exemplo de requisição

{
  "id": "campaign-sms-001",
  "isToUseLiteApi": false,
  "canSendWithOpenTicket": false
}

Campos

Campo	Obrigatório	Descrição
id	Sim	Id da campanha criada na etapa 1.
isToUseLiteApi	Não	Indica se o disparo deve usar a Lite API.
canSendWithOpenTicket	Não	Permite enviar mesmo se o contato tiver um atendimento em aberto.

Depois do disparo, o envio é processado de forma assíncrona: cada destinatário passa por validação de conta, registro e envio da mensagem, com atualização de status conforme o resultado da entrega.

Fluxo combinado — SET /campaign/full

Cria a campanha, cadastra a(s) audiência(s), define a mensagem e dispara tudo em uma única chamada. Use para campanhas do tipo INDIVIDUAL, BATCH.

Tipo de conteúdo: application/vnd.iris.activecampaign.full-campaign+json

Exemplo de requisição (campanha para um grupo de destinatários via SMS)

{
  "campaign": {
    "id": "campaign-sms-full-001",
    "name": "Campanha SMS Full - Promoção",
    "campaignType": "GROUP",
    "channelType": "SMS"
  },
  "audiences": [
    {
      "recipient": "+5511999990000",
      "recipientType": "PHONENUMBER",
      "channelType": "SMS",
      "messageParams": { "nome": "Maria" }
    },
    {
      "recipient": "+5511988880000",
      "recipientType": "PHONENUMBER",
      "channelType": "SMS",
      "messageParams": { "nome": "João" }
    }
  ],
  "message": {
    "channelType": "SMS",
    "messageContent": "Ola {{0}}, aproveite nossa promocao ate amanha!",
"messageParams": ["nome"]
  },
  "dispatch": true
}

Campos

Campo	Obrigatório	Descrição
campaign	Sim	Dados da campanha (mesmos campos da etapa 1).
audience	Condicional	Usado para um único destinatário (campaignType = INDIVIDUAL).
audiences	Condicional	Lista de destinatários (campaignType = BATCH).
message	Sim	Texto da mensagem SMS (mesmos campos da etapa 3).
dispatch	Não (padrão true)	Se false, cria a campanha sem disparar automaticamente.

Fluxo combinado dinâmico — SET /campaign/full/v2

Variante do fluxo combinado voltada para bases grandes: campanhas BATCH (origem via arquivo CSV). É a opção recomendada para volumes altos de destinatários, pois processa a origem de forma assíncrona.

Tipo de conteúdo: application/vnd.iris.activecampaign.full-campaign+json (mesmo formato do /campaign/full)

Somente campaignType = BATCH ou USERSFILTER são aceitos nesse endpoint. Qualquer outro valor é rejeitado.

Exemplo de requisição (campanha batch via SMS, origem por arquivo)

{
  "campaign": {
    "id": "campaign-sms-full-v2-001",
    "name": "Campanha SMS Full V2 - Base completa",
    "campaignType": "BATCH",
    "channelType": "SMS",
    "fileUrl": "https://storage.example.com/audiencias-sms.csv"
  },
  "message": {
    "channelType": "SMS",
    "messageContent": "Ola {{0}}, sua fatura esta disponivel.",
"messageParams": ["nome"]
  },
  "dispatch": true
}

Regra importantes para o canal SMS

Convivência com outros canais: habilitar o SMS não afeta o funcionamento de campanhas já existentes em WhatsApp ou Google RCS.

Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃