### Install Yemot Router 2

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Installs the yemot-router2 package using npm.

```bash
npm install yemot-router2
```

--------------------------------

### Basic Router Initialization and Usage

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Demonstrates the basic setup and usage of the YemotRouter, mimicking Express Router. It shows how to define a route and respond to a call with a text message.

```javascript
import { YemotRouter } from 'yemot-router2';
const router = YemotRouter();

router.get('/', async (call) => {
    return call.id_list_message([
        {
            type: 'text',
            data: 'שלום עולם'
        }
    ])
});
```

--------------------------------

### Default Settings Management

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Explains how default settings can be managed across different levels: library, router instance, call instance, and specific read/id_list_message calls. It details the order of precedence, where more specific settings override broader ones. Examples demonstrate initializing the router with defaults and overriding them during a call.

```javascript
const router = YemotRouter({
    printLog: true,
    defaults: {
        removeInvalidChars: true,
        read: {
            timeout: 30000
        }
    }
});

// אפשר גם כך:
// router.defaults.read.timeout = 30000;

router.get('/', async (call) => {
    // הtimeout יהיה 30 שניות
    await call.read([{ type: 'text', data: 'היי, תקיש 1' }], 'tap', {
        max_digits: 1,
        digits_allowed: [1]
    });

    // הtimeout יהיה 40 שניות
    call.defaults.read.timeout = 40000;
    await call.read([{ type: 'text', data: 'היי, תקיש 1' }], 'tap', {
        max_digits: 1,
        digits_allowed: [1]
    });

    // הtimeout יהיה 60 שניות
    await call.read([{ type: 'text', data: 'היי, תקיש 1' }], 'tap', {
        max_digits: 1,
        digits_allowed: [1],
        timeout: 60000
    });
});
```

--------------------------------

### Call Object `read` Method

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Explains the `read` method of the `Call` object, used to get input from the caller. It returns a Promise with the response, which can be caller input (DTMF), speech recognition, or recording.

```APIDOC
read(messages, mode, options?)

  Description:
    Method to get input from the caller. Returns a Promise with the response (in case of recording request, the file path will be returned).
    More details on `read`: https://f2.freeivr.co.il/post/78283

  Arguments:
    messages: An array of 'message' objects to be played to the caller before receiving input.
    mode: Specifies the type of input requested from the caller:
      'tap' = DTMF input
      'stt' = Speech recognition
      'record' = Recording
    options?: Optional parameters for the read method, such as minimum/maximum digits.
```

--------------------------------

### Zmanim Data Structure and Options

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Defines the data structure for the 'zmanim' type, used for retrieving prayer times. It includes optional parameters for time, time zone, and time difference adjustments. Examples show how to specify time formats, time zones, and apply date/time modifications.

```javascript
{
    time: string, // optional, default: "T" (current time)
    zone: string, // optional, default: "IL/Jerusalem",
    difference: string // optional, default: 0
}
```

```javascript
const messages = [{
    type: 'zmanim',
    data: {
        time: 'sunset',
        zone: 'IL/Bney_Brak',
        difference: '+1D'
    }
}];
```

--------------------------------

### Play Hebrew Date

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Plays the Hebrew date in the format DD/MM/YYYY. For example, '28/07/2022' will be spoken accordingly.

```APIDOC
dateH:
  description: Plays the Hebrew date.
  parameters:
    - name: date
      type: string
      format: DD/MM/YYYY
      description: The Hebrew date to be spoken. Example: "28/07/2022"
```

--------------------------------

### Play Number

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Plays a given number audibly. For example, providing '105' will result in the system speaking 'one hundred and five'.

```APIDOC
number:
  description: Plays a number audibly.
  parameters:
    - name: number
      type: integer
      description: The number to be spoken. Example: 105
  example:
    input: "105"
    output: "one hundred and five"
```

--------------------------------

### Manual Call Deletion from Active Calls

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Provides an example of manually removing a call from `activeCalls` using `router.deleteCall(call.callId)` after sending a response, which is recommended if the subsequent heavy task takes time to prevent blocking re-entry into the extension.

```javascript
const router = YemotRouter({ printLog: true });
router.get('/', async (call) => {
    try {
        call.id_list_message([
            {
                type: 'text',
                data: 'בסדר, בקשתך תטופל בהקדם'
            }
        ]);
    } catch (error) {
        if (error.isExitError) return;
        throw error;
    };
    router.deleteCall(call.callId);
    await doBigJob();
});
```

--------------------------------

### Recording Options

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Default options for handling audio recordings. This includes settings for the save path, file name, confirmation menu, saving on hangup, appending to existing files, and minimum/maximum recording lengths.

