Documentation Last updated: 2024-03-04

This page provides documentation for the Voice Monkey Alexa Skill.It is regularly updated, so come back soon to see the most up to date information.
If you have any feedback, questions or suggestions, please get in touch.

INTRODUCTION TO VOICE MONKEY

Enhance your wellness, be more productive and make your smart home even smarter.
Voice Monkey gives your home a voice and fills your living space with intelligent ambient sound and video.

Voice Monkey is a smart home Alexa Skill that amongst other things lets you:

  • Play ambient sounds and video to help you relax, focus and sleep.
  • Add fun and ambience to your home through apps such as our Cuckoo clock
  • Enhance Alexa Routines with functionality such as Prompts that perform actions in response to you saying Yes/No.
  • Make API requests to trigger Alexa routines remotely or make text-to-speech voice announcements.
  • Integrate your Alexa smart home with other apps through integrations such as IFTTT and Zapier.
How does Voice Monkey do this?

When you enable the Voice Monkey Skill and sign-up you will be asked to link your Echo devices to Voice Monkey via Alexa Routines. With these connections in place, we can then start pushing the content you want to those devices.

Note

Devices are an important part of the Voice Monkey ecosystem. To find out more, please view the section on Devices.

GETTING STARTED

Voice Monkey is an Alexa Skill. However, instead of controlling the Skill with your voice, you control it via the Voice Monkey console, available through any browser on your desktop, tablet or mobile device.

The steps to get started with Voice Monkey are quite simple:

  1. Enable the Voice Monkey Alexa Skill
  2. Sign in to the Voice Monkey Console.
  3. Create a Device and link it to Alexa using a Routine.

Step 1: Enable the Voice Monkey Alexa Skill

Enable the Voice Monkey Skill on your relevant Amazon site using either the Amazon Skills website or the Skills section of the Amazon App.

Select your country specific Alexa Skills store:
Link your Amazon account:

When you enable the Voice Monkey Alexa Skill, you will be asked to link your Amazon account and accept the permissions. To link your account, simply sign-in using the same Amazon Account you use for Alexa.

Amazon Credentials

Voice Monkey uses "Login With Amazon" which means we NEVER see or have access to your Amazon account password.

Step 2: Sign in to the Voice Monkey Console.

To access the console, head to: https://console.voicemonkey.io in your web browser.

Click the login button which will redirect you to the secure Amazon website where you can sign-in using the same Amazon Account that you used to link Voice Monkey with Alexa above.

Remember, we never see your Amazon account credentials.

Step 3: Create a device and link it to Alexa

Warning

Please note, that Voice Monkey devices were recently re-named from "Monkeys" to "Devices".

To finish getting started you need to create at least one Voice Monkey Device and link it to Alexa via a Routine. You can find out more information on Devices, below but the basic steps to crate a "Speaker" device:

  1. In the Voice Monkey console, go to Devices
  2. Create a new "Speaker" Device and provide a name.
  3. Create a new Alexa Routine.
  4. In the "When this happens" section select Smart Home->Your Voice Monkey device.
  5. In the "Action" section select Skills ->Voice Monkey.
  6. In the "From" section select the Physical Alexa device to link.
  7. After you've saved your routine, return to the Voice Monkey console and complete the set-up.

Congratulations, you've linked your first device.

DEVICES

Voice Monkey "Devices", previously called "Monkeys", are the mechanisms that allow Voice Monkey to connect with your physical Amazon Echo devices.

What is a Device?

With any Smart Home product that works with Alexa, whether it's Phillips Hue or Ring, the manufacturer has to create a virtual device to tell Alexa what type of product is being connected. Amazon has a number of different products that can be connected. For example, Phillips Hue will create a "Light" device (or entity) within Alexa.

Amazon do not provide any easy to use, native APIs for triggering routines or for pushing content to your Echo speakers. So Voice Monkey has built a workaround.

