[Alpha] Como configurar o reenvio automático por SMS via API (Fallback SMS) – Blip | Blip Help

Contexto

O reenvio automático por SMS (também chamado de fallback SMS) é uma funcionalidade que atua como canal secundário de entrega para suas mensagens ativas. Caso a mensagem não seja entregue no canal original (WhatsApp ou RCS) dentro de uma janela de tempo configurada, o sistema envia automaticamente o conteúdo via SMS para o mesmo contato, ampliando as chances de entrega.

Este guia mostra como configurar e operar essa funcionalidade diretamente pela API de Campanhas (Active Campaign), cobrindo o mesmo comportamento descrito no artigo [Alpha] Como configurar o reenvio automático por SMS no Blip Marketing, porém para quem integra diretamente com a API em vez de usar o Blip Marketing.

Antes de começar

Versão: Funcionalidade em fase Alpha, para utilizar, entre em contato com seu atendimento e peça a liberação.
Canal secundário: É necessário ter o canal SMS contratado e configurado na sua conta Blip.
Permissões de acesso: Acesso à aba Blip Marketing no Contato Inteligente.

A documentação abaixo se refere a utilização através da API, caso queira a funcionalidade através de paineI, acesse esta documentação.

Como funciona

Configuração do reenvio: ao criar a campanha, você inclui o objeto fallback com o canal SMS e o texto que será enviado nessa retentativa.
Definição da mensagem SMS: o texto do reenvio é escrito manualmente por você, de forma independente da mensagem do canal principal, respeitando os limites de caracteres do SMS.
Monitoramento de entrega: após o disparo, o sistema acompanha se a mensagem foi entregue no canal principal (WhatsApp ou RCS) durante a janela de monitoramento.
Acionamento do reenvio: passada essa janela sem confirmação de entrega no canal principal, o sistema cria e dispara automaticamente uma campanha SMS apenas para os destinatários que falharam.
Cobrança: cada SMS reenviado é cobrado conforme os custos contratados na sua conta para o canal SMS, você só paga pelos SMS efetivamente enviados.

Você não precisa chamar nenhum endpoint para acionar o reenvio: ele acontece de forma automática e assíncrona depois do disparo da campanha principal. Se nenhum destinatário falhar, nenhum SMS de reenvio é enviado e não há cobrança adicional.

Pré-requisitos e limitações

O reenvio só pode ser configurado em campanhas cujo canal principal seja RCS (Google RCS) ou WhatsApp. Não é possível configurar reenvio para uma campanha que já é SMS.
O único canal de reenvio suportado atualmente é SMS.
Só é possível configurar um reenvio por campanha (não há reenvio em cadeia, nem múltiplos canais de reenvio em paralelo).
Não há nova retentativa em caso de falha no próprio envio do SMS de reenvio.
O reenvio acontece apenas uma vez por destinatário.
Depois que a campanha é criada com reenvio configurado, não é possível editar essa configuração posteriormente pela API, a definição é feita apenas na criação.
O texto (message) do reenvio é obrigatório sempre que você define o canal de reenvio. Enviar o canal sem a mensagem resulta em erro de validação.

Configurando o reenvio automático por SMS via API

Etapa 1 - Definir o reenvio na criação da campanha

O reenvio é configurado dentro do próprio payload de criação da campanha (fluxo passo a passo SET /campaigns ou fluxo combinado SET /campaign/full / SET /campaign/full/v2), usando o campo fallback. Basta preencher o objeto fallback para ativá-lo, não existe uma flag separada de "ligar/desligar".

Etapa 2 - Escrever a mensagem SMS

A mensagem enviada no reenvio (fallback.message.messageContent) é independente da mensagem do canal principal, escreva um texto adaptado ao contexto do SMS, mantendo-o conciso e dentro do limite de caracteres (veja Limitações e regras do SMS).

Exemplo - campanha RCS com reenvio automático por SMS configurado

{
  "campaign": {
    "id": "campaign-rcs-001",
    "name": "Campanha RCS - Aviso de vencimento",
    "campaignType": "BATCH",
    "channelType": "GoogleRCS",
    "fallback": {
      "channelType": "SMS",
      "message": {
        "channelType": "SMS",
        "messageContent": "Ola {{0}}, seu boleto de {{1}} vence amanha. Evite juros, pague em dia."
      }
    }
  },
  "audiences": [
    {
      "recipient": "+5511999990000",
      "recipientType": "PHONENUMBER",
      "channelType": "GoogleRCS",
      "messageParams": { "nome": "Maria", "valor": "R$ 150,00" }
    }
  ],
  "message": {
    "channelType": "GoogleRCS",
    "messageContent": "Ola {{nome}}, seu boleto de {{valor}} vence amanha."
  },
  "dispatch": true
}

