---
sidebar_position: 4
title: API Reference
description: Detailed API reference for Firetell JavaScript / TypeScript Client SDK classes, methods, and types.
---

# API Reference

This document provides a detailed description of the classes, methods, events, and types exposed by `@firetell/firetell-client-sdk`.

---

## FiretellClient

The `FiretellClient` manages session initialization, REST call dispatch, per-call Native WebSockets, and real-time background EventSource (SSE) stream subscriptions.

### Constructor

```typescript
new FiretellClient(jwt: string, domain: string)
```

| Parameter | Type     | Default | Description                                                                  |
| :-------- | :------- | :------ | :--------------------------------------------------------------------------- |
| `jwt`     | `string` | —       | The Agent JWT authentication token.                                          |
| `domain`  | `string` | —       | Your full Firetell workspace API domain (e.g. `"yourcompany.firetell.app"`). |

---

### Properties

#### `ready`

- **Type:** `Promise<ISession>`
- **Description:** Resolves when the workspace metadata is fetched, the SSE event stream is established, and the agent session is ready.

#### `connected`

- **Type:** `boolean`
- **Description:** Returns `true` if a call WebSocket or event stream is active.

#### `activeCalls`

- **Type:** `Map<string, Call>`
- **Description:** A map of active call instances keyed by their `callId`.

#### `isWebRTCSupport`

- **Type:** `boolean`
- **Description:** Returns `true` if the current environment supports WebRTC (specifically `RTCPeerConnection`).

#### `sdkVersion`

- **Type:** `string`
- **Description:** The version string of the current SDK (`"1.0.0"`).

---

### Methods

#### `makeCall()`

- **Signature:** `makeCall(call: Call, sdp: RTCSessionDescription): Promise<string>`
- **Description:** Initiates an outbound call via HTTP REST (`POST /api/v1/call-center/calls`), receives a scoped `call_token`, and opens a native WebSocket for WebRTC signaling.

#### `superviseCall()`

- **Signature:** `superviseCall(callId: string, mode: "listen" | "whisper" | "barge"): Promise<ISupervisionResponse>`
- **Description:** Initiates call supervision for supervisors via HTTP REST, receives a scoped `call_token`, and connects to the WebRTC audio stream.

#### `getSessionInfo()`

- **Signature:** `getSessionInfo(): ISession | null`
- **Description:** Returns the active session details if ready; otherwise returns `null`.

#### `getDeviceId()` / `FiretellClient.getOrCreateDeviceId()`

- **Signature:** `client.getDeviceId(storageKey?: string): string` / `FiretellClient.getOrCreateDeviceId(storageKey?: string): string`
- **Description:** Generates or retrieves a unique persistent browser Device ID string stored in `localStorage` (e.g. `"web_550e8400-e29b-41d4-a716-446655440000"`).

#### `logout()`

- **Signature:** `logout(): void`
- **Description:** Ends active calls, closes the SSE event stream, disconnects WebSockets, and clears session state.

#### `destroy()`

- **Signature:** `destroy(): void`
- **Description:** Performs an immediate local cleanup of WebSockets, SSE streams, call objects, and event listeners.

---

### Client Events

Subscribe to these events using `client.events.on(eventName, handler)`.

| Event (Enum / String)                                      | Payload                                                 | Description                                                                                    |
| :--------------------------------------------------------- | :------------------------------------------------------ | :--------------------------------------------------------------------------------------------- |
| `EClientEventName.SESSION` (`"session"`)                   | `ISession \| null`                                      | Fired when a session is ready (payload is `ISession`) or destroyed (payload is `null`).         |
| `EClientEventName.ERROR` (`"error"`)                       | `{ code: number, message: string }`                     | Fired when an error occurs in the connection or signaling layer.                               |
| `EClientEventName.CALL_OFFER` (`"call.offer"`)             | `Call`                                                  | Fired when an incoming call offer is received.                                                 |
| `EClientEventName.AGENT_STATE` (`"agent.state"`)           | `{ event, workspace_id, data, timestamp }`              | Fired via SSE when an agent's presence state changes (`available`, `busy`, `away`, `offline`). |
| `EClientEventName.AGENT_STATE_FORCED` (`"agent.state.forced"`) | `{ event, workspace_id, data, timestamp }`          | Fired via SSE when an agent's state is force-changed by a supervisor.                         |
| `EClientEventName.AGENT_CREATED` (`"agent.created"`)       | `{ event, workspace_id, data, timestamp }`              | Fired via SSE when a new agent account is created in the workspace.                            |
| `EClientEventName.AGENT_UPDATED` (`"agent.updated"`)       | `{ event, workspace_id, data, timestamp }`              | Fired via SSE when an agent account's details or avatar are updated.                           |
| `EClientEventName.AGENT_DELETED` (`"agent.deleted"`)       | `{ event, workspace_id, data, timestamp }`              | Fired via SSE when an agent account is deleted.                                                |
| `EClientEventName.CONTACT_CREATED` (`"contact.created"`)   | `{ event, workspace_id, data, timestamp }`              | Fired via SSE when a new contact is created in the workspace.                                  |
| `EClientEventName.CONTACT_UPDATED` (`"contact.updated"`)   | `{ event, workspace_id, data, timestamp }`              | Fired via SSE when a contact is updated.                                                       |
| `EClientEventName.CONTACT_DELETED` (`"contact.deleted"`)   | `{ event, workspace_id, data, timestamp }`              | Fired via SSE when a contact is deleted.                                                       |