This workaround involves creating virtual Smart Home "Devices" like the Hue example above. Instead of creating "lights" we are simply creating "doorbells".

When these "doorbells" are pressed, something happens. So we ask you to create a Voice Monkey "Device" (or doorbell) and add it to your Alexa routine. That way, when you trigger that "Device", for example using the Voice Monkey API, you are in effect pressing the doorbell, which starts your Routine.

This can get confusing, but the above is for context, you don't need to know this. Anything important can be found below.

Device Types

There are two types of Voice Monkey Devices that can be added depending on what you wish to do.

SpeakersSpeakers are devices that you wish to link to your physical Echo devices to play audio or video content.
Routine TriggersTriggers are used solely for triggering Alexa Routines.

Note

Under the hood, both "Speakers" and "Triggers" are the same thing, virtual doorbell Alexa devices (see above). However, they are treated differently within Voice Monkey so please create the appropriate device type for your use case.

Adding a Speaker Device

Voice Monkey "Speaker Devices" are used with Apps, Announcements, Flows and Audio and Video content.

To add a Speaker Device follow these instructions:

Step 1: Sign in to the Voice Monkey console, and go to Devices or visit this URL: https://console.voicemonkey.io/devices

Step 2: In the "Speakers" section, click the "+ Add a device" button

Step 3: On the next page provide a name for your Device e.g. "Monkey - Echo Dot". This name will appear in the Alexa app. You can also select whether this device is a single device, or a group of devices.

Step 4: Go to the Alexa App and create a new Routine.

Step 5: In the "When this happens" section, select Smart Home and then select the Device you created above.

Step 6: In the "Action" section of the routine, select Skills and then select the Voice Monkey Skill.

Step 7: In the "From" section of the routine, select the physical device to link to e.g. "Echo Dot Bedroom".

Step 8: Save the Routine. If you are creating a Group of Speakers, you need to follow Steps 4-8 for each device you are adding to the group, making sure that in the "From" section, you select a different device each time.

Step 9: Return to the Voice Monkey console. Sync the devices by following the instructions. If everything is working correctly you should hear a confirmaiton sound from your device. Congratulations, you linked a device!

Naming Tip

We suggest you pre-fix your Voice Monkey Device names with the same thing each time e.g. "Monkey" or "VM" or similar. This makes them much easier to find within the Alexa App as they are ordered alphabetically.

Adding a Routine Trigger Device

Voice Monkey "Routine Trigger Devices" are used to Trigger Alexa Routines using the Voice Monkey API or within some Apps and Flows.

To add a Routine Trigger Device follow these instructions:

Step 1: Sign in to the Voice Monkey console, and go to Devices or visit this URL: https://console.voicemonkey.io/devices

Step 2: In the "Routine Triggers" section, click the "+ Add a trigger" button

Step 3: On the next page provide a name for your Device e.g. "Monkey - Lights On". This name will appear in the Alexa app.

Now you have a Trigger device set-up, you can use it within your Alexa Routines:

Step 1: Go to the Alexa App and create a new Routine.

Step 2: In the "When this happens" section, select Smart Home and then select the Device you created above.

Step 3: In the "Action" section of the routine, select whatever you want to happen next, whether it's asking Alexa to turn on a light or start some music.

NOw, whenever you trigger that Voice Monkey Device, it will start your Routine. You can trigger your Voice Monkey Device using the API, via an integration such as IFTTT or through some Apps and Flows.

FLOWS

With Flows you can create powerful automations for your Alexa smart home. Find out more below.

What are Flows?

Flows are a collection of actions that run when triggered. Think of them as mini Alexa Routines.

When you create a Flow you assign different actions that run in sequencial order. These actions range from Alexa saying something, to a video being played. You can see which types of actions are available below.

Flows opens up use cases such as:

  • Playing a custom sound.
  • Creating parent/child routines.
  • Running Routines based on a given response e.g. Yes/No

How to create a Flow?

Sign in to the Voice Monkey console, and go to the Flows section or visit this URL: https://console.voicemonkey.io/flows