```js
const options = {
    /* נתיב לשמירת ההקלטה - שלוחה בלבד, ברירת מחדל שלוחה נוכחית, או api_dir אם מוגדר */
    path: '',

    /* שם קובץ (ללא סיומת) לשמירת ההקלטה, ברירת מחדל - ממוספר אוטומטית כקובץ הגבוה בשלוחה */
    file_name: '',

    /*
    ברירת מחדל משמיע תפריט לאישור ההקלטה/הקלטה מחדש, ניתן להגדיר שמיד בהקשה על סולמית ההקלטה תאושר
    */
    no_confirm_menu: false,

    /* האם לשמור את ההקלטה באם המשתמש ניתק באמצע הקלטה */
    save_on_hangup: false,

    /*
    במידה והוגדר שם קובץ לשמירה (file_name) וכבר קיים קובץ כזה,
    האם לשנות את שם הקובץ הישן ולשמור את החדש בשם שנבחר (ברירת מחדל), או לצרף את ההקלטה החדשה לסוף הקובץ הישן
    */
    append_to_existing_file: false,

    /* כמות שניות מינימלית להקלטה, ברירת מחדל אין מינימום */
    min_length: '',

    /* כמות שניות מקסימלית להקלטה, ברירת מחדל ללא הגבלה */
    max_length: ''
};
```

--------------------------------

### Call Routing and Navigation

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Describes the `go_to_folder` functionality for routing calls to different extensions. It notes that this method is not recommended and suggests using `call.go_to_folder` instead. It also mentions that subsequent messages cannot be chained after this type of call.

```APIDOC
go_to_folder:
  path: string (relative path to the current extension or the main extension)
  description: Transfers the call to another extension.
  notes: Not recommended, prefer using `call.go_to_folder(path)`. Cannot chain subsequent messages after this type.
```

--------------------------------

### Key Press Options

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Configuration options for handling user key presses. This includes settings for value names, re-entry, digit limits, timeouts, playback modes, character blocking, allowed digits, attempt counts, empty value handling, and keyboard blocking.

```js
let options = {
    /* שם הערך בימות
    ברירת מחדל, נקבע אוטומטית,
    val_1, val_2, val_3 ...
    */
    val_name: "val_x",
    
    /* האם לבקש את הערך שוב אם קיים. */
    re_enter_if_exists: false,
    
    /* כמות הספרות המקסימלית שהמשתמש יוכל להקיש */
    max_digits: "*",
    
    /* כמות ספרות מינימלית */
    min_digits: 1,
    
    /* שניות להמתנה */
    sec_wait: 7,
    
    /* צורת ההשמעה למשתמש את הקשותיו
    באם מעוניינים במקלדת שונה ממקלדת ספרות, כגון EmailKeyboard או HebrewKeyboard, יש להכניס כאן את סוג המקלדת
    [ראו example.js]
    האופציות הקיימות:
    "Number" | "Digits" | "File" | "TTS" | "Alpha" | "No" | "HebrewKeyboard" |
    "EmailKeyboard" | "EnglishKeyboard" | "DigitsKeyboard" | "TeudatZehut" |
    "Price" | "Time" | "Phone" | "No"
    פירוט על כל אופציה ניתן למצוא בתיעוד מודול API של ימות המשיח, תחת"הערך השישי (הקשה)".
    */
    
    typing_playback_mode: "No",
    
    /* האם לחסום הקשה על כוכבית */
    block_asterisk_key: false,
    
    /* האם לחסום הקשה על אפס */
    block_zero_key: false,
    
    /* החלפת תווים*/
    replace_char: "",
    
    /* ספרות מותרות להקשה - מערך
    [1, 2, 3 ...]
    */
    digits_allowed: [],
    
    /* כמה פעמים להשמיע את השאלה לפני שליחת תשובת "None" (כלומר תשובה ריקה). ברירת מחדל פעם אחת */
    amount_attempts: "",
    
    /*
    האם לאפשר תשובה ריקה - או שלאחר זמן ההמתנה יושמע "לא הוקשה בחירה" וידרוש להקיש
    ברירת מחדל לא מאפשר תשובה ריקה
    */
    allow_empty: false,
    
    /*
    הערך שיישלח כשלא הוקשה תשובה. ברירת מחדל "None"
    ניתן להעביר גם ערכים שאינם מחרוזת, לדוגמה null והערך שיתקבל מהread יהיה null ולא 'null'
    */
    empty_val: "None",
    
    /* האם לחסום שינוי שפת מקלדת */
    block_change_keyboard: false,
}
```

--------------------------------