---

## Call

The `Call` class manages WebRTC media streams (`RTCPeerConnection`), local/remote audio/video tracks, and call control actions (hangup, answer, hold, mute, DTMF).

### Constructor

```typescript
new Call(client: FiretellClient, options: CallOptions)
```

| Parameter | Type             | Description                              |
| :-------- | :--------------- | :--------------------------------------- |
| `client`  | `FiretellClient` | Active instance of `FiretellClient`.     |
| `options` | `CallOptions`    | Configuration object for the call setup. |

#### `CallOptions` Interface

| Field        | Type      | Required | Description                                                    |
| :----------- | :-------- | :------- | :------------------------------------------------------------- |
| `to`         | `string`  | ✅       | Target phone number or agent extension.                        |
| `from`       | `string`  | ❌       | Caller identity / number on incoming call offers.              |
| `number`     | `string`  | ❌       | Outbound Caller ID DID phone number.                           |
| `isVideo`    | `boolean` | ❌       | Set to `true` to request video media track. Default: `false`.  |

---

### Call Methods

#### `start()`

- **Signature:** `start(): Promise<void>`
- **Description:** Starts an outbound call. Requests media permissions, gathers full ICE candidates, and calls `client.makeCall()`.

#### `accept()`

- **Signature:** `accept(): Promise<void>`
- **Description:** Accepts an incoming call offer. Sets up local media, generates SDP answer, and connects the call.

#### `reject()`

- **Signature:** `reject(): Promise<void>`
- **Description:** Rejects an incoming call offer and notifies the server.

#### `hangup()`

- **Signature:** `hangup(): Promise<void>`
- **Description:** Terminates the active call and closes the WebRTC peer connection and WebSocket.

#### `sendMute()`

- **Signature:** `sendMute(muted: boolean): void`
- **Description:** Mutes or unmutes local audio tracks and notifies server.

#### `sendDTMF()`

- **Signature:** `sendDTMF(digit: string, duration?: number): Promise<void>`
- **Description:** Sends DTMF tones (`0-9`, `*`, `#`, `A-D`).

---

### Call Events

Subscribe to these events on a `Call` instance using `call.on(eventName, handler)`.

| Event (Enum / String)                                      | Payload                                                 | Description                                                                                    |
| :--------------------------------------------------------- | :------------------------------------------------------ | :--------------------------------------------------------------------------------------------- |
| `ECallEventName.STATE` (`"state"`)                         | `{ state: ECallState, reason?: string, status?: number }` | Fired when the call's signaling state changes (`TRYING`, `RINGING`, `ACTIVE`, `ENDED`, etc.). |
| `ECallEventName.MUTE` (`"mute"`)                           | `{ muted: boolean }`                                    | Fired when the call is muted or unmuted.                                                       |
| `ECallEventName.REMOTE_STREAM` (`"remote_stream"`)         | `{ stream: MediaStream }`                               | Fired when the remote audio/video stream is successfully connected via WebRTC.                 |
| `ECallEventName.ERROR` (`"error"`)                         | `Error`                                                 | Fired when an error occurs during WebRTC negotiation or media gathering.                       |

#### `ECallState` Enum

- `INITIATED`: Call is initializing.
- `TRYING`: SIP 100 Trying received from the server.
- `RINGING`: SIP 180/183 Ringing received.
- `ACTIVE`: Media is connected and active (mapped from `ANSWERED`).
- `HELD`: Call is put on hold.
- `ENDED`: Call terminated normally.
- `CANCEL`: Call was cancelled before answering.
- `ERROR`: Call failed.