# EXTERNAL CONTRACT: Yemot HaMashiach API Integration

This document defines the exact wire-protocol required to implement `channels/ivr/YemotAdapter.ts`. Do not invent a standard JSON REST interface for the IVR webhook. You MUST follow this proprietary format.

## 1. Webhook Inbound (Yemot -> Our Server)
When a user calls, Yemot HaMashiach triggers a `POST` or `GET` request to our endpoint `/api/ivr/yemot`.
Data is sent as standard URL-encoded form data (`application/x-www-form-urlencoded` or query string).

**Key Parameters received from Yemot:**
* `ApiCallId`: Unique session ID for the call (String). Map this to `call_session_id`.
* `ApiPhone`: The caller's phone number (String, e.g., "0501234567").
* `ApiDID`: The system phone number the user dialed.
* `ApiExtension`: The current routing folder in Yemot.
* *Dynamic Parameters:* Any variable we requested in the previous step (e.g., `PinCode=123456`).

## 2. Webhook Outbound (Our Server -> Yemot)
Our server must respond with a plain text string (Content-Type: `text/plain` or `text/html`, NOT `application/json`), formatted as `key=value&key2=value2`.

### Supported Commands (to be implemented in YemotAdapter):

**A. Read Text (TTS)**
To read text to the caller without expecting input:
`id_list_message=t-[Text]`
*Example:* `id_list_message=t-ברוכים הבאים לטיפת זהב`

**B. Get User Input (Read)**
To ask the user to press keys:
`read=t-[Text]=[VarName],[Replay],[MinDigits],[MaxDigits],[TimeoutSeconds],[RecordType]`
* `Text`: The text to synthesize (TTS).
* `VarName`: The key that Yemot will use to send the input back to our server in the next request.
* `Replay`: Usually `no` (whether the user can press a key to hear the message again).
* `MinDigits`: Minimum digits to press (e.g., 1).
* `MaxDigits`: Maximum digits (e.g., 6).
* `TimeoutSeconds`: Wait time for input (e.g., 7).
* `RecordType`: `No` (since this is DTMF, not voice recording).
*Example:* `read=t-הקישו קוד אישי=PinCode,no,1,1,6,No`
*Combined Example (TTS + Input):* `id_list_message=t-ברוכים הבאים&read=t-הקישו קוד=PinCode,no,1,1,6,No`

**C. Routing (Go To Folder)**
To move the user to a different extension or hang up:
`go_to_folder=[Destination]`
* To hang up: `go_to_folder=hangup`
*Example:* `id_list_message=t-הגישה נדחתה&go_to_folder=hangup`

**D. Voice Recording**
To record a voice note from the user:
`record=[VarName],[Replay],[RecordLengthSeconds],[TimeoutSeconds]`
*Example:* `record=DamageDescriptionVoice,no,180,5`
*Note:* After recording, Yemot will call the webhook again. The parameter `DamageDescriptionVoice` will contain the `provider_ref` (e.g., `Folder/1/Message/000.wav`) which the `VoiceNoteService` must save as `PENDING_UPLOAD`.

## 3. Developer API: Fetching Recordings
To ingest (`voiceIngest` worker) the recorded audio file from Yemot servers to our Azure Blob storage.

**Endpoint:** `GET https://www.call2all.co.il/ym/api/DownloadFile`
**Parameters (Query String):**
* `token`: API Token (Format: `0771234567:Password`)
* `path`: The `provider_ref` received during the recording step (e.g., `ivr2:Directory/1/000.wav`).

The response will be the raw binary audio file (usually `.wav` or `.mp3`). The adapter must pipe this buffer to `ImageService`/Storage as a secure, private blob.