Skip to main content
An expression tag is a word in square brackets, written in the text, that the voice performs instead of reading: a breath, a laugh, a sigh.
Tags work anywhere you send text to be spoken: POST /tts/synthesize, the /ws/tts WebSocket, and a voice agent’s replies and first message wherever the agent writes them.

​
The tags

Tags are case-insensitive: [Laugh] and [LAUGH] are the same as [laugh].

​
Using them

  • Put the tag after the sentence’s full stop: I can't believe that. [laugh]. This gives the best results.
  • A tag stays with the sentence before it. Long text is spoken sentence by sentence, and Okay. [laugh] That's it! [sigh] Fine. is spoken as Okay. [laugh], That's it! [sigh], Fine.. A tag is never synthesized on its own.
  • A tag at the very start of the text stays with the first sentence: [laugh] Hi there.
  • Tags are not read as words, and they are not touched by numbers, symbols or pronunciation rules.
  • A tag counts as characters of the request text, like any other text.

​
A tag adds time

The clip is longer than the same text without the tag. Measured on our renders: Every tagged test render was longer than its untagged twin, and none ran away. Leave room for the extra time in anything timed to the text, such as captions or a fixed-length slot.

​
Examples

​
POST /tts/synthesize

​
WebSocket (/ws/tts)

​
Voice agents

Ask for them in the agent’s prompt, for example: “When the caller makes a joke, answer with a short laugh by ending your sentence with [laugh].” They also work in the agent’s first message, written verbatim.

​
Tips

  • One tag where it matters sounds natural; a tag on every sentence does not.
  • Use [breath] before a long or serious answer, [sigh] for sympathy, [laugh] after something funny.
  • Write the tag after the full stop, not in the middle of a sentence.

​
Limitations

  • Only [breath], [laugh] and [sigh] exist. An unknown bracketed word such as [giggle] is not a tag: it is read as plain text, as written.
  • If the voice engine serving your request does not support tags (for example after a rollback), the tag is dropped silently and is never spoken as a word. The rest of the text is spoken as usual.
  • Long laughs are the weakest case, and are being improved. The duration of a laugh varies from render to render.
  • Tags do not change the voice, language or pace of the rest of the sentence.