Send vCards with Ruby and Twilio

Send vCard with Ruby and Twilio

Have you ever sent contact information from one phone to another ? If so, you've likely already encountered vCards or Virtual Contact Files (VCF), the standardized format sharing and importing contact data.

In this blog post we will create a vCard with Ruby and send it to our phones with Twilio's Programmable Messaging API. By the end of this tutorial you will have a Ruby script that generates vCard files and another one that sends vCards to your contacts.

Prerequisites

To follow along with the tutorial, you will need:

• A Twilio account (either free or paid). Create one now if you don't already have one
• A Twilio phone number
• A mobile/cell phone capable of sending and receiving SMS
• The latest version of Ruby installed on your machine (I use RVM, and recommend you to use a manager, but this is not mandatory)
• Your preferred Ruby editor or IDE

Right. Let's start coding!

Create the project directory

Create a new folder vcard-project on your computer, wherever you store your Ruby projects.

Install the required dependencies

Next, we need to install the following Gems:

• bundler: for avoiding permissions error
• vCardigan: to generate the vCard
• twilio-ruby: to simplify sending SMS through Twilio's Programmable Messaging API

First, let’s install bundler:

On macOS / Linux / *BSD

Open your preferred terminal emulator and run the following:

On Microsoft Windows

Open a command prompt with administrative rights and run the following:

Now, let's install the remaining two dependencies. Create a new file named Gemfile, then paste the code below into the file.

Now, install the vcardigan and twilio-ruby Gems by running the following command:

Generate the vCard

Next up, create a new file named vcard.rb, then open it with your favorite text editor or IDE. Then, add the code below to the file.

After that, replace the three placeholders, Your_Name, Your_Phone_Number, and Your_Email, with  your full name, phone number, and email address, respectively.

This code creates a version 2.1 formatted vCard with your full name, phone number, email, and their types, and an extra link to the Twilio blog. There are a number of fields you can add to a vCard. In this tutorial, however, we only cover a few for sakes of simplicity.

Generate the VCF file

For this we will use Ruby's File library using the code below. add it to the end of vcard.rb.

The code generates a new file named vcard.vcf in the current directory, writes the content of the vcard into it, and closes the file.

Run the code below to generate the .vcf file on your computer.

If you list the files in your current directory you should see a vcard.vcf file next to vcard.rb. Take note of the path, we will need it right after.

Make the vCard publicly accessible

Now, we need to make the vCard accessible on the internet, so that Twilio can send it with an SMS. To do that, we'll store the file as a Twilio Asset.

To do that, head to Assets in the Twilio Console and click the blue Add an Asset button. Then, add the vCard from your computer. Leave the asset set to public, as you want to share your contacts with the outside world. Now, click Upload to finish uploading the file. Once the upload is complete, you will see a URL for this new asset. Save it for later.

Set the required environment variables

Next, in the Twilio console, go to the main dashboard and grab your Account SID and Auth Token and add them to your env. Please use ACCOUNT_SID and AUTH_TOKEN for them, respectively.

Add code for sending the vCard

Let’s create a new file called vcard_sender.rb and fill it with:

• from to your Twilio phone number — in E.164 format, e.g., +442071838750
• body to any text you fancy
• media_url to the link to the vCard you uploaded to Twilio Assets

Test that the code works as expected

Everything is now ready: our code will send an SMS to a phone number of our choice that we will specify. It can be your number if you like. Make sure to write the number in E.164 format.

All that’s left is to run the code, by replacing <Your Phone Number>  in the command below with your mobile/cell phone number, before running it:

The recipient will receive an SMS containing your text message and the link to your vCard. Upon clicking the link, a file will download on their phone. Opening the link will add the new contact to their contacts list.

By now you have learnt:

• How to generate vCards (VCF) files using Ruby
• How to host assets on Twilio
• How to send an SMS containing a file using Ruby and Twilio
• How to use arguments from the Ruby CLI in your code, through bundler !

If you’ve found this tutorial cool, you might want to check out some other Ruby tutorials I wrote (or click the link from my contact to see the full list!) :

• 5 ways to make HTTP requests in Ruby
• Building Voicemail with Twilio and Ruby
• Coding a Rails lookup app for my grandparents

I can't wait to see what you build!

Valériane Venance was a Developer Evangelist at Twilio. You can find her on LinkedIn. Let her know if you’ve built something cool with Ruby. She’d love to hear about it!