### Yemot Router2 API Documentation

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

This section details the parameters and data handling within the Yemot Router2. It covers how incoming request data is stored and accessed.

```APIDOC
values:
  Description: Contains all parameters sent from Yemot.
  HTTP GET Requests:
    Contains the query string.
  HTTP POST Requests (api_url_post=yes):
    Contains the request body.
```

--------------------------------

### Music on Hold Data Structure

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Specifies the data structure for the 'music_on_hold' type, which includes the music file name and an optional maximum duration in seconds. It also provides a link for available music types and instructions for creating new ones.

```javascript
{
    musicName: string,
    maxSec: number // optional
}
```

--------------------------------

### Express.js Integration with Yemot Router2

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Demonstrates how to correctly integrate the Yemot Router2 with an Express.js application, addressing a common TypeScript typing error by using the `asExpressRouter` property.

```typescript
import { Router } from 'express';
const router = YemotRouter();
app.use(router.asExpressRouter);
```

--------------------------------

### Call Routing API

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

API methods for controlling call flow. Includes functions to move calls between folders, restart extensions, hang up calls, send messages, and route calls to different Yemot systems.

```APIDOC
go_to_folder(target)
  - Moves the call to a specified folder.
  - Can use relative paths or the string 'hangup' to disconnect.
  - Example: call.go_to_folder('/path/to/folder') or call.go_to_folder('hangup')

restart_ext()
  - Restarts the current extension.
  - Equivalent to: call.go_to_folder(`/${call.ApiExtension}`)

hangup()
  - Hangs up the call.
  - Equivalent to: call.go_to_folder('hangup')

id_list_message(messages, options?)
  - Plays one or more messages to the user.
  - 'messages' is an array of message objects.
  - 'options' can include 'prependToNextAction' to chain actions.
  - Example: call.id_list_message([{ text: 'Hello' }], { prependToNextAction: true })

routing_yemot(number)
  - Routes the call to another Yemot system without unit cost.
  - Takes a single argument: the target Yemot system number (string).
  - Supports routing between private and public servers.
```

--------------------------------

### Speech Recognition Options

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Default options for speech recognition. This includes language selection, blocking typing during speech, maximum digits for typing, using the recording engine for long texts, and silence/length timeouts.

```js
const options = {
    /*
    שפת הדיבור
    ברירת מחדל עברית או מה שהוגדר בlang בשלוחה,
    רשימת השפות הזמינות להגדרה: https://did.li/m1lrl
    */
    lang: '',

    /*
    האם לחסום הקשה במצב זיהוי דיבור
    ברירת מחדל מאפשר להקיש תוך כדי הדיבור, כלומר המחייג בוחר אם להקיש או לדבר
    */
    block_typing: false,

    /*
    מקסימום ספרות שאפשר להקיש, באם לא נחסמה ההקשה תוך כדי דיבור
    ברירת מחדל לא מוגבל
    */
    max_digits: '',

    /*
    האם להשתמש במנוע הדיבור של הקלטות - נצרך עבור זיהוי טקסט ארוך
    באם מפעילים הגדרה זו, לא ניתן לקלוט הקשות תוך כדי דיבור
    */
    use_records_recognition_engine: false,

    /*
    אחרי כמה שניות של שקט לסיים את ההקלטה,
    רלוונטי רק אם משתמשים במנוע זיהוי טקסטים ארוכים (use_records_recognition_engine)
    */
    quiet_max: '',

    /*
    * מספר שניות מרבי להקלטה, ברירת מחדל: ללא הגבלה
    */
    length_max: ''
};
```

--------------------------------

### Play Time

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Plays a specified time. The exact format and details for representing time are described separately.

```APIDOC
zmanim:
  description: Plays a specified time.
  details: See separate documentation for time object format.
```

--------------------------------

### Play System Message

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Plays a system message identified by a code. System message codes can be found in the provided link.

```APIDOC
system_message:
  description: Plays a system message.
  parameters:
    - name: message_code
      type: string
      description: The code identifying the system message. Example: "M1005" or "1005"
  references:
    - url: https://f2.freeivr.co.il/post/3
      description: List of system messages
```

--------------------------------

### Handling ExitError for Asynchronous Code Execution

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Illustrates a robust method for executing subsequent code after sending a response to the caller by catching the internal `ExitError` thrown by `call.id_list_message`.

```javascript
import { ExitError } from 'yemot-router2';
async function runBigJob (call) {
    try {
        call.id_list_message([
            {
                type: 'text',
                data: 'בסדר, בקשתך תטופל בהקדם'
            }
        ]);
    } catch (error) {
        if (error.isExitError) return;
        throw error;
    };
    await doBigJob();
}
```

