VoiceMonkey

Control Alexa devices via VoiceMonkey API v2 - make announcements, trigger routines, start flows, and display media.

Security Scan

This skill is internally consistent: it only requests a VoiceMonkey API token and the SKILL.md contains curl-based instructions that match the stated ability to control Alexa/Echo devices via the VoiceMonkey v2 API.

Purpose & Capability

Name/description (VoiceMonkey control of Alexa devices) aligns with required credential VOICEMONKEY_TOKEN and the API endpoints shown in SKILL.md. No unrelated services, binaries, or config paths are requested.

Instruction Scope

SKILL.md is an instruction-only integration that demonstrates direct API calls (curl) to VoiceMonkey endpoints and shows how to set the VOICEMONKEY_TOKEN. It also suggests storing the token in ~/.clawdbot/clawdbot.json; this is reasonable but worth noting because it instructs where to persist the secret.

Install Mechanism

No install spec and no code files — lowest-risk model for install. The skill is purely instructions showing HTTP API usage.

Credentials

Only one required environment variable (VOICEMONKEY_TOKEN) is declared and used consistently in examples. This credential is necessary and sufficient for the described API operations, though it grants full control of connected devices.

Persistence & Privilege

always is false and there is no installation that modifies other skills or system-wide settings. Note: model invocation is allowed (default), so the agent could call the API autonomously if permitted by the platform.

Assessment

This skill appears to do what it says: it uses a single VoiceMonkey API token to call VoiceMonkey endpoints to announce messages, trigger routines, start flows, and display media on Echo devices. Before installing, consider: (1) the VOICEMONKEY_TOKEN is powerful — anyone with it can control your Echo/Alexa devices, so only provide a token you trust the skill with; (2) the SKILL.md suggests storing the token in ~/.clawdbot/clawdbot.json — keep that file protected (restrict file permissions) or prefer setting the token as an environment variable; (3) because the agent can invoke the skill autonomously (default), review agent policies or prompts that could cause unintended announcements/triggers. If you need more assurance, ask the skill author for a privacy/security statement or request the skill be implemented as an explicit, non-autonomous action.

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

Parameter	Required	Description
token	Yes*	Secret token (*or use Authorization header)
device	Yes	Device ID from Voice Monkey console
text	No	TTS text (supports SSML)
voice	No	Voice for TTS (see API Playground for options)
language	No	Language code for better pronunciation
chime	No	Sound URL or Alexa sound library reference
audio	No	HTTPS URL of audio file to play
background_audio	No	Audio to play behind TTS
image	No	HTTPS URL of image for Echo Show
video	No	HTTPS URL of MP4 video for Echo Show
video_repeat	No	Number of times to loop video
website	No	URL to open on Echo Show
no_bg	No	Set "true" to hide Voice Monkey branding
media_width	No	Image width
media_height	No	Image height
media_scaling	No	Image scaling mode
media_align	No	Image alignment
media_radius	No	Corner radius for image clipping
var-[name]	No	Update Voice Monkey variables

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"
  }'

Parameter	Required	Description
token	Yes*	Secret token (*or use Authorization header)
device	Yes	Trigger Device ID from Voice Monkey console

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
  }'

Parameter	Required	Description
token	Yes*	Secret token (*or use Authorization header)
device	Yes	Device ID
flow	Yes	Numeric Flow ID from Voice Monkey console

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