Como enviar SMS via API

Índice:

1. Novo processo para o disparo de SMS
2. Como solicitar a criação de templates
3. Disparo de SMS via API
4. Boas Práticas do Canal SMS
5. Suporte

Estamos aprimorando nossos serviços para garantir a segurança e a eficiência da nossa plataforma. Nesse contexto, gostaríamos de informar sobre algumas alterações significativas no canal SMS e a implementação de medidas de segurança adicionais.

Novo processo para o disparo de SMS

A partir de agora é necessário criar e aprovar um template para os disparos de SMS (também conhecido como Message Template). Ao contrário dos templates de mensagem do WhatsApp que são criados no Blip ou diretamente na conta do WhatsApp da sua empresa, no canal SMS é necessário abrir uma solicitação no nosso sistema de suporte com o conteúdo da mensagem desejada. O time analisa a conformidade do conteúdo solicitado, antes de disponibilizá-lo para uso.

A informação do template é registrada em nossa base de dados, adicionando uma camada extra de segurança à utilização do canal. Essa medida visa prevenir o envio de mensagens maliciosas para números associados a canais de clientes, garantindo a proteção e integridade do processo de comunicação.

Como solicitar a criação de templates

Para solicitar a criação de templates para seus disparos de SMS, você precisa abrir  uma requisição através do nosso sistema de suporte, pelo site ou pelo WhatsApp, com no mínimo 48 horas úteis de antecedência à utilização do template. Essa requisição precisa ter o conteúdo da mensagem que será utilizada no momento do disparo do SMS, para que o time consiga analisar e criar o template de forma assertiva, evitando quaisquer erros futuros.

Antes de criar seu template mensagem, se atente ao número de caracteres e aos caracteres especiais da sua mensagem, visto que para cada quantidade de mensagem há um tipo de cobrança. Além disso, imagens e vídeos são enviados por meio de um link que redireciona para a imagem/vídeo enviado. É permitido o uso de variáveis nos templates. Para isso, você deve indicar os pontos específicos do texto onde as variáveis serão utilizadas, colocando o conteúdo entre {{}} e especificando o tipo de cada variável (somente texto, somente números ou alfanumérica). 

O texto de um SMS pode conter até 160 caracteres, porém ao usar caracteres especiais, todos os caracteres das mensagens vão ser contados de uma forma diferente e o limite da mensagem passa a ser 70 ao invés de 160. Veja mais detalhes na sessão de Disparo de SMS via API abaixo.

Observação: os caracteres das variáveis também são contabilizados na quantidade total de caracteres da mensagem.

Requisição: Agora que você já criou a estrutura do seu template seguindo as orientações acima, abra uma requisição com o nosso time de suporte, seguindo o exemplo abaixo:

Assunto da requisição: criação de template canal SMS

Conteúdo da requisição: incluir aqui a descrição do texto que você deseja que seja implementado no template. Ex:

Exemplos 1:

“Oi {{1}}! Seu ingresso esta disponível neste momento no site www.blipid.com.br/{{2}}”

{{1}} = variável de texto

{{2}} = variável alfanumérica (texto e números)

Quantidade de caracteres, sem o conteúdo das variáveis: 74

Exemplos 2:

“Seu código é: {{1}}”

{{1}} = variável numérica, de 6 algarismos

Quantidade total de caracteres do template: 19

Exemplos 3: 

“Oferta EXCLUSIVA para quitar a sua divida hoje, {{1}}! Não perca a oportunidade: https://blipbank.com.br/{{2}}”

{{1}} = variável de texto

{{2}} = variável alfanumérica (texto e números)

Nesse exemplo, observe que incluímos as palavras sem os acentos corretos, para evitar que sejam transformados em caracteres especiais e haja redução do limite de caracteres.

Quantidade de caracteres, sem o conteúdo das variáveis: 100

Disparo de SMS via API

O processo de envio de SMS via API é bem simples. Siga os passos a seguir para realizar o seu disparo:

Observação: Imagens e vídeos: são enviados por meio de um link que redireciona para a imagem/vídeo enviado. 

Antes de enviar sua mensagem, se atente ao número de caracteres e aos caracteres especiais da sua mensagem, visto que para cada quantidade de mensagem há um tipo de cobrança.

