# AI Provider

Source: https://docs.qvoice.net/ai-provider-websocket/

## Config

This section defines how to configure the AI Provider connection, including media parameters and WebSocket connection details.

### Fields

- **name** (string): Display name of the AI Provider.
- **media** (object): Specifies the audio encoding and sample rate.
- **websocket** (object): Defines the WebSocket endpoint and optional headers used for authentication or custom configuration.

#### `media` object

- **audioFormat** (string): Supported formats are:
- `"pcm16"` — sample rate **24000 Hz**
- `"g711_ulaw"` — sample rate **8000 Hz**
- `"opus"` — sample rate **48000 Hz**
- **sampleRate** (number): Must match the selected audio format.

#### `websocket` object

- **url** (string): Secure WebSocket URL used to connect to the AI Provider.
  Example:
  `wss://cad.fonouc.com:9443/ws/v1/echo`
- **headers** (object, optional): Key–value pairs of headers to include in the connection request.
  Commonly used for authorization tokens or custom metadata.

---

## Events API

This section defines the event types exchanged over the WebSocket connection between the AI Provider and the backend.
Each message is a JSON object containing an `"event"` field that specifies its type.

---

### Event: `start`

Sent once at the beginning of the WebSocket session to initialize the call context.

#### Fields

- **event** (string): Must be `"start"`.
- **start** (object): Contains call initialization data.

#### `start` object

- **callId** (string): Unique identifier of the call.
- **otherLegCallId** (string): Unique identifier of the other leg of the call.
- **callerIdNumber** (string): E.164-formatted phone number of the caller.
- **calleeIdNumber** (string): E.164-formatted phone number of the callee.
- **accountId** (string): Account associated with the call.
- **mediaFormat** (object): Defines the audio encoding and sample rate used for the call.

#### `mediaFormat` object

- **encoding** (string): Audio encoding format. Supported values are:
- `"pcm16"` — sample rate **24000 Hz**
- `"g711_ulaw"` — sample rate **8000 Hz**
- `"opus"` — sample rate **48000 Hz**
- **sampleRate** (number): Must match the selected encoding (24000 for `pcm16`, 8000 for `g711_ulaw`, 48000 for `opus`).

#### Example

```
{
  "event": "start",
  "start": {
    "callId": "call_12345",
    "otherLegCallId": "call_67890",
    "callerIdNumber": "+1234567890",
    "calleeIdNumber": "+1234567891",
    "accountId": "acc_abc123",
    "mediaFormat": {
      "encoding": "pcm16",
      "sampleRate": 24000
    }
  }
}
```

---

### Event: `media`

Carries audio data between the backend and the AI Provider.
Multiple messages of this type are exchanged during the call.

#### Fields

- **event** (string): Must be `"media"`.
- **media** (object): Contains the encoded audio payload.

#### `media` object

- **payload** (string): Base64-encoded audio data.

#### Example

```
{
  "event": "media",
  "media": {
    "payload": "GkXfo59ChoEBQveBAULygQRC84EIQoKEd2VibUKHgQCh..."
  }
}
```

---

### Event: `dtmf`

Sent when the caller presses a key on their phone keypad during the call.
DTMF (Dual-Tone Multi-Frequency) tones are used for interactive voice response (IVR) navigation, entering PIN codes, or other user input scenarios.

#### Fields

- **event** (string): Must be `"dtmf"`.
- **dtmf** (object): Contains the DTMF digit information.

#### `dtmf` object

- **callId** (string): Unique identifier of the call.
- **otherLegCallId** (string): Unique identifier of the other leg of the call.
- **digit** (string): The DTMF digit pressed. Valid values are:
- `"0"` through `"9"` — numeric digits
- `"*"` — asterisk/star key
- `"#"` — pound/hash key
- `"A"`, `"B"`, `"C"`, `"D"` — extended DTMF tones (less common)
- **duration** (number, optional): Duration of the key press in milliseconds.

#### Example

```
{
  "event": "dtmf",
  "dtmf": {
    "callId": "call_12345",
    "otherLegCallId": "call_67890",
    "digit": "5",
    "duration": 100
  }
}
```

#### Use Cases

- **IVR Navigation:** The AI Provider can use DTMF events to navigate menu options (e.g., "Press 1 for sales, Press 2 for support").
- **PIN Entry:** Capture secure numeric input from the caller.
- **Call Transfer:** Use specific key combinations to trigger call transfers or other actions.
- **Interruption Handling:** Detect when a caller wants to interrupt the AI agent by pressing a key.

---

### Event: `hangup`

Sent when the call ends to notify the AI Provider that the session is terminating.
This event is sent immediately before the WebSocket connection is closed.

#### Fields

- **event** (string): Must be `"hangup"`.
- **hangup** (object): Contains hangup information.

#### `hangup` object

- **callId** (string): Unique identifier of the call.
- **otherLegCallId** (string): Unique identifier of the other leg of the call.
- **reason** (string, optional): The reason for the hangup. Common values include:
- `"NORMAL_CLEARING"` — Normal call termination
- `"USER_BUSY"` — Called party is busy
- `"NO_ANSWER"` — No answer from called party
- `"CALL_REJECTED"` — Call was rejected
- `"ORIGINATOR_CANCEL"` — Caller hung up before answer

#### Example

```
{
  "event": "hangup",
  "hangup": {
    "callId": "call_12345",
    "otherLegCallId": "call_67890",
    "reason": "NORMAL_CLEARING"
  }
}
```

#### Use Cases

- **Session Cleanup:** The AI Provider can use this event to clean up resources, save conversation logs, or trigger post-call processing.
- **Analytics:** Track call duration and termination reasons for reporting purposes.
- **State Management:** Gracefully terminate any ongoing AI processing or speech synthesis.

---

## Message Flow Overview

1. **Server → AI Provider:** Sends a single `start` event to begin the session.
2. **Server ↔ AI Provider:** Exchanges continuous `media` events containing audio frames.
3. **Server → AI Provider:** Sends `dtmf` events when the caller presses keypad digits.
4. **Server → AI Provider:** Sends a `hangup` event when the call ends.
5. **Connection Close:** Server closes the WebSocket connection after sending the hangup event.
