SMS

A plataforma permite a configuração de provedores de SMS para o envio de mensagens. Em termos gerais, essa configuração consiste na integração com uma API via HTTP que oferece esse serviço. Ou seja, o Blazon consumirá a API do provedor de SMS para realizar os envios.

Na prática, para cada SMS enviado, o Blazon fará uma requisição HTTP ao provedor, contendo informações como destinatário e conteúdo da mensagem. O provedor, por sua vez, processará o envio da mensagem ao destinatário e retornará a resposta ao Blazon.

Acessando um provedor SMS

Para acessar a configuração de um provedor de SMS, basta seguir os passos:

1. Autentique-se no Admin console

2. Acione o menu Plataforma

3. No menu Plataforma, acione o item Provedores a partir do caminho, SMS > Configurações > Provedores, para ter acesso à listagem dos provedores de SMS

4. Na página de listagem de Provedores de SMS, pode-se filtrar os provedores usando a barra de filtragem no topo da listagem

5. Escolha um provedor de SMS e clique nele para poder editá-lo, ou clique no botão Adicionar Provedor pra criar uma nova configuração.

Configurando um provedor SMS

Para configurar um provedor de SMS, seja uma nova configuração ou uma edição de uma configuração existente, tem-se a tela de detalhamento.

Na tela de detalhamento, clique na aba Configurações para poder configurar um provedor de SMS.

Na tela de configuração principal do provedor tem-se, na parte superior, a configuração dos parâmetros do Método HTTP e da URL do provedor.

Logo abaixo, na seção inferior, tem-se 5 abas de configurações, são elas:

• Parâmetros Query

• Segurança

• Cabeçalhos

• Body

• Retornos

Nas subseções abaixo tem-se o detalhamento de cada configuração dessas.

Parâmetros Query

Nessa aba pode-se configurar os parâmetros de "queryString" da requisição HTTP ao provedor de SMS. Esses parâmetros representam os pares chave=valor definidos na URL após o caractere "?" onde cada par é separado de outro par pelo caractere "&".

A especificação dos parâmetros de queryString, bem como das demais partes de uma mensagem HTTP, pode ser encontrada na documentação de referência RFC 2616.

Nesse card, basta adicionar cada nome de parâmetro seguido do seu valor, clicando sempre no botão Adicionar.

Pode-se adicionar parâmetros com valores literais ou parâmetros com valores que representam uma expressão do framework Spring.

As expressões do Spring framework (ver Spring Expression Language) permitem combinar valores literais e valores de variáveis juntamente com operadores, gerando expressões que serão avaliadas no momento do envio do SMS.

Lista de parâmetros disponibilizada

O Blazon disponibiliza 4 parâmetros com valores do contexto do SMS que será enviado e podem ser usados em expressões, são eles:

Parâmetro	Descrição
to	O número de telefone do destinatário do SMS
displayName	O nome de apresentação do destinatário do SMS.
username	O nome de usuário do destinatátio do SMS.
token	O token OTP que será enviado ao destinatário do SMS.

Usando os parâmetros de query

Na tabela abaixo tem-se 3 parâmetros de query exemplificando essas configurações em um provedor de SMS.

Nome	Valor
username	${[username]}
token	${[token]}
role	manager

No caso acima tem-se a configuração onde os dois primeiros parâmetros usam uma expressão pra fazer bind com uma lista de parâmetros que são enviados ao provedor no momento do envio do SMS. O terceiro parâmetro está com seu valor literal 'manager'.

Considerando que no momento do envio de um SMS o parâmetro ${[username]} seja substituido por fulano, e o parâmetro ${[token]} seja substituido por 3324 e a URL definida seja algo como https://sms-provider-x/send, tem-se a seguinte URL final:

https://sms-provider-x/send?username=fulano&token=3324&role=manager

Segurança

Na aba da subseção Segurança, pode-se configurar o modelo de autenticação que será usado no provedor de SMS. Tem-se 3 possíveis valores:

• Nenhum

• Autenticação HTTP básica

• Bearer token

A configuração com o valor Nenhum, significa que a requisição HTTP para o provedor não necessita de informação de autenticação.

Já a configuração com o valor Autenticação HTTP básica, significa que a requisição para o provedor necessita de autenticação básica com o par username e senha codificados no padrão base64 e separados por ":".

Nesse caso basta inserir o par username e senha nos campos da configuração na tela

Já a configuração com o valor Bearer token, significa que a requisição para o provedor usa autenticação baseada em um token "ao portador" obtida de um servidor.

Nesse caso basta inserir o token no campo da configuração na tela.

Cabeçalhos

Na aba da subseção Cabeçalhos, pode-se configurar as informações de cabeçalho da requisição HTTP ao servidor SMS.

Essas informações tem a configuração similar à configuração dos Parâmetros Query e também aceita uma expressão Spring com bind de valores.

Exemplo de algumas configurações de cabeçalhos comuns:

Cabeçalho	valor
Accept	application/json
Content-Type	application/json
Accept-Language	*
Username	${[username]}

Basta adicionar o par nos campos nome e valor, e clicar no botão Adicionar.

Body

Na aba da subseção Body, pode-se configurar o corpo da mensagem HTTP da requisição ao provedor SMS. Tem-se 4 possíveis valores para essa configuração:

Configuração	Descrição
None	Nenhuma mensagem será enviada no corpo da requisição HTTP ao provedor
form-data	Utilizado quando os dados precisam ser enviados em partes separadas, com fronteiras (boundaries), permitindo incluir arquivos e metadados. Ver RFC 2616.
x-www-form-urlencoded	Utilizado quando os dados do formulário são enviados como pares chave=valor, codificados de maneira semelhante aos parâmetros de queryString de uma URL. Ver RFC 2616.
raw	Quando o conteúdo da mensagem HTTP segue no formato raw, significa que ele é enviado exatamente como está, sem formatação especial como form-data ou x-www-form-urlencoded. Esse formato é útil quando a requisição precisa enviar dados estruturados de maneira personalizada.

Usando a configuração com o valor raw, permite nos definir um dentre 3 formatos disponíveis:

Formato
application/json	O conteúdo da mensagem HTTP será um conteúdo no formato JSON.
application/xml	O conteúdo da mensagem HTTP será um conteúdo no formato XML.
text/plain	O conteúdo da mensagem HTTP será texto sem formatação plano.

Retornos

Na aba de configuração de Retornos pode-se configurar uma lista de possíveis retornos das mensagens HTTP do provedor de SMS.

No momento do retorno da mensagem HTTP pelo provedor de SMS, o Blazon executa um processo de elegibilidade. Com base na ordem pré-configurada desses retornos, ele determina o tratamento adequado para a mensagem recebida.

Sempre existe uma configuração de retorno Default (padrão), que será aplicada caso nenhum outro retorno configurado case com os dados do retorno da mensagem do provedor de SMS.

Cada retorno configurado necessita de 4 valores, que são:

Campo	Descrição
Tipo	Define o tipo do retorno configurado, que pode ser Código HTTP ou Script.
Valor	Nesse campo deve ser definido o valor do código HTTP ou o script beanShell dependendo do tipo do retorno selecionado.
Status	Define se o status do retorno foi Sucesso ou Falha.
Situação	Define o texto de retorno que representa o status da resposta.

Elegibilidade do retorno

No momento que um SMS é enviado pelo provedor de SMS, ao destinatário, o retorno da mensagem HTTP passa por um processo de elegibilidade considerando as configurações de retornos definidas para o provedor.

Esse processo de elegibilidade irá analisar os dados da resposta da mensagem HTTP do provedor de SMS e tentar achar uma configuração de retorno que case com os dados, seguindo a ordem de configuração desses retornos. O processo de elegibilidade do retorno funciona da seguinte forma:

1. O Blazon recebe o retorno da mensagem HTTP enviada ao provedor de SMS;

2. O processo de elegibilidade compara os dados do retorna da mensagem com os dados do primeiro retorno configurado;

3. Caso a comparação dê certo, então o Blazon aplica o status do retorno que foi elegido como status do retorrno da mensagem do provedor de SMS e salva na entrada que representa o envio do SMS;

4. Caso a comparação não dê certo, então o Blazon tenta comparar o próximo retorno na ordem até achar um que case com os parâmetros do retorno do provedor;

5. Caso nenhum retorno configurado case com os dados do retorno da mensagem HTTP do provedor de SMS, então o Blazon aplica o status definido no retorno padrão (Default);

6. Após isso salva o status na entrada que representa o envio do SMS.

Exemplo de configuração de retornos

Como exemplo da configuração de retornos possíveis, tem-se abaixo, uma configuração de três retornos:

1. Exemplo de "retorno" do tipo código HTTP:

Campo	Valor
Tipo	Código HTTP
Valor	200
Status	Sucesso
Situação	OK

2. Exemplo de "retorno" do tipo script beanShell:

Campo	Valor
Tipo	Script
Valor	return httpResponse.httpCodeStatus == 404;
Status	Falha
Situação	Not found

No exemplo acima o script beanShell irá comparar o código de retorno da mensagem HTTP com o valor 404.

3. Exemplo de "retorno" padrão (Default)

Campo	Valor
Tipo	DEFAULT
Valor	-
Status	Sucesso
Situação	OK

Variáveis disponibilizadas no script beanShell

Um retorno do tipo script beanShell, irá comparar os dados do retorno da mensagem HTTP executando um script beanShell. O interpretador do script disponibiliza um objeto httpResponse no contexto da execução do script.

O objeto httpResponse contem 5 variáveis que podem ser usadas no script beanShell, são elas:

Nome da variável	Tipo	Descrição
payload	String	Conteúdo do corpo da mensagem HTTP de retorno.
httpStatus	String	String de status da mensagem HTTP de retorno.
httpCodeStatus	Integer	Código de status da mensagem HTTP de retorno.
headers	Map<String, String>	Cabeçalhos da mensagem HTTP de retorno.
contentType	String	Tipo do conteúdo do corpo da mensagem HTTP de retorno.

Removendo um provedor SMS

Para remover um provedor de SMS configurado, basta primeiramente acessar a listagem de provedores (ver seção Acessando um provedor SMS):

1. Filtrar o(s) provedor(es) de SMS que se deseja remover;

2. Selecionar, clicando na caixa de seleção, no(s) provedor(es) que se deseja remover;

3. Clicar no botão de ação Remover.