Campos do objeto fallback

Campo	Obrigatório	Descrição
channelType	Sim, para habilitar o reenvio	Canal usado na retentativa. Atualmente, apenas SMS é suportado.
message	Sim, quando channelType é informado	Objeto de mensagem (mesmo formato usado em /messages) com o texto que será enviado no reenvio.

Se você enviar fallback.channelType sem fallback.message, a criação da campanha é rejeitada com erro de validação, a campanha não chega a ser criada.

Se você não quiser configurar reenvio, simplesmente omita o campo fallback (ou envie null).

Usando variáveis na mensagem de SMS

A mensagem de reenvio também suporta variáveis, para personalizar o conteúdo de acordo com os dados de cada destinatário.

Integração direta pela API (este guia): use {{0}} no messageContent, com os valores enviados no messageParams de cada item de audiência, o mesmo padrão usado nas mensagens SMS comuns (veja Como fazer disparos de SMS pela plataforma Blip).
Campanhas criadas pelo Blip Marketing (portal): a sintaxe da variável segue o padrão do canal principal configurado no disparo, conforme descrito no artigo do Blip Help, RCS usa ${contact.extras.nome} e WhatsApp usa a posição numérica do template ({{0}}, {{1}}, ...). Usar o padrão errado faz o texto literal da variável aparecer na mensagem enviada ao contato, sem substituição.

O contador de caracteres considera a variável em si (o texto do placeholder) como parte do texto, não o valor final que será substituído para cada contato. Deixe uma margem de segurança ao montar a mensagem, já que valores mais longos (nomes compostos, por exemplo) podem ultrapassar o limite mesmo que o texto no placeholder esteja dentro dele.

Limitações e regras do SMS

Limite de caracteres

160 caracteres para texto simples (sem acentos, emojis ou símbolos especiais).
70 caracteres para texto com caracteres acentuados, emojis ou símbolos especiais.

Esse limite se aplica à mensagem final, já com as variáveis substituídas pelo valor real de cada destinatário, não ao texto bruto do messageContent antes da substituição.

Custo e faturamento

O reenvio automático é opcional e sujeito a custos adicionais. Cada SMS reenviado é cobrado conforme sua contratação de SMS, as taxas por operadora e a quantidade de mensagens reenviadas.

Janela de monitoramento

O reenvio é acionado automaticamente após o período de monitoramento configurado, sem confirmação de entrega no canal principal.
Se a mensagem for entregue antes desse período, o SMS de reenvio não é enviado.
O reenvio acontece apenas uma vez por destinatário.

Compatibilidade de Contatos

Atualmente, o fallback de WhatsApp para SMS funciona exclusivamente para contatos identificados por números de telefone. Disparos que utilizam a identificação via BSUID não acionarão o gatilho de reenvio automático por SMS.

Disparando a campanha

Nenhuma mudança é necessária no disparo: use SET /dispatch (ou dispatch: true no fluxo combinado) exatamente como em uma campanha sem reenvio configurado. Veja o guia Como fazer disparos de SMS pela plataforma Blip para o formato do disparo, que é o mesmo independentemente do canal principal.

A partir do disparo bem-sucedido, o monitoramento do reenvio começa automaticamente, você não precisa fazer mais nada.

Visualizando resultados

O relatório em CSV da campanha original passa a incluir duas colunas extras quando o reenvio está configurado:

Fell into fallback (Yes/No): indica se aquele destinatário caiu no reenvio (ou seja, falhou no canal original e foi incluído na campanha SMS gerada automaticamente).
Fallback status: status de entrega da mensagem de reenvio para aquele destinatário (mesmos valores usados no status normal de entrega), ou - quando não se aplica.

GET /campaigns/{campaignId}/reports/csv

Esse é o mesmo endpoint de relatório já usado para qualquer campanha, nenhuma chamada adicional é necessária para obter os dados de reenvio:

Se a campanha não tem reenvio configurado, o relatório é gerado exatamente como antes, sem as colunas extras.
Se a campanha tem reenvio configurado mas nenhuma campanha de reenvio foi criada ainda (por exemplo, ainda dentro da janela de monitoramento, ou porque ninguém falhou), todos os destinatários aparecem com No e -.
Se a campanha de reenvio já foi criada, os destinatários que caíram nela aparecem com Yes e o status de entrega atual do SMS.

Cancelando o reenvio

Não existe um endpoint específico para "cancelar só o reenvio". Ao excluir a campanha original (DELETE /campaigns/{campaignId}), o sistema automaticamente:

Cancela o monitoramento agendado, caso ainda não tenha sido concluído.
Remove o template de mensagem de reenvio associado à campanha.

