Nexmo SMS Contest App

by slorello89


Nexmo SMS Contest App


An app to run booth contests by SMS.


Installation and Usage

In order to properly use this application you need to create a free Nexmo account, and provision a Nexmo virtual number. Once you have done so, you then need to assign an inbound SMS webhook URL to that number in your Nexmo Dashboard. This webhook URL must be externally accessible. Many people find using ngrok helpful for making their local server externally available during development. The application has the route /webhooks/receive already defined in routes.rb configuration, as such it is easiest to provide that path with your externally accessible URL as your webhook to receive text messages.

Next you need to create the database schema by running rake db:migrate from your command line, and also installing all the dependencies outlined in the Gemfile by running bundle install.

Then, you need to provide your API credentials for Nexmo and your Nexmo number in your application. Your credentials are stored in a .env file in the root folder of your project. You can rename the sample .env.sample file to .env and input your values for the keys or create a new .env file, whichever you prefer.

The credentials you must provide are your Nexmo API Key, API Secret and your Nexmo provisioned phone number. Your credentials are stored in the following manner:


Lastly, run the Nexmo generator to create your Nexmo client instance by running rails generate nexmo_initializer from the command line.

Once that is finished you can start your Rails server by running rails s from your terminal.

You can now text your application by sending a message to your Nexmo number.

Text messages are to be sent in the following format to be considered valid (the Twitter handle field is optional):

{name} -- {twitter handle} -- {email} -- {message}

SMS Concatenation for multiple SMS messages works differently by region and even by different carriers in the same region. As such it is better if contest entries are kept short. The {message} segment of the text should not be longer than a sentence.

Deploying to Heroku

You can deploy the application directly from this GitHub repository by clicking on the Deploy to Heroku button at the top of this README. Once you do that you still must set your Nexmo API credentials and information in Heroku. You can either do so at the time you are initializing your application after you have the clicked the Deploy to Heroku button above, or after from within the Heroku Dashboard.

After you have clicked the above Deploy to Heroku button, you will see three config vars in the Heroku deployment settings. Add your Nexmo API credentials and Nexmo phone number in the appropriate value box for each key before clicking the final Deploy app button. This will ensure your application is deployed to Heroku with your Nexmo API information.

Alternatively, you can do so from with your Heroku Dashboard's application settings by managing the config vars for your Nexmo SMS Contest app after deploying. You will need to add the three environment variables listed above in the Installation and Usage section of this README: NEXMO_API_KEY, NEXMO_API_SECRET, NEXMO_NUMBER.

Once you have deployed to Heroku, you must change your inbound SMS webhook URL in your Nexmo Dashboard to your new Heroku URL.


The app utilizes Active Admin to provide administrative functionality. To use the administrative tooling in order to view contest entries do the following:

From a Clone of this Repository

If you cloned this repository directly, you only need to run rake db:seed from your command line to create your administrative user account, and you can skip to the Administrative Account Credentials section of this README.

From a New Build

If you chose to create your application locally as a new Rails build you need to follow these instructions to access the administrative backend.

After running bundle install as outlined in the Installation instructions, execute the following:

  • rails generate active_admin:install
  • rake db:migrate
  • rake db:seed
  • rails generate active_admin:resource Message

Doing the above will create the Active Admin infrastructure and provide you with an administrative account with a login of and a password of changemerightaway. You can navigate to https://localhost:3000/admin/ and sign in with those credentials to access the administrative section.

Administrative Account Credentials

It is recommended to change the password and the login email for this administrative account. The simplest way to do so is to go into the Rails Console and update it there:

$ rails c
irb(main)::001:0> admin = AdminUser.find_by_email("")
irb(main)::002:0> = "PUT NEW EMAIL ADDRESS HERE"
irb(main)::003:0> admin.password = "PUT NEW PASSWROD HERE"


We ❤️ contributions from everyone! Bug reports, bug fixes and feedback on the library is always appreciated. Look at the Contributor Guidelines for more information and please follow the GitHub Flow.


This project is under the MIT License