Gerenciamento de modelos

O gerenciamento de modelos com a API Verify permite que você personalize a mensagem enviada para fornecer uma OTP aos seus usuários, em vez de usar os modelos padrão da Vonage. Modelos personalizados podem ser configurados para SMS, voz e RCS em qualquer configuração regional compatível.

Estrutura do modelo

Os modelos personalizados são divididos em duas partes:

• O template - ele possui um nome exclusivo e contém um ID, além de indicar se é o modelo padrão. Um modelo é sempre definido como padrão ao ser criado e pode ser alterado posteriormente.

• template_fragments - um modelo pode ter vários fragmentos, que são combinações únicas de locale e channel; isso permite que você crie modelos personalizados em vários idiomas para um único canal. Eles contêm um ID, o texto do modelo e registros de data e hora de criação e atualização.

Ao criar fragmentos, é possível usar quatro variáveis estáticas no texto da mensagem. A única variável obrigatória que a mensagem deve conter é o código, que é representado no texto por ${code}.

Criar um modelo

Para criar um modelo, envie uma solicitação POST para o templates ponto de extremidade. No corpo da solicitação, você precisará fornecer um nome para o modelo:

curl -X POST https://api.nexmo.com/v2/verify/templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{"name": "my-template"
}'

Na resposta, você receberá um template_id, além de alguns links que podem ser usados para visualizar seu modelo e seus fragmentos assim que forem criados:

{
   "template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
   "name": "my-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"
      }
   }
}

O primeiro modelo personalizado que você criar será automaticamente definido como seu modelo padrão, conforme indicado por is_default = true. Para alterar isso, consulte Atualização de um modelo.

Em seguida, você precisará criar fragmentos para cada localidade e canal para os quais deseja usar uma mensagem personalizada.

Criação de fragmentos

Para criar um fragmento, você precisará enviar uma solicitação POST para o template_fragments ponto final. Você deve substituir :template_id com o template_id que você recebeu ao criar seu modelo:

curl -X POST https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "channel": "sms",
   "locale": "en-gb",
   "text": "Thank you for continuing to use ${brand}! Your OTP is: ${code}"
}

No corpo desta solicitação:

• channel especifica o canal ao qual este fragmento se destina e deve ser um dos seguintes: sms, voice, ou rcs.
• locale é o código de localização do idioma em que a mensagem está escrita. Por exemplo, en-gb é o inglês (Reino Unido) e de-de é alemão.
• text é a mensagem que você quer enviar. Isso deve conter o ${code} variável. Outras variáveis estáticas opcionais que você pode incluir são:
  • ${brand} - Será substituído pelo valor do parâmetro “brand” da solicitação de verificação.
  • ${time-limit} - Será substituído pelo período de tempo (número) antes que o código seja considerado vencido.
  • ${time-limit-unit} - Será substituído pela unidade de tempo (segundos, minutos) correspondente ao prazo de validade do código PIN (time-limit).

Essa solicitação criará um modelo de mensagem para um SMS enviado a alguém no Reino Unido. Para criar uma versão dessa mensagem a ser enviada a alguém na França, por exemplo, você enviaria outra solicitação POST com o fr-fr configuração regional e uma diferente text mensagem:

curl -X POST https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "channel": "sms",
   "locale": "fr-fr",
   "text": "Merci de continuer à utiliser ${brand}! Votre OTP est: ${code}"
}

Como Verify escolhe qual modelo usar?

Para determinar o modelo a ser utilizado para uma solicitação, a API Verify seguirá estas etapas:

• Depois que uma solicitação de Verify for enviada, a API utilizará a localidade especificada na solicitação ou detectará a localidade para a qual a solicitação está sendo enviada.
  • Para identificar a localidade, o Verify utiliza o número de telefone fornecido para determinar onde a pessoa está localizada. Por exemplo, 447700900000 será mapeado para en-gb já que é um número do Reino Unido, ao passo que 847700900000 será mapeado para fr-fr já que é um número francês.
  • Se você precisar que uma mensagem seja enviada em um idioma específico, use o locale parâmetro na sua solicitação. Isso pode ser útil em situações como a do Canadá, onde há várias línguas oficiais.

