Pular para o conteúdo principal

Guia de Migração: Plugin da API de Broadcast em /messages → /campaign/full (API Active Campaign Growth)

  • Atualizado
  1. Sobre esta migração
  2. Estado atual - Broadcast
  3. Rota para migrar - Campanha Ativa
  4. De-Para das requests
  5. Rota de /Notifications
  6. Envio Direto

 

Sobre esta migração

Esta migração se aplica especificamente às integrações que utilizam o endpoint /messages para envio de mensagens em massa (Plugin de API de Broadcast).

Se você utiliza outros recursos da API /messages que não estejam relacionados ao envio de campanhas via Broadcast, nenhuma alteração é necessária neste momento. Esses recursos continuam funcionando normalmente.

Ao longo deste artigo, apresentamos as orientações para migrar apenas Plugin da API de Broadcast (pertencente a API /messages) para a API do Growth, garantindo a continuidade dos seus disparos e o acesso aos novos recursos disponíveis. 

 

Estado atual - Broadcast

Na atual versão da API de broadcast, existem 2 grandes rotas para realizar os envios

  • /api/v2/Broadcast/csv: A partir de um CSV enviado no corpo da requisição é possível realizar os disparos

  • /api/v2/Broadcast/list: A partir de um body em JSON no corpo da requisição é possível realizar os disparos

Além das URIS, diversos outros parâmetros, via cabeçalho e queryString são utilizados no envio

Headers

  • identifier: identificador do bot pelo qual serão disparadas as notificações

  • accessKey: a accessKey (TCP) do bot

  • organization: id da organização para envio das requisições para a plataforma

  • user: email para qual será enviado o report dos disparos

Querystring

  • phoneColumn: dado o payload, qual será o campo (no csv ou no json) que conterá o telefone para disparo

  • namespace: namespace ao qual está atrelado o template a ser enviado

  • template: nome do template a ser enviado

  • senderEmail: email para qual será enviado o report dos disparos

  • languageCode: idioma que será utilizado no envio do template

  • scheduleTime: Dado o horário atual, quantos segundos depois queremos que a campanha seja agendada (EX: se queremos a campanha para 1h depois do envio, precisamos passar 3600)

Corpo/CSV

Além dos parâmetros acima citados, alguns templates podem precisar de variáveis adicionais. Essas variaveis são decididas de maneira POSICIONAL, de modo que, se o Message Template contiver um vídeo e 2 variáveis no corpo da requisição, teremos um corpo semelhante ao exemplo abaixo, onde a URL será passada para o "HEADER" e as demais variaveis usadas no corpo da mensagem

[
 {
 "telefone": "5531900000000",
 "url": "https://v.ftcdn.net/17/86/49/30/240_F_1786493040_OGqTFtyomFdsGwkoRbYkUSsWKINLbirM_ST.mp4",
 "var1": "ValorVar1",
 "var2: "ValorVar2",
 }
]

 

Rota para migrar - Campanha Ativa

Na atual versão da API, foram disponibilizadas rotas de Active Campaign compatíveis com os parâmetros utilizados nas rotas de Broadcast

  • /api/v2/ActiveCampaign/list

  • /api/v2/ActiveCampaign/csv

Enviando uma requisição com o corpo exibido no exemplo anterior, teremos a campanha criada normalmente

[
 {
 "telefone": "5531900000000",
 "url": "https://v.ftcdn.net/17/86/49/30/240_F_1786493040_OGqTFtyomFdsGwkoRbYkUSsWKINLbirM_ST.mp4",
 "var1": "ValorVar1",
 "var2: "ValorVar2",
 }
]

Visualização na plataforma

Além de termos os envios centralizados, na tela de Growth/Mensagens Ativas, as campanhas serão exibidas sob o prefixo WA-Broadcast-Plugin, indicando que vieram através da API, conforme imagem abaixo

Saúde do número

Através da mesma tela também é possível validar a saúde do número

 

De-Para das requests

Abaixo seguem alguns comparativos, usando a sintaxe CURL como base, de como as requests são no modo broadcast e como elas podem ser ajustadas para o modo Active Campaign.

Carrossel Templates

TLDR: O que muda em resumo é apenas o path da requisição

  • Broadcast: /api/v2/Broadcast/csv e /api/v2/Broadcast/list

  • Active Campaign: /api/v2/ActiveCampaign/csv e /api/v2/ActiveCampaign/list

Tipo Carrossel

A API De broadcast não suporta o envio do tipo Carrossel por ela. Para enviar Campanhas Ativas desse tipo, utilize diretamente a aplicação de Campanha ativa

CSV

