Guia de Migração: API TakeBroadcast para a API de Growth (Active Campaign)

1. Por que estamos fazendo essa mudança?
2. O que muda na prática?
3. Qual é o impacto para você?
4. Guia prático

Por que estamos fazendo essa mudança?

A API TakeBroadcast foi a primeira solução do Blip para envio de mensagens ativas. Ela cumpriu seu papel, mas foi construída fora do ecossistema nativo da plataforma e não recebe mais novas funcionalidades ou manutenções corretivas.

Toda evolução relacionada a disparos ativos já acontece na API de Growth (Active Campaign), que é nativa do Blip, integrada aos dashboards, à gestão de saúde do número e ao protocolo LIME — o mesmo protocolo usado por todo o ecossistema de extensões da plataforma.

Em resumo: a TakeBroadcast está em modo de descontinuação. Quem ainda a utiliza está usando uma API sem suporte ativo e sem acesso às melhorias e novos recursos lançados pela plataforma.

O que muda na prática?

A mudança principal: de API externa para comando LIME

A diferença mais importante é estrutural. A TakeBroadcast é chamada como uma API HTTP convencional em um domínio externo (takebroadcast.cs.blip.ai). A API de Growth usa o protocolo nativo de comandos LIME do seu contrato, o mesmo usado por todas as extensões do Blip. 

A nova estrutura: três pilares

Qualquer disparo na API de Growth é organizado em três blocos:

1. campaign — configurações gerais: nome, tipo (Individual ou Batch), canal e fluxo de retorno no Builder.

2. audience / audiences — quem recebe: número do destinatário, valores das variáveis e mídias por contato.

3. message — o que é enviado: nome do template aprovado, idioma e lista de parâmetros esperados.

Como os parâmetros funcionam agora

Na TakeBroadcast, os valores eram passados como campos soltos (var1, image). Na API de Growth:

• audience.messageParams — dicionário com os valores das variáveis por destinatário.

• message.messageParams — array com os nomes das chaves esperadas (schema). A ordem aqui deve seguir a ordem dos componentes do template cadastrado na Meta.

Importante: message.messageParams contém nomes de chaves, não valores. Passar valores nesse campo é um erro comum de migração.

Regra de ordenação dos parâmetros

A ordem em message.messageParams precisa seguir a estrutura do template:

Templates normais:

[ ...header, ...botões URL, ...body ]

Templates com Limited Time Offer: 

[ ...header, expiração da oferta, ...botões, ...body ]

Templates de Carrossel:

[ ...body principal, ...card 0 (header → botões → body), ...card 1, ... ]

Qual é o impacto para você?

O que você perde ficando na TakeBroadcast

• Dados de disparo e entrega não são atualizados em tempo real.

• Os novos dashboards de campanha da plataforma não leem dados da TakeBroadcast.

• Sem acesso a funcionalidades novas, como envio via BSUID.

• Sem controle de throughput individual por bot — risco de concorrência entre disparos.

• Sem visibilidade da saúde do número de WhatsApp na interface do Growth.

• Sem suporte a validações de negócio, como verificar se o usuário já está em atendimento antes de disparar.

O que você ganha migrando

• Dados de campanha em tempo real, visíveis diretamente na plataforma.

• Rastreamento completo por destinatário (status de entrega, leitura, falha e motivo).

• Controle de throughput por bot sem concorrência.

• Integração com fluxos do Builder via flowId e stateId para direcionamento em respostas da audiência.

• Agendamento de campanhas via campo scheduled.

• Acesso a todos os novos recursos lançados para a API de Growth.

Guia prático

Como identificar se você usa a API TakeBroadcast

Verifique as URLs que suas integrações e scripts de disparo chamam. Se aparecer o domínio abaixo, a integração usa a API legada: 

https://takebroadcast.cs.blip.ai/

Os endpoints mais comuns a verificar: 

O que e onde precisa alterar

Passo 1 — Trocar o endpoint HTTP

O <contrato> é seu identificador na plataforma Blip.

Passo 2 — Trocar os headers de autenticação

A Authorization da API de Growth usa a chave de acesso do bot encontrada no portal Blip em Configurações → Informações de conexão.

Atenção para arquitetura com bot roteador: a chave deve ser sempre a do bot roteador, não do subbot. O campo masterState precisa ser informado nesses casos.

Passo 3 — Reestruturar o payload

O payload deixa de ser uma lista simples e passa a ser um comando LIME com três blocos internos.

Cenário 1 — Template sem variáveis (individual)

Antes:

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/Broadcast/list?phoneColumn=telefone&namespace=<NAMESPACE>&template=<TEMPLATE>&languageCode=<IDIOMA>&scheduleTime=0' \
--header 'identifier: <ID_DO_BOT>' \
--header 'accessKey: <ACCESS_KEY_BOT>' \
--data '[{ "telefone": "<TELEFONE>" }]'

