Voice Verify API - Tutorial: Send a voice message with verification code with Telesign Ruby SDK

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This tutorial teaches you how to use Telesign Voice Verify API with a Ruby SDK, by walking you step-by-step through the creation of an integration where you send your own verification code to an end-user. Skip to the end of this page to see the full, completed sample code.

Before you begin

Make sure you have the following before you start:

• Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.
• Testing device: A mobile phone on which you can receive a call.

📘

NOTE:

This tutorial uses the following:

• MacOS
• Ruby 3.3.6

Please modify accordingly if your developer environment differs from these details.

Set up your project

1. Follow the Telesign Full-service Ruby SDK install instructions here on GitHub incorporating these details:

   • Use voiceVerify as the project name.

   You should end up in the top-level directory for your project in the Terminal.

2. Create a new file called send_voice.rb and open it in your editor.

touch send_voice.rb

Send a voice message with a verification code

1. Follow the steps below or copy the sample code into the file and update it accordingly.
2. Import these dependencies from the SDK.

require 'telesign'
require 'telesignenterprise'

3. Define variables to store your authentication credentials.

customer_id = ENV['CUSTOMER_ID'] || 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = ENV['API_KEY'] || 'ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

4. Define a variable to hold the phone number you want to get information for. Use the complete number, including the country code. This should be a string with no spaces or special characters. For example: 16505551212.

phone_number = ENV['PHONE_NUMBER'] || '11234567890'

📘

NOTE:

In your production integration, pull the phone number from your recipient database instead of hardcoding it.

5. Generate a verification code.

verify_code = random_with_n_digits(5)

6. Create a VerifyClient object and pass it your customer_id and api_key.

verify_client = TelesignEnterprise::VerifyClient.new(customer_id, api_key)

7. Send a voice message containing the verification code you created. Store the results of your request in the response variable.

response = verify_client.voice(phone_number, verify_code: verify_code)

8. Have the end user input the verification code they received, then check it to see if it is valid. Print the results of the check.

print 'Please enter the verification code you were sent: '
user_entered_verify_code = gets.strip

if verify_code == user_entered_verify_code
  puts 'Your code is correct.'
else
  puts 'Your code is incorrect.'
end

Test your integration

1. Switch from your editor to the terminal and run:

ruby send_voice.rb

If all goes well, you should send a voice message containing a verification code to the phone number you selected. If you are testing with your phone, you should be able to enter the verification code in response to a prompt from your terminal. The sample will then check your verification code to see if it matches the verification code that was sent and report on the results.

Send a Voice Message with Verification Code in a Different Language

This section explains how to send a custom voice message in a different language using Voice Verify API. A sample is provided here if you want to cut and paste. Note that the only difference between this code sample and the previous code sample in this tutorial is that you use the tts_message (text-to-speech) parameter to enter a custom message, and the language parameter to specify the language. For a list of language codes, refer to - Voice Verify API - Supported languages for text-to-speech.

require 'telesignenterprise'

customer_id = ENV['CUSTOMER_ID'] || 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = ENV['API_KEY'] || 'ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = ENV['PHONE_NUMBER'] || '11234567890'
language = 'fr-FR'
tts_message = 'Votre code de vérification Widgets \'n\' More est $$CODE$$.'

verify_client = TelesignEnterprise::VerifyClient.new(customer_id, api_key)
response = verify_client.voice(phone_number, language: language, tts_message: tts_message)

Sample code

require 'telesign'
require 'telesignenterprise'

customer_id = ENV['CUSTOMER_ID'] || 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = ENV['API_KEY'] || 'ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = ENV['PHONE_NUMBER'] || '11234567890'
verify_code = Telesign::Util.random_with_n_digits(5)

verify_client = TelesignEnterprise::VerifyClient.new(customer_id, api_key)
response = verify_client.voice(phone_number, verify_code: verify_code)

print 'Please enter the verification code you were sent: '
user_entered_verify_code = gets.strip

if verify_code == user_entered_verify_code
  puts 'Your code is correct.'
else
  puts 'Your code is incorrect.'
end