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

•Get your secret token from Voice Monkey Console → Settings → API Credentials

•Set environment variable:

bash

export VOICEMONKEY_TOKEN="your-secret-token"

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

json

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

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

API Base URL

code

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

bash

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

With Authorization Header (recommended)

bash

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

bash

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

bash

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

bash

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

bash

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

bash

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

bash

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

bash

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:

xml

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

xml

<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