Click the "Create Flow" button. You'll be asked to provide a name for your Flow.

You're then ready to start adding Actions.

Once you've added an Action, a node will appear within the Tree diagram in the console. You can click on the "+" icon next to a node to add another action after. You can click the edit icon to Edit that action.

Flow Action types

The following actions are currently available:

AudioPlay an audio file located at a secure https URL.
ConditionCreate an IF/ELSE scenario based on a specific condition.
Flow TriggerTrigger another one of your Flows.
ImageDisplay an image file on a screen enabled device.
Question PromptSpecify a question (e.g. "Shall I turn on the lights?") with a defined answer (e.g. "yes/no"). Add different actions according to your response. See below for answer types.
Routine TriggerTrigger an Alexa routine using your Trigger devices.
SpeechAlexa will speak your text from your chosen device.
Variable SetSet the value of one of your variables during a Flow.
VideoPlay a video file located at a secure https URL.
Web RequestMake a GET or POST http request to another URL.
WebsiteOpen a website on a large screen enabled device.

Answer types

When you add a "Question Prompt" action, you are required to specify an answer type. These are the answer types available:

ColorResponses should be a color e.g. "red", "white", "yellow".
First NameResponses should be a name e.g. "Paul", "Sarah", "Joe".
LettersResponses should be a single letter e.g. "A", "B", "C".
NumericResponses should be numeric e.g. "1", "20", "300".
On / OffResponses should be either "On" or "Off".
True / FalseResponses should be either "True" or "False".
Yes / NoResponses should be either "Yes" or "No".

How to trigger Flows

There are currently five ways of triggering or starting a Flow.

Manually - In the Voice Monkey console, head to the Flows section. You'll see a button next to your Flow labeled "Trigger Flow".

API - Using the Flows API, you can start the flow programatically from any software or app that can make http requests.

Alexa Routine - You can start a Flow from within an Alexa Routine. For instructions, go into the Flow editor and click the "View instructions" button next to the Routine trigger option.

Voice - You can start a Flow using your an Alexa voice command. For instructions, go into the Flow editor and click the "View instructions" button next to the Voice trigger option.

Schedules - Flows can be scheduled for a specific time or day and even at random times during the day.

VARIABLES

Use Variables for IF/ELSE conditions within Flows and for richer more dynamic announcements.

What are Variables?

Think of a variable as a box. You can put something into that box and replace it whenever you want.

Variables allow you to temporarily store information in Voice Monkey and then use this information in your Flows and announcements.

For example, we can create a variable called "LIGHT_STATUS" with an initial value of "ON". Now, whenever we switch a light off, we update that value to "OFF". You can then use this variable in a Flow condition. If "LIGHT_STATUS" is "ON" then do this, otherwise do that.

How to create a Variable?

Sign in to the Voice Monkey console, and go to the Variables section or visit this URL: https://console.voicemonkey.io/variables

Click the "New variable" button. You'll be asked to provide a name for your Variable and an initial value.

You're variable is now ready to use.

How to update a Variable?

There are a few ways to update variables:

  • In the Voice Monkey console, head to the Variables section. Find the variable you wish to update and click "Edit".
  • Using any of our API endpoints, add a GET or POST parameter of var-[variable_name]=value. For example, if you have a variable called "STATUS" and you wish to set the value to "on", you would send a parameter var-status=on. More than one variable can be updated in a single API call. You can add this parameter to any /announcement, /trigger or /flows API call. However if the purpose of the API call is to only update one or more variables, you can do so using the /variables endpoint with the "var-" parameter mentioned above.
  • Use the "Set Variable" action to set a variable's value within a Flow.

Using a Variable

Using variables is easy and you can do so in the following ways.

Flow Conditions

When using the Flow "Condition" action, you can select the condition type to that of "variables". This way you can check the value of a variable and form an IF/ELSE statement. For example, if the variable "STATUS" equals "ON" then do this.

