> ## Documentation Index > Fetch the complete documentation index at: https://blackbox.dasha.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add pronunciation rules > Adds new pronunciation rules to an existing dictionary. After adding rules, automatically updates all agents using this dictionary with the new configuration. ## Provider Restrictions Some providers have restrictions on rule types: * Certain providers may only support alias rules * Phoneme rules may require specific phonetic alphabet formats If you attempt to add an unsupported rule type, you will receive a 400 Bad Request error. ## OpenAPI ````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/pronunciation-dictionaries/{providerId}/add-rules openapi: 3.0.4 info: title: Dasha BlackBox Agent API description: API for managing AI agents and calls contact: name: DashaAI Team email: support@dasha.ai version: v1 servers: - url: https://blackbox.dasha.ai description: Dasha BlackBox Agent API security: - ApiKey: [] - OAuth: [] tags: - name: ActivityLogs - name: Agents - name: AgentTestCases - name: CallResults - name: Calls - name: Chats - name: Copilot - name: CustomerData - name: Mcp - name: Media - name: Misc - name: PronunciationDictionaries - name: Providers - name: SipAliases - name: SipCredentials - name: SipPhoneNumbers - name: TextChat - name: TwilioProvider - name: Voice - name: WebhookTest - name: WebIntegrations - name: WebSocket description: WebSocket endpoints for real-time communication paths: /api/v1/pronunciation-dictionaries/{providerId}/add-rules: post: tags: - PronunciationDictionaries summary: Add pronunciation rules description: >- Adds new pronunciation rules to an existing dictionary. After adding rules, automatically updates all agents using this dictionary with the new configuration. parameters: - name: providerId in: path description: Dictionary identifier required: true schema: type: string requestBody: description: Rules to add content: application/json: schema: allOf: - $ref: '#/components/schemas/AddRulesRequestDto' description: >- Request to add new pronunciation rules to an existing pronunciation dictionary. If a rule with the same text already exists in the dictionary, it will be replaced with the new rule. The dictionary's content hash and last updated timestamp will be updated after the operation. text/json: schema: allOf: - $ref: '#/components/schemas/AddRulesRequestDto' description: >- Request to add new pronunciation rules to an existing pronunciation dictionary. If a rule with the same text already exists in the dictionary, it will be replaced with the new rule. The dictionary's content hash and last updated timestamp will be updated after the operation. application/*+json: schema: allOf: - $ref: '#/components/schemas/AddRulesRequestDto' description: >- Request to add new pronunciation rules to an existing pronunciation dictionary. If a rule with the same text already exists in the dictionary, it will be replaced with the new rule. The dictionary's content hash and last updated timestamp will be updated after the operation. responses: '200': description: Pronunciation rules added successfully content: application/json: schema: $ref: '#/components/schemas/PronunciationDictionaryResponseDto' '400': description: Invalid rule type or validation errors content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Authentication failed or API key is missing content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Pronunciation dictionary with specified ID does not exist content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '502': description: Gateway error occurred '503': description: Service temporarily unavailable '504': description: Request timeout occurred components: schemas: AddRulesRequestDto: required: - rules type: object properties: rules: minItems: 1 type: array items: oneOf: - $ref: '#/components/schemas/AliasPronunciationRule' - $ref: '#/components/schemas/PhonemePronunciationRule' description: >- Base class for pronunciation rules that control how specific text is spoken during TTS synthesis. Rules use polymorphic serialization with a type discriminator to support different pronunciation methods (alias or phonetic). description: >- Pronunciation rules to add to the dictionary. Each rule specifies a word or phrase to match and how it should be pronounced using either alias (text replacement) or phonetic representation. If a rule with the same text already exists, the existing rule will be replaced with the new one. additionalProperties: false description: >- Request to add new pronunciation rules to an existing pronunciation dictionary. If a rule with the same text already exists in the dictionary, it will be replaced with the new rule. The dictionary's content hash and last updated timestamp will be updated after the operation. PronunciationDictionaryResponseDto: required: - content - contentHash - createdTime - lastUpdatedTime - name - orgId - provider - providerId type: object properties: providerId: minLength: 1 type: string description: >- Unique identifier assigned by the TTS provider. Used to reference this dictionary when configuring voices or making API calls to the provider. provider: minLength: 1 type: string description: >- TTS provider that hosts this pronunciation dictionary. Supported providers: ElevenLabs, Cartesia. The dictionary can only be used with voices from the same provider. orgId: minLength: 1 type: string description: >- Organization that owns this pronunciation dictionary. Used for access control and resource management. contentHash: minLength: 1 type: string description: >- Content hash for tracking dictionary changes. This hash changes whenever rules are added, removed, or modified, allowing you to detect updates without comparing full rule lists. content: type: array items: oneOf: - $ref: '#/components/schemas/AliasPronunciationRule' - $ref: '#/components/schemas/PhonemePronunciationRule' description: >- Base class for pronunciation rules that control how specific text is spoken during TTS synthesis. Rules use polymorphic serialization with a type discriminator to support different pronunciation methods (alias or phonetic). description: >- Pronunciation rules defining how specific words and phrases should be spoken. Each rule specifies text to match and its pronunciation using either alias (alternative text) or phonetic representation. name: minLength: 1 type: string description: >- Display name for the pronunciation dictionary. Used to identify and organize dictionaries in your account. createdTime: type: string description: Timestamp when the pronunciation dictionary was originally created. format: date-time lastUpdatedTime: type: string description: >- Timestamp when the pronunciation dictionary was last modified. Updates when rules are added, removed, or the name is changed. format: date-time additionalProperties: false description: >- Pronunciation dictionary information including rules, metadata, and provider details. Contains all data needed to use the dictionary with TTS voices and track changes over time. ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} AliasPronunciationRule: allOf: - $ref: '#/components/schemas/PronunciationRuleBase' - required: - alias - type type: object properties: type: enum: - alias type: string description: >- Rule type discriminator indicating this is an alias-based pronunciation rule. readOnly: true alias: minLength: 1 type: string description: >- Alternative text to speak instead of the matched text. The TTS engine will pronounce this replacement text using its natural language processing. For example, "HTTP" could be aliased to "H T T P" for letter-by-letter pronunciation, or "SQL" to "sequel" for word pronunciation. additionalProperties: false description: >- Alias pronunciation rule that replaces matched text with alternative text during TTS synthesis. Useful for expanding acronyms, replacing technical terms with pronounceable alternatives, or substituting brand names with phonetic spellings. The TTS engine will then pronounce the alias text naturally. PhonemePronunciationRule: allOf: - $ref: '#/components/schemas/PronunciationRuleBase' - required: - phoneme - type type: object properties: type: enum: - phoneme type: string description: >- Rule type discriminator indicating this is a phoneme-based pronunciation rule. readOnly: true phoneme: type: array items: type: string description: >- List of phoneme symbols representing how the text should be pronounced. Each string in the list is a phoneme from the specified phonetic alphabet. The TTS engine will synthesize these phonemes directly, bypassing its natural language processing for precise pronunciation control. alphabet: type: string description: >- Phonetic alphabet system used for the phoneme symbols. Supported values vary by provider but commonly include "ipa" (International Phonetic Alphabet). When not specified, the provider's default alphabet is used. nullable: true additionalProperties: false description: >- Phoneme pronunciation rule that specifies exact phonetic pronunciation for matched text using phonetic alphabet symbols. Provides precise control over pronunciation, useful for words that TTS engines commonly mispronounce, foreign words, or specialized terminology requiring specific pronunciation. PronunciationRuleBase: required: - text - type type: object properties: type: allOf: - $ref: '#/components/schemas/PronunciationRuleType' description: >- Rule type discriminator determining the pronunciation method. Supported values: alias (text replacement), phoneme (phonetic representation). readOnly: true text: minLength: 1 type: string description: >- Word or phrase to match in the input text. When this text is encountered during TTS synthesis, it will be pronounced according to the rule's pronunciation specification. Matching is typically case-insensitive. additionalProperties: false description: >- Base class for pronunciation rules that control how specific text is spoken during TTS synthesis. Rules use polymorphic serialization with a type discriminator to support different pronunciation methods (alias or phonetic). PronunciationRuleType: enum: - unspecified - alias - phoneme type: string description: >- Pronunciation rule type determining how matched text is pronounced during TTS synthesis. Each type uses a different method to specify pronunciation: alias substitutes alternative text, while phoneme uses phonetic symbols for precise pronunciation control. securitySchemes: ApiKey: type: http description: API Key Authentication (Bearer {key}) scheme: Bearer OAuth: type: oauth2 flows: implicit: authorizationUrl: https://auth.dasha.ai/connect/authorize scopes: platform_api: Platform API ````