voicemonkey

VoiceMonkey

Control Alexa/Echo devices via VoiceMonkey API v2. Make TTS announcements, trigger Alexa routines, start flows, and display images/videos on Echo Show devices.

Setup

1. Get your secret token from Voice Monkey Console → Settings → API Credentials
2. Set environment variable:

   export VOICEMONKEY_TOKEN="your-secret-token"
   

   Or add to ~/.clawdbot/clawdbot.json:

   {
     "skills": {
       "entries": {
         "voicemonkey": {
           "env": { "VOICEMONKEY_TOKEN": "your-secret-token" }
         }
       }
     }
   }
   

3. Find your Device IDs in the Voice Monkey Console → Settings → Devices

API Base URL

https://api-v2.voicemonkey.io

Announcement API

Make TTS announcements, play audio/video, or display images on Alexa devices.

Endpoint: https://api-v2.voicemonkey.io/announcement

Basic TTS Announcement

curl -X GET "https://api-v2.voicemonkey.io/announcement?token=$VOICEMONKEY_TOKEN&device=YOUR_DEVICE_ID&text=Hello%20from%20Echo"

With Authorization Header (recommended)

curl -X POST "https://api-v2.voicemonkey.io/announcement" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_DEVICE_ID",
    "text": "Hello from Echo the Fox!"
  }'

With Voice and Chime

curl -X POST "https://api-v2.voicemonkey.io/announcement" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_DEVICE_ID",
    "text": "Dinner is ready!",
    "voice": "Brian",
    "chime": "soundbank://soundlibrary/alarms/beeps_and_bloops/bell_02"
  }'

Display Image on Echo Show

curl -X POST "https://api-v2.voicemonkey.io/announcement" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_DEVICE_ID",
    "text": "Check out this image",
    "image": "https://example.com/image.jpg",
    "media_width": "100",
    "media_height": "100",
    "media_scaling": "best-fit"
  }'

Play Audio File

curl -X POST "https://api-v2.voicemonkey.io/announcement" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_DEVICE_ID",
    "audio": "https://example.com/sound.mp3"
  }'

Play Video on Echo Show

curl -X POST "https://api-v2.voicemonkey.io/announcement" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_DEVICE_ID",
    "video": "https://example.com/video.mp4",
    "video_repeat": 1
  }'

Open Website on Echo Show

curl -X POST "https://api-v2.voicemonkey.io/announcement" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_DEVICE_ID",
    "website": "https://example.com",
    "no_bg": "true"
  }'

Announcement Parameters

Routine Trigger API

Trigger Voice Monkey devices to start Alexa Routines.

Endpoint: https://api-v2.voicemonkey.io/trigger

curl -X POST "https://api-v2.voicemonkey.io/trigger" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_TRIGGER_DEVICE_ID"
  }'

Flows Trigger API

Start Voice Monkey Flows.

Endpoint: https://api-v2.voicemonkey.io/flows

curl -X POST "https://api-v2.voicemonkey.io/flows" \
  -H "Authorization: $VOICEMONKEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": "YOUR_DEVICE_ID",
    "flow": 12345
  }'

Media Requirements

Images

• Most common formats supported (JPG, PNG, etc.)
• No animated GIFs
• Optimize file size for faster loading
• Must be hosted at HTTPS URL with valid SSL
• CORS must allow wildcard: Access-Control-Allow-Origin: *

Videos

• MP4 format only (MPEG-4 Part-14)
• Audio codecs: AAC, MP3
• Max resolution: 1080p @30fps or @60fps
• Must be hosted at HTTPS URL with valid SSL

Audio

• Formats: AAC, MP3, OGG, Opus, WAV
• Bit rate: ≤ 1411.20 kbps
• Sample rate: ≤ 48kHz
• File size: ≤ 10MB
• Total response length: ≤ 240 seconds

SSML Examples

Use SSML in the text parameter for richer announcements:

<speak>
  <amazon:emotion name="excited" intensity="high">
    This is exciting news!
  </amazon:emotion>
</speak>

<speak>
  The time is <say-as interpret-as="time">3:30pm</say-as>
</speak>

Notes

• Keep your token secure; rotate via Console → Settings → API Credentials if compromised
• Use the API Playground to test and explore options
• Premium members can upload media directly in the Voice Monkey console
• Always confirm before sending announcements to avoid unexpected noise