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](https://console.voicemonkey.io) → Settings → API Credentials 2. 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" } } } } } ``` 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 ```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](https://console.voicemonkey.io) 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