API Reference
This document provides a detailed description of the classes, methods, streams, and types exposed by firetell_flutter_sdk.
FiretellClient
The main client managing session initialization, REST call dispatch, SSE event streaming, and active call lifecycle.
Constructor
FiretellClient({
required String jwt,
required String domain,
})
| Parameter | Type | Description |
|---|---|---|
jwt | String | Agent JWT authentication token |
domain | String | Workspace API domain (e.g. yourcompany.firetell.app) |
Properties
ready
- Type:
Future<Session> - Description: Resolves when workspace metadata is fetched, SSE stream is connected, and the session is ready.
isConnected
- Type:
bool - Description: Returns
trueif the SSE event stream is currently connected.
activeCalls
- Type:
Map<String, Call> - Description: Map of currently active calls, keyed by call ID.
iceServers
- Type:
List<Map<String, dynamic>> - Description: ICE servers from workspace metadata (or defaults).
baseUrl
- Type:
String - Description: Workspace base URL.
jwt
- Type:
String - Description: Current JWT token.
session
- Type:
Session? - Description: Current session info.
nullbefore authentication or after logout.
Event Streams
| Stream | Type | Description |
|---|---|---|
onCallRing | Stream<CallRingParams> | Incoming call ring notification (from SSE) |
onCallOffer | Stream<Call> | Incoming call with WebRTC ready to answer |
onCallCreated | Stream<Map<String, dynamic>> | New call created in workspace |
onCallStarted | Stream<Map<String, dynamic>> | Call ringing at destination |
onCallAnswered | Stream<Map<String, dynamic>> | Call answered |
onCallEnded | Stream<Map<String, dynamic>> | Call ended |
onCallCanceled | Stream<Map<String, dynamic>> | Call canceled before answer |
onAgentState | Stream<Map<String, dynamic>> | Agent state changed |
onSession | Stream<Session?> | Session state changed |
onError | Stream<Object> | Error event |
onConnectionState | Stream<SseConnectionState> | SSE connection state changes |
Methods
makeOutboundCall()
Future<Call> makeOutboundCall({
required String to,
String? from,
bool isVideo = false,
})
Creates a Call, sets up WebRTC media, gathers Full ICE candidates, calls the REST API, connects the per-call WebSocket, and sends the SDP offer.
getPhoneNumbers()
Future<List<PhoneNumber>> getPhoneNumbers({int page = 1, int limit = 100})
Future<PhoneNumbersResponse> getPhoneNumbersResponse({int page = 1, int limit = 100})
Fetch phone numbers (DIDs) accessible by the authenticated agent/team from GET /api/v1/call-center/phone-numbers. Use the returned number as from (Caller ID) in makeOutboundCall.
handlePushIncomingCall()
Future<Call> handlePushIncomingCall(CallRingParams params)
Creates a Call from push notification parameters and connects the signaling WebSocket. The call is not auto-answered — call call.accept() when the user taps answer.
sendTransfer()
Future<void> sendTransfer(String callId, String target, {String? reason})
Transfer a call via WebSocket (if active) or REST API fallback.
logout()
Future<void> logout({String? deviceId})
Unregisters the device push token on the backend (POST /api/v1/me/logout), hangs up all active calls, closes the SSE stream, and cleans up the local session. Defaults to DeviceIdHelper.getOrCreate() if deviceId is omitted.
destroy()
Fully destroys the client immediately without server communication.
Call
Represents a single VoIP call session with dedicated WebSocket signaling and WebRTC peer connection.
Constructor
Call({
required List<Map<String, dynamic>> iceServers,
CallOptions options = const CallOptions(),
})
Properties
| Property | Type | Description |
|---|---|---|
callId | String? | Unique call identifier |
to | String | Destination number/extension |
from | String | Caller number/extension |
fromName | String | Caller display name |
callState | CallState | Current call state |
active | bool | Whether the call is currently active |
isVideo | bool | Whether the call includes video |
isCameraOff | bool | Whether local camera transmission is disabled/muted |
isMuted | bool | Whether the microphone is muted |
isSpeakerOn | bool | Whether audio is routed to speakerphone (vs earpiece) |
isHold | bool | Whether the call is on hold |
Event Streams
| Stream | Type | Description |
|---|---|---|
onStateChange | Stream<({CallState state, String? reason, Map<String, dynamic>? data})> | Call state changes |
onLocalStream | Stream<MediaStream?> | Local camera/microphone media stream |
onRemoteStream | Stream<MediaStream?> | Remote audio/video stream |
onMuteChange | Stream<bool> | Microphone mute state changes |
onCameraChange | Stream<bool> | Camera state changes (true = off, false = on) |
onSpeakerChange | Stream<bool> | Speakerphone state changes |
Methods
accept()
Future<void> accept()
Accept an incoming call — sets up WebRTC media (audio and video if SDP contains video), creates SDP answer, gathers Full ICE candidates, and sends the answer via WebSocket.
reject()
Future<void> reject()
Reject an incoming call via WebSocket.
rejectViaHttp()
Future<void> rejectViaHttp({
required String baseUrl,
required String callToken,
})
Reject via fast HTTP endpoint (~50ms). Preferred for push-triggered reject when no WebSocket is connected.
hangup()
Future<void> hangup()
End the active call. Sends call.hangup via WebSocket and cleans up WebRTC resources.
mute() / unmute() / toggleMute()
Future<void> mute()
Future<void> unmute()
Future<void> toggleMute()
muteVideo() / unmuteVideo() / toggleCamera()
Future<void> muteVideo()
Future<void> unmuteVideo()
Future<void> toggleCamera()
Mute or resume local video track transmission and notify remote peer via call.camera.
switchCamera()
Future<void> switchCamera()
Switch between the front-facing and rear-facing device cameras.
setSpeakerphoneOn() / toggleSpeaker()
Future<void> setSpeakerphoneOn(bool enable)
Future<void> toggleSpeaker()
Toggle audio output between the device speakerphone (loudspeaker) and earpiece.
onhold() / unhold()
Future<void> onhold()
Future<void> unhold()
Hold/unhold via SDP renegotiation (changes transceiver direction, re-gathers ICE, sends new SDP).
sendDTMF()
void sendDTMF(String digit)
Send a DTMF digit (0-9, *, #, A-D).
transfer()
Future<void> transfer(String target, {String? reason})
Transfer the call to another target (extension, phone number, team ID, SIP account).
connectSignaling()
Future<void> connectSignaling(String wsUrl, String callToken)
Connect the per-call WebSocket and authenticate with call_token. Must complete within 3 seconds.
destroy()
void destroy({bool sendHangup = true})
Clean up all resources (WebSocket, WebRTC, streams).
Models
Session
class Session {
final String sessionId;
final String username;
final String displayName;
final String domain;
final int expiresAt; // Unix timestamp in milliseconds
}
CallOptions
class CallOptions {
final String to;
final String from;
final String fromName;
final String? fromAvatar;
final bool isVideo;
final bool isTransfer;
final String? transferReason;
}
CallRingParams
class CallRingParams {
final String callId;
final String callToken;
final String? wsUrl;
final String callerNumber;
final String callerName;
final String? callerAvatar;
final String calleeNumber;
final String calleeName;
final bool isTransfer;
final String? transferReason;
final bool isVideo;
final int ringTimeoutSecs;
}
Factory constructors:
CallRingParams.fromFcmData(Map<String, dynamic> data)
CallRingParams.fromApnsPayload(Map<String, dynamic> payload)
CallRingParams.fromMap(Map<String, dynamic> map)
MakeCallResponse
class MakeCallResponse {
final String callId;
final String callToken;
final String wsUrl;
}
Enums
CallState
enum CallState {
none, initiated, trying, ringing, answered, active, onHold, ended, error, cancel
}
SseConnectionState
enum SseConnectionState {
connecting, connected, disconnected, reconnecting, error
}