Call Flows Integration
Call Flows define the automated routing logic for incoming and outgoing calls. They are built and managed visually using the graphical designer inside the Firetell Console.
Call Flows are compiled from the visual builder, so creating and editing flows is done in the Console only. The REST API exposes read-only endpoints to list and inspect your flows (for example, to find a call_flow_id or audit which numbers are assigned). To add dynamic, server-side logic to a flow, use the two integration nodes described below: Contact Lookup and JSON Call Action (JCA).
Read-only REST Endpoints
Requires ApiKey authentication.
| Method | Endpoint | Description |
|---|---|---|
GET | /call-flows | List call flows (paginated, filterable) |
GET | /call-flows/:id | Get a call flow with its compiled actions |
List Call Flows
GET /call-flows
| Query Parameter | Type | Description |
|---|---|---|
page | number | Page number (min 1) |
limit | number | Items per page (1–100) |
search | string | Text search (max 50 characters) |
sort_field | string | Sort field |
sort_order | string | asc or desc |
trigger_type | string | Filter by inbound or outbound |
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-flows?trigger_type=inbound&page=1&limit=20" \
-H "Authorization: ApiKey sk-YOUR_API_KEY"
{
"data": [
{
"id": "650000000000000000000100",
"title": "Main Inbound IVR",
"trigger_type": "inbound",
"status": "published",
"assigned_dids": ["+14155552671"],
"created_at": "2026-02-01T00:00:00.000Z"
}
],
"meta": { "total": 1, "page": 1, "limit": 20, "total_pages": 1 }
}
Get a Call Flow
GET /call-flows/:id
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-flows/650000000000000000000100" \
-H "Authorization: ApiKey sk-YOUR_API_KEY"
{
"id": "650000000000000000000100",
"title": "Main Inbound IVR",
"trigger_type": "inbound",
"status": "published",
"workspace_id": "my_workspace",
"assigned_dids": ["+14155552671"],
"compiled_actions": [],
"created_at": "2026-02-01T00:00:00.000Z",
"updated_at": "2026-07-13T10:00:00.000Z"
}
Using Outbound Call Flows
A published flow with trigger_type: "outbound" is referenced by its call_flow_id in two places, so every outbound call follows the same routing logic you designed in the visual builder:
| Integration | Where call_flow_id goes | Behavior |
|---|---|---|
| Client API (in-app calling) | Required claim in the client JWT your backend signs with an API Key secret created in the Console | Every call the client app makes is routed through this flow. See Client API overview. |
| Workspace REST API (server-to-server) | Optional call_flow_id field of POST /calls/make | The call executes this flow on answer. Do not send a non-empty actions array at the same time — the request is rejected with 400. |
{
"iss": "sid-650000000000000000000001",
"aud": "client-api",
"sub": "partner_customer_100",
"domain": "acme.firetell.com",
"exp": 1786022400,
"call_flow_id": "cf_650000000000000000000100"
}
curl -X POST "https://{workspace_id}.firetell.app/api/v1/calls/make" \
-H "Authorization: ApiKey sk-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": { "number": "+14155550100", "name": "Customer Support" },
"to": { "number": "+12125550123", "name": "John Doe" },
"call_flow_id": "cf_650000000000000000000100"
}'
Use GET /call-flows?trigger_type=outbound to look up the IDs of your published outbound flows.
Contact Lookup Node (contact_lookup)
The Contact Lookup node allows Firetell to query your CRM, database, or API endpoint to resolve the caller's identity before routing the call.
How it Works
- Internal Fallback (Optional): If the Request URL parameter is left empty, Firetell will automatically search the internal Firetell Call Center database for a contact matching the caller's phone number.
- Webhook Query: If a Request URL is provided, Firetell issues an HTTP
POSTrequest to your configured webhook URL. The request body contains the call context:event(string):"call_flow.contact_lookup".call_id(string): Unique call ID.caller_number(string): The caller's E.164 phone number.destination_number(string): The dialed inbound DID/phone number.workspace_id(string): Workspace identifier.call_flow_id(string): Call flow identifier.
- Your server must respond with a
200 OKJSON payload containing the contact's name.
Expected JSON Response
Firetell scans the response object for a display name using the following fields (in order of priority):
display_namenamefullNamedisplay_titletitle
Example response:
{
"id": "customer_99182",
"display_name": "John Doe",
"tier": "VIP"
}
Telephony Behavior
- Caller ID Display Name: If a name is found, Firetell injects it into the SIP headers. Softphones, WebRTC clients, and physical IP phones will display the contact's name instead of a raw phone number.
- Session Variable: The raw JSON response is saved into the call's channel variable (
firetell_contact_data). This data can be referenced later during the call flow or accessed inside subsequent JCA webhooks.
JSON Call Action Node (json_call_action)
The JSON Call Action (JCA) node allows your server to dynamically direct and control the call flow in real-time by returning a sequence of execution actions.
How it Works
- When a call reaches this node, Firetell sends an HTTP
POSTrequest to your configured backend webhook URL. - Firetell sends the call context (caller number, dialed destination, workspace ID, call flow ID, call ID, and contact lookup data) in the body.
- Your server should process the business logic and respond with a
200 OKcontaining a list ofactionsto execute next.
HTTP POST Request Body
{
"event": "call_flow.jca",
"call_id": "call_e9a0c7eb1a744b55a0ee65",
"workspace_id": "ws_abc123",
"call_flow_id": "cf_xyz987",
"caller_number": "14155550100",
"destination_number": "18005550199",
"contact_data": "{\"display_name\":\"John Doe\",\"tier\":\"VIP\"}" // Stringified response from preceding Contact Lookup node
}
Expected Response
Your server must return a JSON response containing an array of compiled call actions.
Example response (Welcome user, and then bridge to an operator):
{
"actions": [
{
"action": "play",
"params": {
"audio_id": "au_welcome_vip",
"answer_call": true,
"continue_on_play": false
}
},
{
"action": "to_operator",
"params": {
"phone_number": "+14155550123",
"timeout": 45
}
}
]
}
Supported Webhook Actions
The following action objects can be returned in the actions array:
1. Play Audio (play)
Plays a pre-recorded audio file stored in the workspace cache.
audio_id(string, required): ID of the audio metadata resource.answer_call(boolean, optional): Iffalse, streams the audio as early media (SIP 183 Progress) without answering/billing the call. Default:true.continue_on_play(boolean, optional): Iftrue, runs the audio in the background and immediately moves to the next action. Iffalse, blocks call flow until playback ends. Default:false.
2. Text to Speech (tts)
Plays a text announcement using synthetic voice.
text(string, required): The text content to read (max 1000 characters).voice(string, optional): Selected TTS voice identifier.speed(number, optional): Playback speed rate.
3. Collect Digits (ivr)
Waits for the caller to press DTMF keys.
timeout(number, optional): Time in seconds to wait for input. Default:5.max_digits(number, optional): Maximum digits to collect (between 1 and 10). Default:1.
4. To Operator (to_operator)
Bridges the call to an external phone number or direct SIP URI.
to(object, required): Destination call party object:number(string, required): Destination E.164 phone number or SIP URI.name(string, optional): Destination display name.
from(object, optional): Custom outbound caller ID object:number(string, required): Outbound caller ID / DID number owned by your workspace. If omitted, the call flow's assigned DID is used.name(string, optional): Caller ID name displayed on the callee's device.
gateway_id(string, optional): Specific outbound gateway ID to route the call through.timeout(number, optional): Max ringing time in seconds before failover (max 300). Default:30.
5. Connect Agent (connect_agent)
Routes the call to a registered Firetell agent.
agent_id(string, required): Unique agent ID.timeout(number, optional): Max ringing time in seconds. Default:30.
6. Connect Team (connect_team)
Bridges the call to a team queue.
team_id(string, required): Unique team ID.strategy(string, optional): ACD strategy (ring-all,round-robin,sequential,random). Default:ring-all.timeout(number, optional): Ring timeout in seconds. Default:30.
7. Connect Voice Agent (connect_voice_agent)
Bridges the call to a Realtime Conversational Voice AI Agent.
voice_agent_id(string, required): Unique Voice Agent ID (va_...).version(number, optional): Specific agent version number. Defaults to the active published version.timeout(number, optional): Connection timeout in seconds before fallback (1–300). Default:30.max_duration_seconds(number, optional): Maximum session duration limit in seconds (10–3600). Default:300.welcome_message(string, optional): Initial greeting message spoken by the bot upon connection (max 500 characters). Overrides the Voice Agent's default greeting message for this call session.
8. Connect SIP Account (connect_sip)
Routes the call to an internal registered SIP account / extension.
sip_account_id(string, required): Unique SIP account ID (sip_...).timeout(number, optional): Ring timeout in seconds before fallback (1–300). Default:30.
9. Call Recording (recording)
Dynamically controls call recording on the active call session.
action(string, optional): Recording action —start(default) orstop.
10. Voicemail (voicemail)
Records a voicemail message from the caller and uploads it to the S3 workspace cloud.
greeting_audio_id(string, optional): Audio ID to play before recording. If omitted, plays default greeting "Please leave your message after the tone."max_duration(number, optional): Max message recording length in seconds. Default:60.beep(boolean, optional): Play a tone beep sound before recording starts. Default:true.
11. Disconnect (disconnect)
Ends the call session immediately.
cause(string, optional): SIP hangup cause (e.g.NORMAL_CLEARING).
12. Audio Stream Fork (stream)
Fork the call audio in real-time to your own WebSocket server as PCM 16-bit little-endian (s16le) binary WebSocket frames. Your server receives raw PCM audio and can optionally send mono PCM audio back to be played to the caller.
ws_url(string, required): Destination WebSocket URL (wss://orws://). Must be a publicly routable server.track(string, optional): Which legs to fork —both(stereo, default),inbound(caller only),outbound(callee only).sample_rate(number, optional): PCM 16-bit little-endian sample rate in Hz —8000(default) or16000.bidirectional(boolean, optional): Iftrue, audio received from your WS server is played into the call in real-time. Default:false.answer_call(boolean, optional): Answer the call before starting the stream. Default:true.headers(object, optional): Custom headers for the WS handshake, e.g.{ "Authorization": "Bearer token" }. Max 10 entries.
Use Cases & Real-World Examples
[Driver / Courier] (PSTN)
│
│ 1. Calls Virtual Proxy Number (DID)
▼
[Firetell Platform]
│
│ 2. Triggers JCA Webhook POST
▼
[Partner Server] ──► 3. Looks up active delivery order for caller_number
│
│ 4. Responds with to_operator action
▼
[Firetell Platform] ──► 5. Bridges to customer's real phone number
(Caller ID displayed is the Virtual Proxy Number)
Step 1: Firetell sends JCA Webhook
{
"event": "call_flow.jca",
"call_id": "call_9c8df104a8b27e",
"workspace_id": "ws_ecommerce_app",
"call_flow_id": "cf_number_masking",
"caller_number": "14155550144",
"destination_number": "18005550199",
"contact_data": null
}
Step 2: Your Server returns Dynamic Bridge Actions
{
"actions": [
{
"action": "play",
"params": {
"audio_id": "au_connecting_mask_notice",
"answer_call": true,
"continue_on_play": true
}
},
{
"action": "to_operator",
"params": {
"to": {
"number": "+14155550188",
"name": "Customer John"
},
"from": {
"number": "+18005550199",
"name": "Firetell Proxy"
},
"timeout": 30
}
}
]
}
Two-Way Privacy:
Both the caller (driver) and the callee (customer) only see the Virtual Proxy Number on their phone screens, ensuring strict compliance with user privacy regulations and personal data protection standards.
Use Case 2: VIP Customer Dynamic Priority Routing
Route callers dynamically based on their customer tier in your CRM or database.
Scenario:
- When a call arrives, the Contact Lookup node queries your CRM with
caller_number. - The JSON Call Action receives the caller's tier (
VIPvsStandard). - If
VIP, the call is immediately routed to their dedicated Account Manager. IfStandard, it is routed to the general support queue.
Your Webhook Response (VIP Customer):
{
"actions": [
{
"action": "play",
"params": {
"audio_id": "au_vip_welcome_greeting",
"answer_call": true,
"continue_on_play": false
}
},
{
"action": "connect_agent",
"params": {
"agent_id": "agt_account_mgr_alex",
"timeout": 45
}
}
]
}
Your Webhook Response (Standard Customer):
{
"actions": [
{
"action": "connect_team",
"params": {
"team_id": "team_general_support",
"timeout": 30
}
}
]
}
Use Case 3: Expired Order or Invalid Access Handling
If a customer or driver calls after an order has already been completed or canceled, your server can reject the connection gracefully without consuming unnecessary call duration or operator time.
Your Webhook Response:
{
"actions": [
{
"action": "play",
"params": {
"audio_id": "au_order_completed_notice",
"answer_call": true,
"continue_on_play": false
}
},
{
"action": "disconnect",
"params": {
"cause": "NORMAL_CLEARING"
}
}
]
}
Use Case 4: After-Hours On-Call Duty Escalation
Route after-hours emergency calls dynamically based on your company's live on-call schedule (e.g. Opsgenie, PagerDuty, or internal roster).
Your Webhook Response:
{
"actions": [
{
"action": "play",
"params": {
"audio_id": "au_after_hours_emergency",
"answer_call": true,
"continue_on_play": false
}
},
{
"action": "to_operator",
"params": {
"phone_number": "+14155550177",
"timeout": 40
}
}
]
}
Use Case 5: Two-Factor Authentication & Voice OTP (2FA)
Voice OTP delivery provides higher deliverability and enhanced protection compared to standard SMS. You can implement Voice OTP in two ways:
Option A: Inbound Reverse Voice OTP (User Calls Verification Number)
- The user requests 2FA verification on your website/app and is prompted to call your verification number from their registered phone.
- The incoming call hits the Call Flow and triggers the JSON Call Action with
caller_number. - Your server looks up the pending 2FA login session for that phone number and responds with a sequence of pre-recorded audio digit clips (e.g.
0–9) or dynamic TTS. - Firetell answers, plays the greeting, sequentially plays each OTP digit, and hangs up immediately.
{
"actions": [
{
"action": "play",
"params": {
"audio_id": "au_greeting_2fa",
"answer_call": true,
"continue_on_play": false
}
},
{
"action": "play",
"params": {
"audio_id": "au_digit_9",
"continue_on_play": false
}
},
{
"action": "play",
"params": {
"audio_id": "au_digit_2",
"continue_on_play": false
}
},
{
"action": "play",
"params": {
"audio_id": "au_digit_8",
"continue_on_play": false
}
},
{
"action": "play",
"params": {
"audio_id": "au_digit_4",
"continue_on_play": false
}
},
{
"action": "disconnect",
"params": {
"cause": "NORMAL_CLEARING"
}
}
]
}
Option B: Outbound Voice OTP (Automated Call Broadcast)
Your server proactively triggers an outbound call to the user's phone via the Make Call API passing the exact same OTP action chain with max_duration: 45.
Use Case 6: Real-Time Audio Streaming to Your Server
Use the stream action to fork live call audio to your own WebSocket server during the call. This enables two powerful patterns:
Option A: One-Way Monitoring (Transcription / Compliance)
Stream audio to your server for real-time transcription, sentiment analysis, keyword spotting, or compliance recording — without interrupting the call.
[Caller] ──► [Firetell] ──► Your WS Server (receives PCM audio)
│ │
│ └─ STT / Analytics / Compliance engine
│
└──► [Agent / Operator] (normal call continues)
JCA Webhook Response:
{
"actions": [
{
"action": "play",
"params": {
"audio_id": "au_call_recorded_notice",
"answer_call": true,
"continue_on_play": false
}
},
{
"action": "stream",
"params": {
"ws_url": "wss://analytics.your-server.com/call-stream",
"track": "both",
"bidirectional": false,
"headers": {
"Authorization": "Bearer YOUR_INTERNAL_TOKEN"
}
}
}
]
}
Your WebSocket server receives binary PCM 16-bit little-endian audio frames continuously while the call is active. When the call ends, the connection closes automatically.
Option B: Full-Duplex Custom AI Voice Bot
Connect the caller to your own AI voice bot — built with any model or TTS provider of your choice. Your server receives the caller's speech and sends synthesized audio back in real-time, which Firetell plays directly into the call.
[Caller] ◄──► [Firetell] ◄──► Your WS Server
│
├─ STT (caller speech → text)
├─ LLM (generate response)
└─ TTS (text → PCM audio → caller)
JCA Webhook Response:
{
"actions": [
{
"action": "stream",
"params": {
"ws_url": "wss://bot.your-server.com/voice-session",
"track": "both",
"sample_rate": 8000,
"bidirectional": true,
"headers": {
"Authorization": "Bearer YOUR_BOT_TOKEN",
"X-Session-Context": "support"
}
}
}
]
}
WebSocket protocol your server must implement:
| Direction | Frame type | Content |
|---|---|---|
| Firetell → Your server | Binary | PCM 16-bit little-endian audio at sample_rate Hz (stereo if track=both: caller on left, callee on right) |
| Your server → Firetell | Binary | Mono PCM 16-bit little-endian audio at sample_rate Hz — bot speech to play to caller |
| Your server → Firetell | Text (JSON) | {"type":"killAudio"} — stop queued bot audio immediately (barge-in) |
call_id, workspace_id, caller_number, caller_name, destination_number, and stream_type=firetell_stream are automatically appended to your ws_url as query parameters so your server can identify the call and caller without needing custom headers.
bidirectional: true requires the call to be answered before audio can flow in both directions. The stream action handles this automatically when answer_call: true (the default).