Custom Dictionary, Dot Phrases & Text Replacements

Nabla offers three user-level personalization features that let a provider tailor API behavior to their vocabulary and workflow: the Custom Dictionary, Dot Phrases, and Text Replacements. They are complementary, but each one applies to a different workflow and at a different stage of the pipeline.

This guide explains what each feature does, when it applies, and how to choose the right one.

Which one do I need?

• The speech-to-text engine keeps mishearing a specialized term → add it to the Custom Dictionary.
• The provider wants a short trigger to expand into a structured block in their generated note → create a Dot Phrase.
• The provider wants a short trigger to expand into longer text while dictating → create a Text Replacement.

Custom Dictionary entries are complementary to the other two: because they improve transcription accuracy, adding the trigger of a Dot Phrase or Text Replacement to the Custom Dictionary can make that trigger more reliably detected in the first place.

Recap Table

Feature	What it does	Ambient workflow	Dictation workflow	When it is applied
Custom Dictionary	Improves speech-to-text accuracy for user-specific terms	✅	✅	In real time, as the audio stream is processed
Dot Phrases	Expands a spoken trigger into generated note content	✅	❌	After transcription, during note generation
Text Replacements	Expands a dictated trigger into longer text	❌	✅	In real time, as the audio stream is processed

In other words:

• Custom Dictionary improves the recognition of specific terms by the speech-to-text engine. It is used in both ambient and dictation workflows.
• Dot Phrases only affect note generation output.
• Text Replacements only affect dictation output.

Custom Dictionary

A Custom Dictionary Expression improves the accuracy of the speech-to-text engine for terms that are not part of the default medical vocabulary. For example: organization names, local procedures, or uncommon acronyms that the engine tends to mishear.

It is a recognition-time hint, not a text substitution. You provide the correct spelling of a word or expression, and it biases the speech-to-text pipeline toward transcribing it that way when it hears something similar.

🗒️

Example: If the provider often mentions Xeljanz, but the transcript sometimes renders it incorrectly, adding Xeljanz to the Custom Dictionary can improve recognition in both ambient and dictation workflows.

Each expression carries:

Field	Description
expression	The term to recognize more reliably (1–64 characters), e.g. metformin.
speech_locale	The locale the expression should be recognized in.

The Custom Dictionary is used in both ambient and dictation workflows. It affects the Transcription WebSocket, the Dictation WebSocket, and their REST equivalents.

Manage Custom Dictionary:

• Get all Custom Dictionary Expressions
• Get a Custom Dictionary Expression
• Create a Custom Dictionary Expression
• Update a Custom Dictionary Expression
• Delete a Custom Dictionary Expression

Dot Phrases

A Dot Phrase is a concise trigger that expands into a predefined block of text inside a generated clinical note. Dot Phrases are specific to the ambient workflow and are matched after the encounter is transcribed, during note generation.

🗒️

Example: If the transcript contains the trigger "Your physical exam is normal", Nabla can return a suggested Dot Phrase containing a reusable normal physical exam block such as:

• Heart Examination: Normal, with regular rate and rhythm, no murmurs.
• Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi.
• Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly.

The integration can then insert that block into the appropriate section of the generated note.

Each Dot Phrase carries:

Field	Description
title	A user-friendly label. Does not affect matching.
trigger	The phrase that, if detected in the transcript, prompts this Dot Phrase, e.g. "Your physical exam is normal".
replacement	The block of text to insert when the trigger is matched, e.g. the normal physical exam block shown above.
content_auto_update_enabled	If true, the inserted text is dynamically adapted to the encounter instead of used verbatim.

When you call one of the note-generation endpoints, user Dot Phrases are matched against the transcript and matching entries are returned in the response as suggested_dot_phrases.

Each suggestion includes the text_to_insert and, where possible, the note section it belongs to. When content_auto_update_enabled is on, text_to_insert may differ from the raw replacement: it is adapted to the encounter discussion (for instance to include exceptions) instead of being used verbatim.

In both cases, the generated note itself never includes the Dot Phrase content automatically: Nabla only suggests it, and the integration is responsible for inserting text_to_insert into the appropriate place in the note.

Manage Dot Phrases:

• Get all Dot Phrases
• Get a Dot Phrase
• Create a Dot Phrase
• Update a Dot Phrase
• Delete a Dot Phrase
• Bulk operations: create, update, delete

Text Replacements

A Text Replacement is the dictation equivalent of a Dot Phrase: a concise trigger that expands into a longer piece of text. It is specific to dictation and is applied in real time as the dictation stream is processed. As soon as the trigger phrase is detected, the transcribed output is automatically replaced with the replacement text.

🗒️

Example: If the provider dictates "normal blood pressure", a Text Replacement can replace that trigger with "Blood pressure is within normal limits." in the dictation output.

Each Text Replacement carries:

Field	Description
trigger	The dictated phrase that will be replaced, e.g. "Normal blood pressure".
replacement	The text substituted into the dictation result when the trigger is detected.

Text Replacements apply to both the Dictation WebSocket and the REST dictation endpoints.

Manage Text Replacements:

• Get all Text Replacements
• Get a Text Replacement
• Create a Text Replacement
• Update a Text Replacement
• Delete a Text Replacement