Depois: 

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "campaign": {
      "name": "Nome da campanha",
      "campaignType": "Individual",
      "channelType": "WhatsApp",
      "sourceApplication": "MinhaApp"
    },
    "audience": {
      "recipient": "+55119999999999"
    },
    "message": {
      "messageTemplate": "<TEMPLATE>",
      "messageTemplateLanguage": "<IDIOMA>",
      "channelType": "WhatsApp"
    }
  }
}

Cenário 2 — Template com variáveis de texto (individual)

Antes:

--data '[{ "telefone": "<TELEFONE>", "var1": "<VALOR>" }]'

Depois: os valores vão em audience.messageParams, e as chaves em message.messageParams:

"audience": {
  "recipient": "+55119999999999",
  "messageParams": {
    "1": "<VALOR>"
  }
},
"message": {
  "messageTemplate": "<TEMPLATE>",
  "messageTemplateLanguage": "<IDIOMA>",
  "messageParams": ["1"],
  "channelType": "WhatsApp"
}

Cenário 3 — Template com imagem no header

Antes:

--data '[{ "telefone": "<TELEFONE>", "image": "<URL_DA_IMAGEM>", "var1": "<VALOR>" }]'

Depois: a imagem entra primeiro em messageParams (ela é o parâmetro do header):

"audience": {
  "recipient": "+55119999999999",
  "messageParams": {
    "image": "<URL_DA_IMAGEM>",
    "username": "<VALOR>"
  }
},
"message": {
  "messageTemplate": "<TEMPLATE>",
  "messageTemplateLanguage": "<IDIOMA>",
  "messageParams": ["image", "username"],
  "channelType": "WhatsApp"
}
Cenário 4 — Envio em lote (múltiplos destinatários no payload)

Altere campaignType para Batch e use audiences (plural) com um array:

"campaign": {
  "name": "Campanha em lote",
  "campaignType": "Batch",
  "channelType": "WhatsApp"
},
"audiences": [
  {
    "recipient": "+55119999999991",
    "messageParams": { "1": "Valor para contato 1" }
  },
  {
    "recipient": "+55119999999992",
    "messageParams": { "1": "Valor para contato 2" }
  }
],
"message": {
  "messageTemplate": "<TEMPLATE>",
  "messageTemplateLanguage": "<IDIOMA>",
  "messageParams": ["1"],
  "channelType": "WhatsApp"
}

Cenário 5 — Envio em massa via CSV

Antes, fazia upload físico do arquivo. Agora, é preciso hospedar o CSV em uma URL pública e informá-la em fileUrl. O endpoint muda para /campaign/full/v2:

Antes:

curl --form 'formFile=@"/caminho/do/arquivo.csv"' \
  'https://takebroadcast.cs.blip.ai/api/v2/Broadcast/csv?...'

Depois:

{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full/v2",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "campaign": {
      "name": "Campanha via CSV",
      "campaignType": "Batch",
      "channelType": "WhatsApp",
      "fileUrl": "<URL_PUBLICA_DO_CSV>"
    },
    "message": {
      "messageTemplate": "<TEMPLATE>",
      "messageTemplateLanguage": "<IDIOMA>",
      "channelType": "WhatsApp"
    }
  }
}

Atenção: o arquivo CSV precisa estar acessível via URL pública (HTTP/HTTPS). Não pode mais enviar o arquivo binário na requisição.

Regras do CSV:

• A primeira coluna identifica o destinatário (ex.: telefone).

• As colunas cujos nomes forem listadas em message.messageParams são usadas como parâmetros do template — na mesma ordem.

• Colunas não listadas em message.messageParams são salvas em contact.extras do contato.

Checklist de migração

• [  ] Identificar todas as chamadas ao domínio takebroadcast.cs.blip.ai.

• [  ] Trocar o endpoint para https://<contrato>.http.msging.net/commands.

• [  ] Substituir os headers de autenticação pelo Authorization: Key <ACCESS_KEY>.

• [  ] Reestruturar o payload com os blocos campaign, audience/audiences e message.

• [  ] Mover os valores das variáveis para audience.messageParams.

• [  ] Declarar os nomes das chaves em message.messageParams (na ordem correta do template).

• [  ] Para CSV: hospedar o arquivo em URL pública e usar campaign.fileUrl com uri /campaign/full/v2.

• [  ] Validar o idioma do template no campo message.messageTemplateLanguage.

• [  ] Testar em homologação com números controlados antes de ir para produção.

Pontos de atenção frequentes

Artigos relacionados

• Como enviar notificações via API Active Campaign (Growth) — Blip Help Center

• Configuração do arquivo de audiência — Envio de notificações em massa

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 😃