O texto de um SMS pode conter até 160 caracteres, porém ao usar caracteres especiais, todos os caracteres das mensagens vão ser contados de uma forma diferente e o limite da mensagem passa a ser 70 ao invés de 160.

 

Exemplo de caracteres considerados especiais:   (ç, á, ã, etc.)

 

Atenção: Devido ao protocolo de funcionamento de envio do SMS, ao realizar o envio de uma mensagem que exceda o limite de caracteres de uma mensagem, o envio de SMS múltiplo consome alguns caracteres da mensagem para conseguir unir o texto no destino. Ou seja, para uma mensagem com carácter especial (limite 70 caracteres para contar como 1 SMS) um texto de 140 caracteres não irá cobrar duas mensagens e sim três, já que o envio da mensagem irá consumir 3 caracteres de cada parte da mensagem. Para o envio de uma mensagem com limite de 160, o envio irá consumir 7 caracteres de cada parte da mensagem.

Exemplo de limite de caracteres

Quantidade Caracteres	Limite por Divisão da mensagem	Quantidade de Mensagens
70 (com especial)	70	1
71 (com especial)	67	2
135 (com especial)	67	3
160	160	1
320	153	3

Exemplos de palavras e seu número de caracteres devido ao uso de caracteres especiais, note que esses caracteres estão em negrito:

Palavra	Limite de caracteres da mensagem
Olá	70
Ola	160
Atenção!	70
Atencao	160

 

Segue abaixo, um exemplo de envio de mensagem com seu número de caracteres e a quantidade de mensagens devido ao uso de caracteres especiais.

Mensagem	Número de caracteres	Quantidade de Mensagens
Olá pessoal!! Tudo bem com vocês? Atenção, essa é uma mensagem de teste de envio de SMS. Você foi premiado com R$ 10.000 reais em bônus acesse o Instagram @testeDeMensagem e confira!	193	3
Ola pessoal! Tudo bem? Atencao essa e uma mensagem de teste de envio de SMS. Voce foi premiado com 10 mil reais em bonus acesse o link e confira.	147	1

(Tabela de caracteres considerados como “não especial”)

1) Requisições 

Para enviar um disparo via API é necessário que você acesse algum aplicativo de requisições HTTP, por exemplo, o Postman. Caso não tenha instalado, você pode acessar aqui: 

Além disso, apenas para fins de informação, a maioria das requisições dessa documentação vão possuir os campos abaixo:

Campo	Digite a informação
Id	Identificador único da mensagem
to	Digite o número de telefone de quem receberá a mensagem (“+” + DDI + DDD + 9º dígito) + @sms.gw.msging.net. Por exemplo: +5511988887777@sms.gw.msging.net
type	text/plain
content	Digite o texto da mensagem desejada e o template criado;

 

Observação: no campo “to” é obrigatório incluir o “+” antes do DDI, uma vez que o “+” é utilizado para SMS internacional.

 

Para gerar o id das requisições abaixo, você pode gerar manualmente ou por meio de um gerador gratuito de GUID.  

• Link da Guideline do GUID pela Microsoft: Guid.NewGuid Método (System) | Microsoft Docs
• Link do gerador online e gratuito de GUID: Free Online GUID Generator

2) Disparo individual

Caso deseje enviar um SMS para apenas um número, seu disparo será individual. 

1. Primeiro, utilize a requisição ‘Send a Message’. Você pode acessar mais detalhes sobre essa requisição em: Blip Docs | API Reference
2. Modifique o campo ‘to’ para o seguinte padrão abaixo.  Esse campo indica para quem você deseja enviar a mensagem:

“+” + DDI + DDD (com o 9º dígito incluso) + número de telefone + @sms.gw.msging.net

 

Número	Número com Padrão
+5511988887777	+5511988887777@sms.gw.msging.net

4) No campo ‘content’, que representa o conteúdo da mensagem, adicione o texto da mensagem desejada e o template criado.

5) Selecione a opção “POST” para definir o tipo de requisição e envie. 

6) Sua requisição seguirá o seguinte modelo:

 

6) Pronto, você realizou um disparo de SMS via API!

