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

Client API Overview & Authentication

The Client API allows you to integrate external, third-party end-users, mobile apps, or custom web portals with the Firetell voice platform. Unlike the Agent API (which is designed for call center agents registered in the database), the Client API allows you to authenticate any custom username on-the-fly using a signed JSON Web Token (JWT).

1. Authentication & JWT Payload​

To connect a client device via the SDK, your backend must generate and sign a JWT using the Secret Key of one of your workspace API Keys. The JWT must contain the following claims:

ClaimTypeRequiredDescription
issstringYesThe API Key SID (sid-...) used to sign the token.
audstringYesMust be set to client-api.
substringYesUnique external username/ID (1-64 chars. Allowed: alphanumeric, _, -, .. No @ or spaces).
domainstringYesYour workspace domain (e.g., company.firetell.com).
expnumberYesExpiration timestamp in seconds (Unix epoch time).
call_flow_idstringYesThe outbound Call Flow ID that will handle outbound calls made by this client.

Payload Example​

{
  "iss": "sid-650000000000000000000001",
  "aud": "client-api",
  "sub": "partner_customer_100",
  "domain": "acme.firetell.com",
  "exp": 1786022400,
  "call_flow_id": "cf_650000000000000000000100"
}

:::important Subject (sub) Validation Rules To ensure secure and reliable connection handling and avoid formatting conflicts:

  • Allowed characters: Alphanumeric (a-z, A-Z, 0-9), underscores (_), hyphens (-), and dots (.).
  • Forbidden characters: Special characters, whitespaces, and specifically the @ symbol are strictly prohibited.
  • Length: The sub value must be between 1 and 64 characters long. :::

2. Dynamic Connection Quotas & Limits​

To protect the infrastructure from misuse or intentional DDoS attacks, the following limits are strictly enforced on Client API connections:

  • Per-User Session Limit: A single user ID (sub) can have a maximum of 5 concurrent active sessions (e.g., open tabs or devices).
  • Workspace Limit: All Client API connections in a single workspace are capped at a total of 1000 concurrent active connections.

:::warning Requesting Limit Increases If your production application requires higher concurrent connection capacities, please contact our support team at enterprise@firetell.com to request custom quotas. :::

3. Real-Time Events (call.ring)​

Clients receive real-time updates (such as incoming call alerts) via a Server-Sent Events (SSE) stream at /stream?token={JWT}:

  • Incoming Call Notification (call.ring): When a call is routed to the client, the client device receives a call.ring event to trigger the ringer UI: 
    {
      "event": "call.ring",
      "call_id": "call_1770000000000",
      "call_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "ws_url": "wss://yourcompany.firetell.app/ws",
      "from": {
        "number": "agent_username",
        "name": "Your driver"
      },
      "to": {
        "number": "partner_customer_100",
        "name": "Partner Customer Name"
      },
      "timestamp": "2026-07-30T16:07:00.000Z"
    }

4. Outbound Calling Rule (call_flow_id)​

When a client initiates an outbound call via the Client SDK (by calling the makeCall API), the following rules apply:

  • Strict Call Flow Routing: The call must be routed through the outbound Visual Call Flow identified by the call_flow_id claim in the client's JWT token.
  • Pre-requisite: The call flow assigned to call_flow_id must be pre-configured in the Workspace Portal and have its trigger_type set to outbound.
  • Security & Control: This restriction ensures that end-user calls are securely monitored, formatted, recorded (if configured), and filtered according to your business's outbound calling rules before routing to carriers or external DIDs.

5. Integrating with Client SDK​

Once you have generated a valid Client JWT on your backend, you can pass it to our official frontend Client SDK to initialize the real-time event stream, handle WebRTC audio/video connections, and manage the calling lifecycle on the device.

To install the SDK, import it, and see complete usage guides, please refer to the Client SDK Integration Guide.

6. REST API Reference​

If you are implementing your own WebRTC signaling/client wrapper without using the official Client SDK, you can call the make call REST API directly using your Client JWT.

Initiate Outbound Call​

Initiate an outbound WebRTC call and receive the signaling WebSocket session details.

  • Endpoint: POST /api/v1/call-center/calls/make
  • Headers:
    • Authorization: Bearer <client-api-jwt>
    • Content-Type: application/json

Request Body​

{
  "to": "agent_username",
  "from": "",
  "type": "audio"
}

Response Example (201 Created)​

{
  "call_id": "call_1770000000000",
  "ws_url": "wss://yourcompany.firetell.app/call-session",
  "call_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

After receiving this response, the client must connect to ws_url and send a session.connect event with the call_token within 3 seconds to complete signaling authentication.