Depois de determinar a localidade a ser usada, o Verify procurará um modelo que corresponda a essa localidade:

• Se você tiver fornecido um template_id Na sua solicitação, o sistema consultará primeiro esse modelo e verificará se você criou um modelo personalizado para essa localidade e canal. Se houver um, ele enviará a mensagem de OTP usando esse modelo.
• Se não houver nenhum, ou se você não tiver fornecido um template_id Na solicitação, o Verify tentará usar um modelo padrão para essa localidade.
  • Se você criou um modelo personalizado, o sistema tentará usar um que tenha is_default definir como “true”.
  • Caso contrário, ele tentará usar um modelo padrão da Vonage.
• Se não for possível encontrar um modelo para essa localidade, ou se você estiver usando uma localidade não suportada nesse canal, o padrão será en_US.

O fluxo completo é ilustrado a seguir:

Outras operações com modelos

Todos os detalhes sobre as operações com modelos podem ser encontrados no Verify a especificação da API, incluindo exemplos de solicitações e respostas. Eles também estão resumidos a seguir:

Visualizando modelos

Você pode listar todos os modelos que criou enviando uma solicitação GET para este endpoint:

https://api.nexmo.com/v2/verify/templates

Ou visualize um modelo específico enviando uma solicitação GET para o mesmo endpoint com o ID do seu modelo:

https://api.nexmo.com/v2/verify/templates/:template_id

Atualização de um modelo

Você pode atualizar o name do seu modelo, além de indicar se o modelo é o padrão, alterando o is_default parâmetro. Para isso, envie um PATCH enviar uma solicitação para este endpoint, substituindo :template_id com o ID do modelo que você está atualizando:

curl -X PATCH https://api.nexmo.com/v2/verify/templates/:template_id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "name": "my-template-updated",
   "is_default": false
}

Excluindo um modelo

Para excluir um modelo, envie uma solicitação DELETE para este endpoint, substituindo :template_id com o ID do modelo que você está removendo:

https://api.nexmo.com/v2/verify/templates/:template_id

Outras operações com fragmentos de modelo

Todos os detalhes sobre as operações com modelos podem ser encontrados no Verify a especificação da API, mas também estão resumidos a seguir:

Visualizando fragmentos de modelo

Você pode listar todos os fragmentos de modelo que criou para um modelo específico enviando uma solicitação GET para este endpoint:

https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments

Certifique-se de substituir :template_id com o ID do modelo cujos fragmentos você deseja visualizar.

Para visualizar um modelo específico, envie uma solicitação GET para o mesmo endpoint com o ID do modelo e o ID do fragmento do modelo:

https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id

Atualização de um fragmento de modelo

Você pode atualizar a mensagem enviada usando seu fragmento de modelo, atualizando o text parâmetro. A localidade e o canal não podem ser atualizados.

Para isso, envie um PATCH enviar uma solicitação para este endpoint, substituindo :template_id e :template_fragment_id com o ID do seu modelo e o ID do fragmento do modelo:

curl -X PATCH https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer XXXXX" \
-d '{
   "text": "The authentication code for your ${brand} is: ${code}"
}

Excluindo um fragmento de modelo

Para excluir um fragmento de modelo, envie uma solicitação DELETE para este endpoint, substituindo :template_id e :template_fragment_id com o ID do seu modelo e o ID do fragmento do modelo:

https://api.nexmo.com/v2/verify/templates/:template_id/template_fragments/:template_fragment_id

Solução de problemas

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 que combine uma localidade e um canal.
• Tentativa de excluir um modelo com fragmentos: Não é possível excluir um modelo se ele tiver fragmentos existentes. Você pode usar o Campos HAL para que, na resposta do modelo `get`, sejam percorridos os IDs dos fragmentos existentes a serem excluídos antes da exclusão do próprio modelo.
• Não usar ${code} no texto: Ao criar um fragmento, é preciso incluir o código dentro do texto.
• Número máximo de modelos: Há um limite de 10 modelos por usuário, e qualquer tentativa de gerar mais resultará em um erro.