Creating an Alexa Game: Number Spies — System Components Overview

Architecture and Services to Support the Game


In the previous article, we talked about how Number Spies started with making an Alexa Flash Briefing to duplicate the behavior of a numbers station. That idea grew into a voice game in the form of an Alexa Skill.

In order to create the encoded messages, I knew there needed to be an audio processing backend. This was the part that delayed the project for many months as I didn’t know how to do the audio processing.

Along the way, more components were added to the system until it became the system shown in the diagram.


Flash Briefing — this Alexa Skill type allows players to enable the briefing and play it with other briefings. Later, the player can listen to their briefings by saying: “Alexa, play Flashing Briefings.” In order to know what to play, the briefing skill reads the feed.json file and plays audio.mp3.

Daily Process — this component consists of a Lambda function that starts every day at UTC 0 via a CRON job. The process reads the current day’s Message from the CMS. If there is no message for the day, the process exits. If there is a message, an AWS Step Function State Machine starts and turns that message into a feed, audio file, and a data file that other components can use.

Step Function State Machine Definition

CMS — the Content Management System stores all the configurable game data and has its own website to add, update, or delete content. The CMS used for this game is from Sanity which proved to be a valuable part of the solution. Originally I was using a Google Sheet as a kind of CMS, but once the requirements grow to include more than one data type I went looking for a “headless” CMS and found Sanity. (see

Zapier — this component allows for integration. The Daily Process calls a web hook which triggers a Zap that posts the encrypted message to a Facebook Page. Posting the message to Facebook triggers a second Zap that posts a link for the Facebook Page on a Twitter account. (see

Facebook Page — Number Spies has its own page on Facebook to help build a community around the game. For those who want to play the game but don’t want to transcribe the numbers for the encoded message, they can copy them from this page. The idea for a Facebook Page came from a conversation that I had with Sarah Andrew Wilson from

Twitter Account — Number Spies has its own account (@NumberSpies) on Twitter. This account also helps build a community on social media. Since the encoded messages are too large, a tweet instead includes a link back to the Facebook Page.

Website — The Number Spies website provides information about getting started, the rules for the game, voice commands, a contact form and more. This mobile-friendly site also allows the player to decode a message with the Novice Decoder or shows the steps on how to decode manually. You can also provide your own name for a purchased spy alias. To store this alias, the website calls an API that is able to update the User Data storage.

User Data — this DynamoDB database keeps track of all player data in a single item/record. This includes aliases, score, currency, experience points, levels, and game settings. This storage also allows for an alias entered on the Website to be recorded in the voice game by way of a unique code.

Alexa Skill — the custom Alexa Skill is the heart of the voice game. Its code runs in its own Lambda function and calls the CMS as needed to access the game data. A player’s game info is stored in the User Data table. The numbers station transmission can be played as many times as the player wants during the day and uses the same audio.mp3 file as the Flash Briefing. The Daily Process also generates a data.json file which includes any message for the current day, the One Time Pad (OTP) to encode the message, as well as the valid verify codes for the message. The skill can also send emails to the player.

SendGrid — to send emails to the players, I use the popular SendGrid service. There are 2 emails types: Send OTP and Send Dossier. The first is only available to players that purchased the monthly subscription through In-Skill Purchasing (ISP). The ability to send a Dossier email is available to all players.

How the System Evolved

The first problem to solve was the Flash Briefing. First, I hardcoded the feed.json and audio.mp3 file to make sure the briefing worked. Then I created the scheduled Daily Process Lambda and used that to generate the feed.json. The Daily Process started as a single Lambda function that was getting its data from a Google Sheet. Later, I moved to a CMS and I added Step Functions to handle different steps of the process to generate the 3 output files. Much later I added the web hook call in the Daily Process to trigger Zapier.

The Daily Process contains multiple Lambda functions for the different steps and uses libraries such as FFmpeg and SoX for the audio manipulations.

Next, I moved on to the Alexa Skill defining the language model one intent at a time. There are common intents that all Skills need such as Launch, Goodbye/Stop/Cancel, Help, and Repeat. As I defined a new intent, I would move on to implement it and learn as I went along. Often this required finding new NPM modules and solving challenges. There were times this led to ideas on how to expand the game.

Eventually, I created a list of all my game ideas and had to move many of my ideas to a list for version 2. Otherwise, I would keep coding and never release. This helped me focus much better on the minimal things needed for the first release. The last part added to the Alexa Skill was sending emails.

I wanted a game website, so I moved on to that toward the end of the process or when I needed a break from coding the Skill. Sometimes you just need to let a problem sit for a day so you are fresh going back to it. I created the website using Vue.js and the Nuxt framework.

The very last section of the system that was implemented was the social media accounts and the Zapier integration.


The Number Spies implementation grew from a Flash Briefing and a custom Alexa Skill to a larger system with various integrations. The resulting system and components started looking more like an architecture that you might see in a business environment.

Which components have you implemented in voice game architecture?

What ideas do you have to improve the system design?

Creating an Alexa Game — Table of Contents

  • Intro — From Idea to Code and Beyond
  • The Spark of Inspiration for Number Spies
  • Number Spies — System Components Overview (this post)
  • Content Management with
  • Number Spies Alexa Flash Briefing
  • Number Spies Alexa Skill — Language Model
  • Number Spies Alexa Skill — Why I Chose the Jovo Framework
  • Number Spies Alexa Skill — Text-to-Speech and Speech Markdown
  • Website Domain Name and Skill Invocation Name
  • Number Spies Alexa Skill — Code (multiple parts)
  • Number Spies Alexa Skill — Unit Testing with Bespoken
  • Number Spies Alexa Skill — Skill Store Info
  • Number Spies Alexa Skill — Analytics with Dashbot
  • Number Spies Alexa Skill — Exception Monitoring with Sentry
  • Number Spies Alexa Skill — User Acquisition with Voxalyze Then Not
  • Number Spies Website
  • Game Promotion & Social Media
  • Is the Game a Success?

Alexa Champion 🏆, Bixby Premier Developer, Software Architect, Speaker 🎙️, Author

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store