Phone ID - Tutorial: Perform a number deactivation check with Telesign Ruby SDK

📘

NOTE:

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

This tutorial explains how to check whether a phone number was deactivated using the Phone ID Number Deactivation identity attribute with the Telesign Ruby SDK. You can use the check to decide whether to send someone an SMS or Voice message. If someone's number is not active, you can save the cost of attempting to send a message. Skip to the end of this page to see the full sample code.

Before you begin

Make sure you have the following ready:

• Authentication credentials - Your Telesign Customer ID and API Key. If you don't have these already, see How do I find my Customer ID and API Key?
• Identity attribute enabled - Make sure the Number Deactivation identity attribute is enabled by Telesign. If it is not yet enabled, contact a Telesign expert.

📘

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 phoneidTest 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 phone_id_deactivation_check.rb and open it in your editor.

   Terminal

   touch phone_id_deactivation_check.rb
   

Make Number Deactivation request

1. Follow the steps below or copy the sample code into a file and update accordingly.

2. Import this dependency from the SDK.

   Ruby

   require 'telesignenterprise'
   

3. Define variables to store your authentication credentials.

   Ruby

   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 perform a number deactivation check on. This should be a string with no spaces or special characters. Use the complete number, including the country code. For example: 16505551212.

   Ruby

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

   📘

   NOTE:

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

5. Define a variable to hold the ucid which is the use case code that provides information about what kind of transaction you are performing.

   Ruby

   ucid = 'ATCK'
   

6. Instantiate a phoneid_client object containing your Customer ID and API Key.

   Ruby

   phoneid_client = TelesignEnterprise::PhoneIdClient.new(customer_id, api_key)
   

7. Perform a number deactivation check, and store the results in the response variable.

   Ruby

   response = phoneid_client.number_deactivation(phone_number, ucid)
   

8. The results stored in the response variable are provided to you in this step as shown in the sample code.

   Ruby

   if response.ok
     if response.json['number_deactivation']['last_deactivated']
       puts 'Phone number %s was last deactivated %s.' %
                [response.json['number_deactivation']['number'],
                 response.json['number_deactivation']['last_deactivated']]
     else
       puts 'Phone number %s has not been deactivated.' %
                response.json['number_deactivation']['number']
     end
   end
   

   📘

   NOTE:

   Use putsto display the output in the console for debugging purposes. In your production code, you would likely remove this from your code.

Test your integration

1. Switch from your editor to the terminal and build your project. Make sure you are in the top-level directory of your project.

   Terminal

   ruby phone_id_deactivation_check.rb
   

You should receive a response containing details about whether your phone number is active or not. You can use these results to make decisions about what to do with the phone number. For example, if someone is trying to sign up for an account with an inactive number, you might require them to sign up using a different number. Or, if you needed to send the provided number a code via text or voice message, you might opt not to send the message since it will not reach a deactivated number.

Sample code

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'
ucid = 'ATCK'

phoneid_client = TelesignEnterprise::PhoneIdClient.new(customer_id, api_key)
response = phoneid_client.number_deactivation(phone_number, ucid)

if response.ok
  if response.json['number_deactivation']['last_deactivated']
    puts 'Phone number %s was last deactivated %s.' %
             [response.json['number_deactivation']['number'],
              response.json['number_deactivation']['last_deactivated']]
  else
    puts 'Phone number %s has not been deactivated.' %
             response.json['number_deactivation']['number']
  end
end