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:
- Enable the Voice Monkey Alexa Skill
- Sign in to the Voice Monkey Console.
- 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:
- In the Voice Monkey console, go to Devices
- Create a new "Speaker" Device and provide a name.
- Create a new Alexa Routine.
- In the "When this happens" section select Smart Home->Your Voice Monkey device.
- In the "Action" section select Skills ->Voice Monkey.
- In the "From" section select the Physical Alexa device to link.
- After you've saved your routine, return to the Voice Monkey console and complete the set-up.
Congratulations, you've linked your first device.
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.
| Speakers | Speakers are devices that you wish to link to your physical Echo devices to play audio or video content. |
|---|
| Routine Triggers | Triggers 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.
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:
| Audio | Play an audio file located at a secure https URL. |
|---|
| Condition | Create an IF/ELSE scenario based on a specific condition. |
|---|
| Flow Trigger | Trigger another one of your Flows. |
|---|
| Image | Display an image file on a screen enabled device. |
|---|
| Question Prompt | Specify 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 Trigger | Trigger an Alexa routine using your Trigger devices. |
|---|
| Speech | Alexa will speak your text from your chosen device. |
|---|
| Variable Set | Set the value of one of your variables during a Flow. |
|---|
| Video | Play a video file located at a secure https URL. |
|---|
| Web Request | Make a GET or POST http request to another URL. |
|---|
| Website | Open 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:
| Color | Responses should be a color e.g. "red", "white", "yellow". |
|---|
| First Name | Responses should be a name e.g. "Paul", "Sarah", "Joe". |
|---|
| Letters | Responses should be a single letter e.g. "A", "B", "C". |
|---|
| Numeric | Responses should be numeric e.g. "1", "20", "300". |
|---|
| On / Off | Responses should be either "On" or "Off". |
|---|
| True / False | Responses should be either "True" or "False". |
|---|
| Yes / No | Responses 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.
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.
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:
token | Required | This 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. |
|---|
device | Required | The Device ID string that you're targetting. This can be found in the Devices section within Settings or in the API Playground. |
|---|
text | Optional | This text will be converted to speech that Alexa will announce. You can also include SSML content for richer announcements. |
|---|
voice | Optional | The Voice used when making an announcement. Defaults to your regular Alexa voice. Visit the API Playground to see available options. |
|---|
language | Optional | A Language code to help annoucements sound better in certain languages. Visit the API Playground to see available options. |
|---|
chime | Optional | Adds 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. |
|---|
audio | Optional | Plays an audio file located at a secure https URL. Please see the Media section of these docs for file format limitations. |
|---|
background_audio | Optional | When using the text parameter for text to speech, this audio file will play in the background. |
|---|
website | Optional | Expects 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_bg | Optional | If set to "true", then no Voice Monkey logo or image will appear on a screen enabled device. |
|---|
image | Optional | A https URL of an image file which will display on a screen enabled Alexa device. |
|---|
media_width | Optional | A numeric value representing the width of the image file. Visit the API Playground to see available units. |
|---|
media_height | Optional | A numeric value representing the height of the image file. Visit the API Playground to see available units. |
|---|
media_scaling | Optional | A string value which determines how Alexa should scale your image. Visit the API Playground to see available options. |
|---|
media_align | Optional | A string value which defines the position of the image within the container. Visit the API Playground to see available options. |
|---|
media_radius | Optional | A 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. |
|---|
video | Optional | A 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_repeat | Optional | A numeric value indicating how many times the video should loop. |
|---|
var-[variable name] | Optional | Update 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:
token | Required | This 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. |
|---|
device | Required | The 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:
token | Required | This 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. |
|---|
device | Required | The Device ID string that you're targetting. This can be found in the Devices section within Settings or in the API Playground. |
|---|
flow | Required | The numeric ID of the Flow you wish to start. This ID can be found in the Flows section within the console. |
|---|