Se a campanha de reenvio já tiver sido criada e disparada antes da exclusão da campanha original, ela não é afetada, a exclusão apenas impede que novos reenvios sejam criados a partir dali.

Perguntas frequentes (FAQ)

1. Se eu configurar o reenvio, isso aumenta o custo da minha campanha?

Sim. Você só paga pelos SMS efetivamente enviados. Se todos os contatos receberem a mensagem no WhatsApp/RCS dentro da janela de monitoramento, nenhum SMS é disparado e não há custo adicional.

2. Posso usar o mesmo texto da mensagem principal para o SMS de reenvio?

Não é recomendado. WhatsApp e RCS permitem mensagens mais longas e com formatação, enquanto o SMS é limitado a 160 caracteres (ou 70 com acentos/especiais) e aceita somente texto simples. Adapte o fallback.message.messageContent para o contexto do SMS.

3. Como sei se o SMS de reenvio foi realmente enviado?

Consulte o relatório CSV da campanha (GET /campaigns/{campaignId}/reports/csv): as colunas Fell into fallback e Fallback status mostram, por destinatário, se ele caiu no reenvio e qual o status de entrega do SMS.

4. O reenvio automático funciona para campanhas individuais e em massa?

Sim. O campo fallback é aceito em qualquer campaignType (INDIVIDUAL, BATCH, USERSFILTER, FROMCAMPAIGN), tanto no fluxo passo a passo quanto no /campaign/full e /campaign/full/v2.

5. Posso agendar uma campanha com reenvio automático configurado?

Sim. Use o campo scheduled normalmente na criação da campanha. O reenvio continua funcionando conforme configurado, aplicando a janela de monitoramento a partir do disparo efetivo (imediato ou agendado).

6. Preciso chamar algum endpoint para disparar o reenvio?

Não. O disparo do SMS de reenvio é automático, decorrida a janela de monitoramento após o disparo da campanha principal.

7. Posso configurar reenvio para uma campanha que já é SMS?

Não. O reenvio é destinado a complementar campanhas RCS ou WhatsApp; a campanha de reenvio em si já é do tipo SMS.

8. O que acontece se vários destinatários falharem ao mesmo tempo?

Todos são incluídos na mesma campanha de reenvio, criada uma única vez por campanha de origem (o sistema não cria uma campanha de reenvio duplicada mesmo que a verificação seja acionada mais de uma vez).

9. Consigo saber o id da campanha de reenvio gerada?

Não é retornado nenhum id de reenvio de forma síncrona (a criação é assíncrona). A forma de acompanhar o resultado é pelo relatório CSV da campanha original, que já traz o status do reenvio por destinatário.

10. Posso alterar o texto do reenvio depois que a campanha já foi criada?

Não. A configuração de reenvio é definida apenas na criação da campanha e não pode ser editada posteriormente pela API.

11. Se eu excluir a campanha antes do disparo, o reenvio configurado é cancelado junto?

Sim. Excluir a campanha (DELETE /campaigns/{campaignId}) remove o template de reenvio e cancela qualquer monitoramento pendente.

Boas práticas

O que fazer:

Mantenha a mensagem de reenvio breve e direta (50–120 caracteres é uma boa referência).
Valide o tamanho do messageContent já com os valores de messageParams substituídos, não apenas o texto com os placeholders.
Teste com uma audiência pequena antes de configurar reenvio em campanhas de grande volume.
Acompanhe as colunas Fell into fallback e Fallback status do relatório CSV para medir a efetividade do reenvio nas suas campanhas.

O que evitar:

Usar acentos, emojis ou símbolos especiais sem necessidade, eles reduzem o limite de caracteres de 160 para 70.
Enviar fallback.channelType sem fallback.message, a criação da campanha será rejeitada.
Reaproveitar cegamente o texto da mensagem principal (WhatsApp/RCS) como texto do SMS, sem adaptar ao limite de caracteres.

Troubleshooting

A criação da campanha falha com erro de validação de fallback

Causa provável: fallback.channelType foi enviado sem fallback.message.
Solução: sempre envie o objeto message completo dentro de fallback quando configurar o canal de reenvio.

O SMS de reenvio não foi enviado, mesmo após a janela de monitoramento

Causa provável: o destinatário não tem um número de telefone válido, ou não houve falha registrada no canal principal para esse destinatário.
Solução: confirme que o recipient da audiência é um número válido e verifique o status de entrega do canal principal no relatório antes de esperar o reenvio.

As colunas de reenvio não aparecem no relatório CSV

Causa provável: a campanha não tem fallback configurado, ou a janela de monitoramento ainda não se encerrou.
Solução: as colunas só aparecem quando fallback foi definido na criação da campanha; se ainda não passou o tempo de monitoramento, os valores aparecerão como No/- até a campanha de reenvio ser criada.

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 😃