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:
Autentique-se no Admin console
Acione o menu Plataforma
No menu Plataforma, acione o item Provedores a partir do caminho, SMS > Configurações > Provedores, para ter acesso à listagem dos provedores de SMS
Na página de listagem de Provedores de SMS, pode-se filtrar os provedores usando a barra de filtragem no topo da listagem
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.
Nota
Para ver alguns exemplos de configurações dos elementos de um provedor de SMS pode-se acessar o Guias do produto na paǵina Configurando um provedor de SMS.
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 "&".
Nota
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.
Nota
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:
to
O número de telefone do destinatário do SMS
${[to]}
displayName
O nome de apresentação do destinatário do SMS.
${[displayName]}
username
O nome de usuário do destinatátio do SMS.
${[username]}
token
O token OTP que será enviado ao destinatário do SMS.
${[token]}
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.
Nota
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:
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:
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:
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.
Cada retorno configurado necessita de 4 valores, que sã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:
O Blazon recebe o retorno da mensagem HTTP enviada ao provedor de SMS;
O processo de elegibilidade compara os dados do retorna da mensagem com os dados do primeiro retorno configurado;
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;
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;
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);
Após isso salva o status na entrada que representa o envio do SMS.
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:
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):
Filtrar o(s) provedor(es) de SMS que se deseja remover;
Selecionar, clicando na caixa de seleção, no(s) provedor(es) que se deseja remover;
Clicar no botão de ação Remover.
Envio de tokens via SMS
O Blazon conta com a possibilidade de envio de SMS usando serviços de provedores de SMS externos. O envio de SMS está previsto em especial nas funcionalidades de autenticação e de troca de senha, para envio do token de validação.
Configurações necessárias
Para que o envio do token via SMS funcione corretamente, é necessário, antes de tudo, configurar os provedores de SMS que serão usados pelo Blazon.
Toda a configuração do provedor de SMS pode ser feita diretamente no Blazon, via admin console e está documentada no guia do admin console nesse link.
Nota
Na prática, apenas um provedor de SMS atende, no entanto é possível configurar quantos provedores sejam necessários e utilizá-los nos serviços de envio de tokens.
Após a configuração dos processadores de SMS é necessário configurar as políticas de troca de senha e/ou a políticas de autenticação que irão usar os provedores para envio de tokens via SMS.
Na política, seja a de troca de senha ou de autenticação, configura-se as opções para envio de token via SMS.
Troubleshooting
Caso algum problema ocorrer, como o SMS não ser enviado, tem-se algumas sugestões de análises:
Verificar/realizar as configurações do provedor de SMS, tais configurações podem ser acessadas na documentação do guia do admin console nesse link;
Verificar algum possível problema na entrada de envio de SMS, as entradas podem ser acessadas no admin console e está documentada nesse link.
Atualizado
Isto foi útil?