03 Core Concepts & Lifecycle

1. Recommended lifecycle (strongly recommended)

1.1 Initialization

• Call setup(config) once at application startup
• Register long-lived “global” event handlers early (e.g., AGENT_STATUS, RECONNECT_ATTEMPT)

1.2 Sign-in phase

• Call login(params) to establish a session with the backend
• Only perform call-control operations after a successful login (outbound, hold, transfer, supervisor monitoring, etc.)

1.3 Runtime

• Use Promise responses as the primary indicator of operation success/failure (recommended)
• Use events to drive UI state and workflow transitions (ringing, bridged, agent state changes, etc.)

1.4 Sign-out / teardown

• Call logout()
• Remove event listeners via off for any handlers you registered

2. Operations (Promises) vs. Events

The SDK provides two information channels:

• Operation response (Promise resolve): whether the backend accepted/executed the operation successfully
• Event notifications (on/off/once): what happened during call lifecycle and state transitions

Typical example:

• When you call previewObCall():
  • You first receive previewObCallResp (operation response)
  • If successful, you then receive events such as previewObCallStart / previewObCallRinging / previewObCallBridge / previewObCallResult

See 10-Key-Flows-Sequence-Diagrams.md for full sequences.

3. Key identifiers: uniqueId vs mainUniqueId

You will see two identifiers across operations/events (treat 06-Types.md as the source of truth):

• uniqueId: per-leg (per-channel) unique identifier
• mainUniqueId: main-call unique identifier used to correlate a full call chain

Many status updates (e.g., agentStatus) include these when deviceStatus=3/4 (ringing/talking).

4. Agent state machine: state / stateAction

Many event payloads include:

• state: coarse-grained agent state (e.g., idle/busy/ringing/talking)
• stateAction: fine-grained action/cause (e.g., “customer ringing for outbound”, “hold”, “consult started”)

Use this to implement UI rules and guardrails (e.g., only allow hold when the agent is talking).

See 08-State-Machine-stateAction.md.

5. Reconnection (reconnectAttempt)

On disconnect, the SDK performs automatic reconnection attempts and emits events:

• attempt: attempt number (starting at 1)
• maxAttempts: max attempts (fixed at 20)

Recommended practice:

• Listen to RECONNECT_ATTEMPT and prompt re-login after max attempts are exceeded
• Gate critical operations (outbound/transfer/supervisor actions) behind “logged in / WS available”

Payload details are in 05-Events.md.

6. Queues & Supervisor use cases

For supervisor/monitoring scenarios:

• getQueueStatus() for on-demand queries
• queueStatus events for queue metrics, queue members, and waiting callers

Types and structures are defined in 06-Types.md.