3) Múltiplos Disparos:

Caso deseje enviar um SMS para vários números, seu disparo será para múltiplos contatos.

• Crie uma lista de distribuição usando a requisição ‘Create a List’, método POST. Você pode acessar mais detalhes sobre essa requisição em: Blip Docs | API Reference
• Com a lista criada, adicione os usuários que deseja impactar usando a requisição ‘Add a member to a list’ (Adicione um membro em uma lista) seguindo o formato abaixo.  Você pode acessar mais detalhes sobre essa requisição em:  Blip Docs | API Reference. 

{{número completo do usuário com o nono dígito}}@sms.gw.msging.net.

• Para enviar a mensagem, use a requisição ‘Send a message’ com o nome completo da lista criada no campo ‘to’, o conteúdo da mensagem e o template no campo ‘content’. Você pode acessar mais detalhes sobre essa requisição em: Blip Docs | API Reference.

Pronto, você realizou um disparo de SMS via API!

Boas Práticas do Canal SMS

1) Ative SMS em um chatbot exclusivo para SMS

Para facilitar o controle de mensagens, indicamos que o fluxo de SMS seja exclusivo para um chatbot de SMS, ou seja, não é recomendado ativar SMS num chatbot que tenha fluxo do WhatsApp. Nesse caso, crie um chatbot a parte apenas para o fluxo de SMS.

Caso você ative o SMS num chatbot que tenha fluxo de WhatsApp e acione um componente interativo, como por exemplo: botões ou conteúdos dinâmicos, como esses componentes não existem no SMS e ambos os canais estão utilizando o mesmo fluxo, o componente não será enviado no formato esperado e ainda poderá ser cobrado uma quantidade maior de mensagens devido à quantidade de caracteres que esse comportamento irá gerar. Dessa forma, a mensagem não funcionará da forma prevista, será muito extensa e ainda vai possuir vários caracteres especiais que serão contabilizados financeiramente.

Tipos de mensagens permitidas no SMS	Tipos de mensagens não permitidas no SMS
Textos	Botões
Imagens*	Quick Reply
Vídeo	Menu
Web link	Áudio
	Carrossel
	Pesquisa
	Localização
	Conteúdo Dinâmico

Imagens e vídeos: são enviados por meio de um link que redireciona para a imagem/vídeo enviado.

 

2) Para enviar somente mensagens ativas não é necessário fluxo de chatbot

Caso você queira somente enviar mensagens para o seu usuário, sem necessidade de receber as respostas dessa mensagem, basta realizar sua ativação de SMS num chatbot que não possua fluxo no Builder. Caso esse fluxo exista, esperando respostas do usuário e dando prosseguimento à “conversa” entre o cliente e o chatbot, haverá a contabilização do pagamento devido à continuidade de mensagens enviadas.

 

Observação: Para verificar o status das notificações enviadas, você precisa consultar o evento:

Primeiro você precisa pegar o identificador da mensagem ativa enviada via API nos links:

• Get last messages (per user identity) 
• Get logged messages (all users) 

Depois, pegar o status dessa mensagem ativa em específico usando a seguinte requisição:

• Get notifications of a message 

Possíveis eventos (status):

• event: Event related to the message. The recipient's events depend on the channel and may not be available. The valid values are:
• accepted: The message has been accepted by the server.
• dispatched: The message has left the server and was dispatched to recipient.
• received: The recipient has received the message.
• consumed: The recipient has read the message.
• failed: The message has failed. In this case, the property reason must be present.
• reason: In case of failed events, it represents the reason of the message failure. It contains the following properties:
• code: The failure's numeric code. This value is mandatory.
• description: Failure's description message.

Suporte

Estamos comprometidos em oferecer suporte contínuo durante esse período de transição. Nossa equipe de suporte está à disposição para auxiliá-lo no processo de solicitação de templates, e ajudar em qualquer dúvida caso seja necessário.

Agradecemos pela compreensão e colaboração durante este processo de aprimoramento da segurança. Estamos confiantes de que essas mudanças fortalecerão ainda mais a confiabilidade dos nossos serviços.

Para mais informações, acesse a discussão sobre o assunto em nossa comunidade ou os vídeos no nosso canal. 😃