Skip to main content
🤖 LLM Friendly: This page is available in raw Markdown format for LLM consumption:api-reference.md|Get full documentation:llms.txt/llms-full.txt

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​

new FiretellClient(jwt: string, domain: string)
ParameterTypeDefaultDescription
jwtstring—The Agent JWT authentication token.
domainstring—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.

getPhoneNumbers()​

  • Signature: getPhoneNumbers(options?: { page?: number; limit?: number }): Promise<IClientPhoneNumbersResponse>
  • Description: Returns the list of accessible DID phone numbers assigned to the agent or agent's teams.

getConversations()​

  • Signature: getConversations(query?: IListConversationsQuery): Promise<IListConversationsResponse>
  • Description: Returns paginated SMS conversation threads (SMS Inbox) accessible by the agent. Supports filtering by status, assigned_to, assigned_team_id, unread_only, and keyword search.

startConversation()​

  • Signature: startConversation(payload: IStartConversationPayload): Promise<IStartConversationResponse>
  • Description: Initiates a new conversation thread or sends an initial outbound SMS/MMS to a customer.

getConversation()​

  • Signature: getConversation(conversationId: string): Promise<IConversation>
  • Description: Returns details of a specific conversation thread.

updateConversation()​

  • Signature: updateConversation(conversationId: string, payload: IUpdateConversationPayload): Promise<IConversation>
  • Description: Updates conversation metadata (assigns/reassigns agent, assigns team, or changes status between open and closed).

markConversationAsRead()​

  • Signature: markConversationAsRead(conversationId: string): Promise<IMarkAsReadResponse>
  • Description: Marks all inbound messages in a conversation as read and resets unread_count to 0.

getConversationMessages()​

  • Signature: getConversationMessages(conversationId: string, query?: IListMessagesQuery): Promise<IListMessagesResponse>
  • Description: Fetches historical messages for a conversation thread in chronological order.

sendConversationMessage()​

  • Signature: sendConversationMessage(conversationId: string, payload: ISendMessagePayload): Promise<IConversationMessage>
  • Description: Dispatches an outbound SMS/MMS reply to the customer in an existing conversation thread.

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)PayloadDescription
EClientEventName.SESSION ("session")ISession | nullFired 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")CallFired when an incoming call offer is received.
EClientEventName.MESSAGE_RECEIVED ("message.received")IMessageReceivedEventFired via SSE when a new inbound SMS message is received from a customer.
EClientEventName.MESSAGE_SENT ("message.sent")IMessageSentEventFired via SSE when an outbound message is dispatched (allows collision avoidance between agents)
EClientEventName.MESSAGE_UPDATED ("message.updated")IMessageUpdatedEventFired via SSE when carrier delivery status transitions (sent, delivered, failed).
EClientEventName.CONVERSATION_UPDATED ("conversation.updated")IConversationFired via SSE when a conversation's status, assignment, or metadata updates.
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​

new Call(client: FiretellClient, options: CallOptions)
ParameterTypeDescription
clientFiretellClientActive instance of FiretellClient.
optionsCallOptionsConfiguration object for the call setup.

CallOptions Interface​

FieldTypeRequiredDescription
tostring✅Target phone number or agent extension.
fromstring❌Caller identity / number on incoming call offers.
numberstring❌Outbound Caller ID DID phone number.
isVideoboolean❌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)PayloadDescription
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")ErrorFired 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.