--------------------------------

### Executing Heavy Code Asynchronously

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Presents an alternative approach to running computationally intensive code by executing it within an immediately invoked anonymous function before returning the response to the caller.

```javascript
(() => {
    await doBigJob();
})();
call.id_list_message(...);
```

--------------------------------

### Send Custom String to Yemot Server

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

The `send` method allows sending arbitrary strings to the Yemot server, useful for unsupported functionalities. The string is sent exactly as provided without validation or processing. It can be combined with `call.blockRunningUntilNextRequest()` for sequential operations like credit card processing.

```js
await call.send(yourCustomString);
```

--------------------------------

### File Message Type

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Used for playing audio files. The 'data' field should contain the file path or name without the extension. Files can be referenced by their name if they are in the current directory or by a full path.

```javascript
{
  type: "file",
  data: "/1/002"
}
```

--------------------------------

### Play Gregorian Date

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Plays the Gregorian date and speaks the corresponding Hebrew date. The input format is DD/MM/YYYY.

```APIDOC
date:
  description: Plays the Gregorian date and speaks the corresponding Hebrew date.
  parameters:
    - name: date
      type: string
      format: DD/MM/YYYY
      description: The Gregorian date. Example: "28/07/2022"
```

--------------------------------

### Message Object Structure

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Defines the basic structure of a message object, consisting of a type and data field. The 'type' specifies the message category, and 'data' contains the message content.

```javascript
{
  type: string,
  data: string
}
```

--------------------------------

### Play Music on Hold

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Plays music while the caller is on hold. The `maxSec` parameter is optional and specifies the maximum duration in seconds. Refer to the provided link for available music types and instructions on creating new ones.

```APIDOC
music_on_hold:
  description: Plays music on hold.
  parameters:
    - name: musicName
      type: string
      description: The name of the music file to play. Example: "ztomao"
    - name: maxSec
      type: integer
      optional: true
      description: Maximum duration in seconds to play the music.
  references:
    - url: https://f2.freeivr.co.il/topic/44/%D7%9E%D7%95%D7%96%D7%99%D7%A7%D7%94-%D7%91%D7%94%D7%9E%D7%AA%D7%A0%D7%94
      description: Available music types and instructions for creating new ones.
```

--------------------------------

### Handling Invalid Characters in Text-to-Speech

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

This section explains how to handle invalid characters (., -, ', ", &) when converting text to speech. It details the `removeInvalidChars` option, which can be set at the message level or for the entire `read`/`id_list_message` call to silently remove these characters instead of throwing an error.

```javascript
{
  type: "text",
  data: "טקסט. בעייתי.",
  removeInvalidChars: true
}
```

```javascript
const resp = await call.read(messagesWidthInvalidChars, 'tap', { removeInvalidChars: true });
```

```javascript
call.id_list_message(messagesWidthInvalidChars, { removeInvalidChars: true });
```

--------------------------------

### Type Assertion for empty_val in TypeScript

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Shows how to manually define the type for `empty_val` when using the `call.read` method in TypeScript, as the default DTS inference may not cover all cases.

```typescript
const res = await call.read([{ type: 'text', data: 'please type one' }], 'tap', {
    allow_empty: true,
    empty_val: null,
}) as string | null;
```

--------------------------------

### Speech Message Type

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Used for automatic playback of TTS (Text-to-Speech) files. The 'data' field should be the path to the TTS file or its name if it's in the current directory, without the file extension.

```javascript
{
  type: "speech",
  data: "נתיב לקובץ TTS או שם קובץ TTS בתקיה הנוכחית"
}
```

--------------------------------

### Text Message Type

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Used for reading text aloud. The 'data' field should contain the text to be spoken. Special characters that cannot be read aloud should be avoided.

```javascript
{
  type: "text",
  data: "דוגמה לטקסט דוגמה"
}
```

--------------------------------

### Play English Letters

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Plays English letters audibly. This function does not support Hebrew characters. For instance, 'abc' will be spoken as 'A, B, C'.

```APIDOC
alpha:
  description: Plays English letters audibly.
  parameters:
    - name: letters
      type: string
      description: A string of English letters to be spoken. Example: "abc"
  notes:
    - Does not support Hebrew characters.
  example:
    input: "abc"
    output: "A, B, C"
```

--------------------------------

### Digits Message Type

Source: https://github.com/shlomocode/yemot-router2/blob/master/README.md

Used for playing digits. The 'data' field contains the digits to be spoken. This is particularly useful for reading out phone numbers.

```javascript
{
  type: "digits",
  data: "105"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.