Texto Simples

  • Broadcast

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/Broadcast/csv?phoneColumn=telefone&namespace=<NAMESPACE_TEMPLATE_WPP>&template=<TEMPLATE_TEXTO_SIMPLES>&senderEmail=<EMAIL_PARA_NOTIFICACAO>&languageCode=<IDIOMA_TEMPLATE_PARA_ENVIO>&scheduleTime=0&headerVariables=true&separator=%2C' \
--header 'identifier: <ID_DO_BOT>' \
--header 'accessKey: <ACCESS_KEY_BOT>' \
--header 'organization: <ID_ORGANIZACAO>' \
--header 'user: <EMAIL_PARA_NOTIFICACAO>' \
--form 'formFile=@"/<DIRETORIO_ARQUIVO_CSV>/csv-without-variable.csv"'
- ActiveCampaign
curl --location 'https://takebroadcast.cs.blip.ai/api/v2/ActiveCampaign/csv?phoneColumn=telefone&namespace=<NAMESPACE_TEMPLATE_WPP>&template=<TEMPLATE_TEXTO_SIMPLES>&senderEmail=<EMAIL_PARA_NOTIFICACAO>&languageCode=<IDIOMA_TEMPLATE_PARA_ENVIO>&scheduleTime=0&headerVariables=true&separator=%2C' \
--header 'identifier: <ID_DO_BOT>' \
--header 'accessKey: <ACCESS_KEY_BOT>' \
--header 'organization: <ID_ORGANIZACAO>' \
--header 'user: <EMAIL_PARA_NOTIFICACAO>' \
--form 'formFile=@"/<DIRETORIO_ARQUIVO_CSV>/csv-without-variable.csv"'

 

Rota de /Notifications

Essa rota existe desde as primeiras versões da API e o intuito dela é para permitir o envio de notificações individuais aos usuários. Na rota de ActiveCampaign, utilizando o endpoint de /list, podemos enviar uma Campanha de um usuário para manter a compatibilidade da mesma com o uso atual.

Principais diferenças

Para realizar a conversão das rotas, existem algumas diferenças em como os parâmetros são utilizados

Querystrings e Headers

  • Os parâmetros namespace, template e languageCode não são enviados no corpo da requisição e sim como querystring;

  • É necessário utilizar o parâmetro phoneColumn=telefone para indicar qual o campo que conterá o número a receber a mensagem ativa;

  • É necessário adicionar o cabeçalho senderEmail

  • É necessário adicionar o campo scheduleTime para permitir o agendamento do envio

  • Os parâmetros identifier, accessKey, organization e user se mantem com o mesmo comportamento, não precisando de nenhuma alteração.

Corpo da requisição

Já no corpo da requisição, o campo que conterá o telefone para qual será disparada a notificação deve bater de acordo com o especificado no parametro phoneColumn (no exemplo do artigo, o corpo deve conter o body telefone)

Os demais campos são posicionais:

  • Caso um template seja do tipo imagem: o primeiro parametro do body será referente a URL da mídia a ser enviada e os demais referentes ao texto de legenda da mensagem

  • Caso um template seja do tipo vídeo: o primeiro parâmetro do body será referente a URL da mídia a ser enviada e os demais referentes ao texto de legenda da mensagem

     

  • Notification

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/Notification/' \
--header 'Content-Type: application/json' \
--header 'identifier: <BOT_ID>' \
--header 'accessKey: <BOT_ACCESS_KEY>' \
--header 'organization: <ORGANIZATION_ID>' \
--header 'user: <USER_EMAIL>' \
--header 'costCentre: 0' \
--data '{
 "phoneNumber": "<PHONENUMBER>",
 "namespace": "<MESSAGE_TEMPLATE_NAMESPACE>",
 "template": "<MESSAGE_TEMPLATE>",
 "languageCode": "<MESSAGE_TEMPLATE_LANGUAGE>",
 "parameters": {
 "header": {
 "type": "image",
 "url": "https://images3.alphacoders.com/107/thumb-1920-1070509.jpg"
 },
 "body": [
 "<VARIABLE_VALUE>"
 ]
 }
}'

  • Rota de campanha ativa

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/ActiveCampaign/list?phoneColumn=telefone&namespace=<MESSAGE_TEMPLATE_NAMESPACE>&template=<MESSAGE_TEMPLATE>&senderEmail=tulior%40blip.ai&languageCode=<MESSAGE_TEMPLATE_LANGUAGE>&scheduleTime=0' \
--header 'Content-Type: application/json' \
--header 'identifier: <BOT_ID>' \
--header 'accessKey: <BOT_ACCESS_KEY>' \
--header 'organization: <ORGANIZATION_ID>' \
--header 'user: <USER_EMAIL>' \
--header 'costCentre: 0' \
--data '[
 {
 "telefone": "<PHONENUMBER>",
 "url": "https://images3.alphacoders.com/107/thumb-1920-1070509.jpg",
 "var1": "<VARIABLE_VALUE>"
 }
]'

 

Envio Direto

Confirá o artigo em que ensinamos a utilizar diretamente a aplicação de Active Campaign, com as urls da plataforma: Como enviar notificações via API Active Campaign (Growth)


 

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 😃