Compartilhar:
){kind=small}
Sou ator formado, com uma dissertação sobre stand-up comedy, e comecei a me dedicar ao desenvolvimento em PHP por meio dos encontros da comunidade. Você pode me encontrar dando palestras e escrevendo sobre tecnologia, ou ouvindo e comprando discos curiosos da minha coleção de vinil.
Apresentando o Gerenciamento de Modelos para o Verify
Tempo de leitura: 4 minutos
Os desenvolvedores agora podem personalizar a mensagem enviada com uma senha de uso único (OTP) , em vez de usar o modelo padrão da Vonage. Essa funcionalidade é bastante abrangente; por isso, neste artigo, vamos explicar como implementá-la e como ela funciona.
O gerenciamento de modelos permite que os desenvolvedores alterem a mensagem de envio do OTP por SMS ou Voice em qualquer localidade compatível. Esses modelos são conhecidos como modelos personalizados. Uma nova solicitação de Verify pode detectar a localidade para a qual a solicitação está sendo enviada ou usar uma localidade especificada na solicitação. Verify verifica se você criou um modelo personalizado para essa localidade e canal e o utiliza, caso esteja presente. Caso contrário, ele tenta usar um modelo padrão da Vonage e, se você estiver usando uma localidade não compatível nesse canal, ele finalmente usa en_US como padrão.
O recurso de gerenciamento de modelos consiste em um conjunto de 10 novos pontos de extremidade da API para Verify, programados de acordo com nossos padrões HAL da Vonage.
Existem duas entidades importantes nos modelos personalizados. Como os modelos podem se tornar muito grandes (pense nisso: um modelo usado para 15 localizações nos três canais significa 45 combinações distintas), o modelo personalizado é dividido em duas partes lógicas:
* O template que possui um nome exclusivo e contém um GUID, além de indicar se é o modelo padrão para aquele canal e localidade (eles são sempre definidos como padrão ao serem criados e podem ser alterados posteriormente)
* template_fragments, que são todas entidades com uma relação muitos-para-um com um template. Os fragmentos anexados ao modelo são combinações únicas de locale e channel, que possuem seu próprio GUID, o text conteúdo do modelo e carimbos de data/hora.
Ao criar fragmentos, há algumas variáveis estáticas disponíveis para uso no texto da mensagem. A única coisa importante a se observar aqui é que a mensagem deve conter o código que é representado no texto por ${code}. Existem outras variáveis estáticas reservadas; veja todas elas a seguir:
${code}- o código que o usuário final deve digitar${brand}- o parâmetro “brand” usado na solicitação${time-limit}- número inteiro que representa o prazo de validade${time-limit-unit}- string que representa a unidade de tempo
Vamos percorrer o caminho ideal para mostrar como um modelo personalizado é usado para duas configurações regionais en-gb e fr_fr para envio de SMS. Atualmente, ao se cadastrar na Plataforma de API da Vonage e enviar uma solicitação de teste via SMS, você receberá a seguinte mensagem, supondo que tenha enviado o brand como “ACME”:
ACME code: 5244. Valid for 3 minutes
OK, vamos mudar isso. Primeiro, precisamos criar o modelo usando a seguinte solicitação:
POST https://api.nexmo.com/v2/verify/templates
{
"name": "acme-template"
}Você receberá um código de resposta HTTP 201 informando que ele foi criado:
HTTP 201
{
"template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
"name": "acme-template",
"is_default": true,
"_links": {
"self": {
"href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9"
},
"fragments": {
"href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments"
}
}
}Agora precisamos criar dois fragmentos para nossas duas configurações regionais. Isso é feito por meio das duas solicitações a seguir:
POST https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments
{
"channel": "sms",
"locale": "en-gb",
"text": "Thank you for continuing to use ${brand}! Your OTP is: ${code}"
}
POST https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments
{
"channel": "sms",
"locale": "fr-fr",
"text": "Merci de continuer à utiliser ${brand}! Votre OTP est: ${code}"
}Ambos devem retornar 201 respostas. Nossa personalização está concluída, portanto, há quatro métodos no total para acionar essas duas mensagens:
Esta nova solicitação de Verify de exemplo resultará na mensagem personalizada en_GB :
POST
https://api.nexmo.com/v2/verify
{
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "447700900000"
}
]
}
O motivo pelo qual o en-gb modelo é selecionado automaticamente aqui é porque o Verify detectou que o to número contém um código do Reino Unido, portanto ele é mapeado para o modelo. Você pode, no entanto, especificar o locale modelo a ser usado; assim, um caso de uso poderia ser o envio para um número canadense (onde os idiomas oficiais são tanto o inglês quanto o francês), mas você deseja garantir que o inglês seja usado:
POST
https://api.nexmo.com/v2/verify
{
"locale": "en-gb"
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "17700900000"
}
]
}Essas duas situações também podem ser utilizadas em nossa tradução para o francês.
POST
https://api.nexmo.com/v2/verify
{
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "847700900000"
}
]
}Ótimo! Finalmente, você pode enviar para um número vietnamita, mas especifique que deseja o modelo em francês:
POST
https://api.nexmo.com/v2/verify
{
"locale": "fr-fr"
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "847700900000"
}
]
}
Decidir qual localidade será enviada é, essencialmente, uma “rede”. Como há várias opções, essa árvore de decisão fica assim:
Verify locale logic
É importante observar que, embora possa parecer bastante complexo, não há nenhum “erro” no final do processo. Se tudo mais falhar, você receberá um modelo padrão da Vonage em inglês com um código. Os usuários finais podem não conseguir entender o texto inteiro, mas é muito provável que reconheçam um código após dois pontos.
Aqui estão alguns erros comuns que você pode encontrar ao tentar usar modelos personalizados:
The account is not activated
Embora os modelos de leitura estejam disponíveis para todos os usuários, a criação de modelos personalizados precisa ser habilitada na sua conta. Entre em contato com seu gerente de conta ou com o suporte para habilitar esse recurso.
O modelo ou fragmento já existe
Cada modelo deve ter um nome exclusivo, e cada fragmento nesse modelo deve ser uma entrada única combinada para uma localidade e um canal.
Tentativa de excluir modelo com fragmentos
Não é possível excluir um modelo se ele tiver fragmentos existentes. Você pode usar os campos HAL para descoberta na resposta da consulta “get template” para identificar os IDs dos fragmentos existentes a serem excluídos antes de excluir o próprio modelo.
Não usar
${code}no texto
Ao criar um fragmento, é necessário incluir o código no texto. Se você não fornecer o código ao usuário final, não terá um sistema de autenticação de dois fatores — portanto, a API não permitirá que você faça isso.
Número máximo de modelos
Há um limite de 10 modelos por usuário, e qualquer tentativa de gerar mais do que isso resultará em um erro.
Embora os modelos personalizados sejam uma novidade relativamente significativa no Verify, ainda não terminamos: mais recursos interessantes serão lançados em breve! Enquanto isso, você pode entrar em contato conosco pelo nosso Slack da nossa comunidade se tiver dúvidas ou comentários sobre o Verify.
Compartilhar:
Sou ator formado, com uma dissertação sobre stand-up comedy, e comecei a me dedicar ao desenvolvimento em PHP por meio dos encontros da comunidade. Você pode me encontrar dando palestras e escrevendo sobre tecnologia, ou ouvindo e comprando discos curiosos da minha coleção de vinil.