Announcements

Within announcement text in Flow Actions or API calls you can add your variable name wrapped in {curly brackets}. This will be replaced with the variable value in the announcement. For example, lets imagine our variable called "STATUS" had a value of "ON". We could then write the following announcement text:

"The light is currently {STATUS}"

When Alexa reads this, it would say: "The light is currently on"

URLs

You can replace image, audio, video and website URLs with a variable, or even just part of a URL with a variable.

WEBHOOKS

Documentation coming soon.

API v2

We offer easy to use APIs that allow you to make announcements, trigger Routines, start Flows and more.

API v1

API v1 is no longer supported but will continue to work for existing v1 users. We recommend you upgrade to v2 for better support and enhanced features.

API Authentication

When making requests to the API, you need to provide your unique secret token as part of the request. This can be done in one of two ways:

Token Parameter When making GET or POST requests, you can include the "token" parameter in the request.

Authorization Header Send a header in the request with "Authorization" as the key and your secret token as the value.

Rotating Your Token

We advise you to keep your token safe and store it securely in external apps. If you need to rotate your key, please visit the Voice Monkey Console and go to Settings ->API Credentials

API Endpoint

The domain for API requests is: https://api-v2.voicemonkey.io

API Playground

The API Playground is a feature within the Voice Monkey console that allows you to test and experiment with the available APIs. You can easily set values for the various parameters available and generate a URL which you can use in requests.

Announcement API

The Announcement API allows you to make text-to-speech (TTS) announcements on your Alexa devices by making an API request. As well as Announcements, you can also send content such as images, audio and video to your Echo devices.

The endpoint for these requests is: https://api-v2.voicemonkey.io/announcement

The available parameters for this API are as follows:

tokenRequiredThis is your secret token found in the Voice Monkey console either in Settings or in the API Playground. You can pass this as an "Authorization" header instead. Please see authentication options above.
deviceRequiredThe Device ID string that you're targetting. This can be found in the Devices section within Settings or in the API Playground.
textOptionalThis text will be converted to speech that Alexa will announce. You can also include SSML content for richer announcements.
voiceOptionalThe Voice used when making an announcement. Defaults to your regular Alexa voice. Visit the API Playground to see available options.
languageOptionalA Language code to help annoucements sound better in certain languages. Visit the API Playground to see available options.
chimeOptionalAdds a sound to the start of an announcement. The value can be any https URL of an audio file. You can also use the built in Alexa sound library. Please see the API Playground for commonly used sounds.
audioOptionalPlays an audio file located at a secure https URL. Please see the Media section of these docs for file format limitations.
background_audioOptionalWhen using the text parameter for text to speech, this audio file will play in the background.
websiteOptionalExpects a full URL of a website (including http/https://). This URL will then open on a large enough screen enabled Echo device such as an Echo Show 10 or 15.
no_bgOptionalIf set to "true", then no Voice Monkey logo or image will appear on a screen enabled device.
imageOptionalA https URL of an image file which will display on a screen enabled Alexa device.
media_widthOptionalA numeric value representing the width of the image file. Visit the API Playground to see available units.
media_heightOptionalA numeric value representing the height of the image file. Visit the API Playground to see available units.
media_scalingOptionalA string value which determines how Alexa should scale your image. Visit the API Playground to see available options.
media_alignOptionalA string value which defines the position of the image within the container. Visit the API Playground to see available options.
media_radiusOptionalA numeric value which defines the clipping radius on the corner of an image. A large value will create a cicular clip. Visit the API Playground to see available units.
videoOptionalA https URL of a video file which will display on a screen enabled Alexa device. Please see the Media section of these docs for file format limitations.
video_repeatOptionalA numeric value indicating how many times the video should loop.
var-[variable name]OptionalUpdate your variables with new values. See Variables

Routine Trigger API

The Routine Trigger API triggers on of your Voice Monkey Trigger Devices which in turn will start one of your Alexa Routines.

The endpoint for these requests is: https://api-v2.voicemonkey.io/trigger

The available parameters for this API are as follows:

tokenRequiredThis is your secret token found in the Voice Monkey console either in Settings or in the API Playground. You can pass this as an "Authorization" header instead. Please see authentication options above.
deviceRequiredThe Device ID string that you're targetting. This can be found in the Devices section within Settings or in the API Playground.

Flows Trigger API

The Flows Trigger API starts the Voice Monkey Flow that you define in the request.

The endpoint for these requests is: https://api-v2.voicemonkey.io/flows

The available parameters for this API are as follows:

tokenRequiredThis is your secret token found in the Voice Monkey console either in Settings or in the API Playground. You can pass this as an "Authorization" header instead. Please see authentication options above.
deviceRequiredThe Device ID string that you're targetting. This can be found in the Devices section within Settings or in the API Playground.
flowRequiredThe numeric ID of the Flow you wish to start. This ID can be found in the Flows section within the console.

MEDIA

Pushing media content to your Alexa devices is one of the most exciting things you can do with Voice Monkey. In this section, we provide some information on what types of media files can be used within the Alexa eco-system.

Hosting Media

All media played on Alexa/Echo devices needs to be hosted at a publicly accessible https:// URL e.g. https://www.example.com/file.jpg

The domain hosting the file must present a valid, trusted SSL certificate. Avoid using self-signed certificates.

Files must be CORS wildcard-enabled. The service must respond with the following header: Access-Control-Allow-Origin: *.

Voice Monkey PREMIUM Members have the opportunity to upload media in the Voice Monkey console. A URL of the uploaded asset is then provided which can be used within Flows and via the API.

Using Images

Alexa accepts most common image file formats. Animated GIFs unfortunately will not work. It's best to optimise the image file size where possible. Large images will display a blank screen whilst the Alexa device downloads the image file for display.

We automatically add cache busting to images so if you were to send an image, change it, then send the same URL again, it will automatically update with the new version.

Using Videos

Alexa accepts MP4 video files.

All video-capable devices support the MPEG-4 Part-14 container (MP4), along with AAC and MP3 audio codecs. The maximum resolution is 1080p @30fps or @60fps on supported devices.

Using Audio

Alexa supports the following Audio formats:

  • aac
  • mp3
  • ogg
  • opus
  • wav

For Alexa to play the file successfully, the audio file must meet the following requirements:

  • Bit rate – The bit rate must be less than or equal to 1411.20 kbps.
  • Sample rate – The sample rate must be less than or equal to 48kHz.
  • File size – The file size of the audio clip can’t be greater than 10mb. If your file size is larger than 10mb, consider editing the duration of the file or converting the file to another format, such as MP3 or Opus.
  • Response length – The combined total time for the entire audio response generated from the components cannot be more than 240 seconds.

TROUBLESHOOTING

Sometimes there can be issues with Amazon Alexa's Smart Home APIs and the authentication systems between Alexa and the Voice Monkey Skill. More often than not these can be fixed by doing the following:

Step 1 - The first thing to try is disabling the Voice Monkey Skill and then re-enabling it. You can do this in the Alexa App or on the Amazon website. This fixes the majority of problems and you might not lose any of the Devices (Monkeys) or Routines that you've created.

Step 2 - If step 1 didn't help, try the following:

  1. In the Alexa App, go to Devices, and delete any Devices (Monkeys) you've created and any Routines using a Device (Monkey).
  2. Back here on the site, go to My Devices and delete all your Devices (Monkeys).
  3. Finally, like Step 1, disable the Voice Monkey Skill and re-enable it again.

Hopefully this will reset everything and fix the issue.

Step 3 - If Step 2 didn't solve the issue:

  1. Delete all Devices (Monkeys) and disable the Voice Monkey Skill.
  2. Wait 24 hours.
  3. Restart your router.
  4. Unplug and restart your Alexa devices.
  5. Follow step 2 again.