Announcement API

Play a text-to-speech announcement on a Speaker device, optionally combined with audio, video, images, on-screen text or a website.

Endpoint

GET/POST https://api-v3.voicemonkey.io/announce

POST is recommended for non-trivial requests (longer speech, JSON body, media URLs). GET is supported for quick browser tests and tools that can only build URLs.

Example request

curl -X POST https://api-v3.voicemonkey.io/announce \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "device": "YOUR_SPEAKER_DEVICE_ID",
    "speech": "Dinner is ready!"
  }'

Parameters

Core

Parameter	Required	Description
token	yes	Your API token. See Authentication.
device	yes	The ID of the Speaker device to announce on. List your devices with GET /devices.
speech	yes*	The text to speak via TTS. Required unless you’re playing media or showing on-screen text only. Supports placeholders.
voice	no	Amazon Polly voice ID (e.g. Joanna, Brian, Hans, Celine). Leave blank for the user’s default. Browse the full list in the Playground.
language	no	BCP-47 language code passed to the Alexa TTS engine (e.g. en-US, de-DE, fr-FR).
chime	no	Soundbank URL of a built-in Alexa sound to play before the speech (e.g. soundbank://soundlibrary/alarms/air_horns/air_horn_01). The Playground has a dropdown of all supported chimes.

Media

Parameter	Required	Description
audio	no	URL (or media://<slug> Media Library reference) of an audio file to play.
background_audio	no	Audio that plays underneath the speech rather than before/after it.
audio_tracks	no	Array of audio tracks for advanced sequencing. Easiest to build via the Playground.
image	no	URL (or Media Library reference) of an image to display on Echo Shows.
video	no	URL (or Media Library reference) of a video to play on Echo Shows.
video_repeat	no	How many times to loop the video. -1 for infinite, 0 (or blank) to play once. Looping isn’t guaranteed — actions on the Echo Show may interrupt the session.
website_url	no	URL of a website to load in the Echo Show’s on-device browser.

Advanced image display

These map directly onto the APL Image component on screen-enabled Echos. Values include their unit suffix (e.g. 100%, 48dp, 10vw).

Parameter	Description
media_scale	none, fill, best-fill, best-fit, best-fit-down.
media_align	top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right.
media_border_radius	Border radius (e.g. 12dp).
media_width	Width (e.g. 100%, 480dp).
media_height	Height (e.g. 60vh, 200dp).

Full-screen text display

Big centered text shown full-screen on screen-enabled devices (Echo Show / Spot / Hub).

Parameter	Description
text_display	The text to display. Pair with the styling params below.
text_display_colour	Hex font colour (e.g. #FFFFFF). Defaults to white.
text_display_bg_colour	Hex background colour (e.g. #000000). Defaults to black.
text_display_size	Font size in dp as a plain number (e.g. 40). Suggested: 24 (Small), 40 (Medium), 120 (Large), 200 (XL). Defaults to 40.

Screens

Parameter	Description
screen	The ID of a Screen you designed in the console, e.g. kitchen-board-x7k2p. Shown on Echo Show, Echo Spot and Fire TV. Its text can use the same placeholders as speech, so combine it with var-NAME parameters to change what it shows. A screen takes the place of image, video, text_display and website_url.

List your screen IDs with GET /screens.

Other

Parameter	Description
character_display	Text to show on the segmented character display of an Echo Dot with Clock.

You can combine any subset of these — e.g. send speech + image + text_display in one call to talk, show a picture and overlay big text. Omit speech entirely to make the screen the whole response.

Screen example

curl -X POST https://api-v3.voicemonkey.io/announce \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "device": "YOUR_SPEAKER_DEVICE_ID",
    "screen": "noticeboard-a1b2c",
    "var-FRIDGE_NOTE": "Pizza night!"
  }'

Text display example

curl -X POST https://api-v3.voicemonkey.io/announce \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "device": "YOUR_SPEAKER_DEVICE_ID",
    "text_display": "Dinner is ready!",
    "text_display_colour": "#FFFFFF",
    "text_display_bg_colour": "#DC2626",
    "text_display_size": "64"
  }'

Placeholders

Every parameter except token and device can contain placeholders, including media URLs and the fields inside audio_tracks. Voice Monkey fills them in when the request arrives, before anything is sent to your Echo:

Placeholder	Replaced with
{NAME}	The current value of your variable NAME.
{NAME.field}	A field inside a variable that holds JSON, e.g. {FORECAST.high} or {FORECAST.days[0].summary}.
{VM.…}	A built-in variable, e.g. {VM.TIME.TEXT12}, {VM.DATE.WEEKDAY} or {VM.DEVICE.NAME} (the Speaker you’re announcing on).
{WEBHOOK.<slug>.<key>}	A value from the latest payload received by an inbound webhook.

{
  "token": "YOUR_TOKEN",
  "device": "YOUR_SPEAKER_DEVICE_ID",
  "speech": "Good morning {VM.USER.FIRST_NAME}, it's {VM.TIME.TEXT12} and the garage is {GARAGE_STATUS}.",
  "audio": "{DOORBELL_SOUND}"
}

A variable can hold a media:// Media Library reference, as DOORBELL_SOUND does above.

• Placeholders that don’t match anything are left as typed, so a typo is easy to spot.
• Values are inserted once. A variable whose value contains {SOMETHING} isn’t expanded a second time.
• {VM.FLOW.NAME}, {VM.FLOW.REF} and {VM.RUN.SCHEDULE} are empty outside a Flow, and {WEB_RESPONSE.…} only exists inside a Flow.

Response

Successful calls return 200:

{
  "success": true,
  "data": "OK"
}

If any var- sidecar updates ran, the response also includes a variableUpdates array — see below.

Setting variables in the same request

Any parameter prefixed with var- is upserted as a variable before the announcement runs, so the new value is available to {NAME} placeholders inside speech (and other text fields) in the same call:

curl -X POST https://api-v3.voicemonkey.io/announce \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "device": "YOUR_SPEAKER_DEVICE_ID",
    "speech": "Hello {NAME}, the camera detected {STATUS}.",
    "var-NAME": "Joe",
    "var-STATUS": "motion"
  }'

See Variables API → Setting variables alongside any other API call for the full rules.

Errors

Errors return a JSON body with an error field and an HTTP status code:

Status	Response body	Meaning
400	{ "error": "MISSING_DEVICE" }	No device parameter supplied.
404	{ "error": "DEVICE_NOT_FOUND" }	The device ID isn’t on this account.
404	{ "error": "SCREEN_NOT_FOUND" }	The screen ID isn’t on this account.
401	{ "error": "UNAUTHORIZED" }	No token supplied.
401	{ "error": "INVALID_TOKEN" }	Token doesn’t match an active token.
429	{ "error": "THROTTLED", "lockoutUntil": "<ISO>" }	Per-user safety lockout — back off until the timestamp.
429	{ "error": "MONTHLY_QUOTA_EXCEEDED", "periodEnd": "<ISO>" }	Plan’s monthly request budget exhausted. Wait for the period end or upgrade.
500	{ "error": "ALEXA_TRIGGER_FAILED" }	Generic upstream Alexa failure — retry with backoff.

Tips

• Use placeholders inside speech, website_url and other fields to insert variables and built-ins like the current time.
• For long-form TTS, break content into multiple sentences — Alexa handles shorter TTS much more reliably.
• Use the Playground to compose requests visually — it has dropdowns for voices, languages and chimes, and generates ready-to-paste snippets in cURL, Python, JavaScript, Home Assistant YAML and more.