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.
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 "&".
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.
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
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.
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=managerSeguranç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.
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.
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:
Tipo
Código HTTP
Valor
200
Status
Sucesso
Situação
OK
2. Exemplo de "retorno" do tipo script beanShell:
Tipo
Script
Valor
return httpResponse.httpCodeStatus == 404;
Status
Falha
Situação
Not found
3. Exemplo de "retorno" padrão (Default)
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:
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.
Atualizado
Isto foi útil?