POST
/initiate-call
Initiates an outbound call through the PBX system from a specified extension to a phone number.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
extension | string | Required | Extension number to call from |
phoneNumber | string | Required | Phone number to call (will be sanitized automatically) |
userId | string | Optional | User ID for token generation (included in response if provided) |
Example Request
POST /initiate-call
Content-Type: application/json
{
"extension": "501",
"phoneNumber": "+33672856190",
"userId": "12345"
}
Success Response 200 OK
{
"success": true,
"pbxResponse": "Success: Call initiated",
"callUrl": "https://pbx.example.com/lc_c2c.php?e=501&n=33672856190",
"initializedAt": "2025-01-15T10:30:00+03:00",
"token": "generated_token_here"
}Error Responses
400 Missing extension or phoneNumber
{ "error": "Missing extension in request body" }
502 Call initiation failed
{ "success": false, "pbxResponse": "Error: Failed to connect" }
GET
/extensions
Fetches all active extensions from the PBX system.
Example Request
GET /extensions
Success Response 200 OK
{
"extensions": ["501", "502", "503", "504"]
}Error Responses
500 PBX API configuration missing
503 PBX API unavailable
GET
/call-history/:phoneNumber
Fetches call history for a specific lead by phone number.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
phoneNumber | string (URL) | Required | Lead's phone number |
userId | string (query) | Required | User ID for token generation |
extensions | string (query) | Optional | Comma-separated extensions |
fd | string (query) | Optional | From date (Y-m-d) |
td | string (query) | Optional | To date (Y-m-d) |
lim | string (query) | Optional | Limit results |
Example
GET /call-history/33672856190?userId=12345&extensions=501,502&fd=2025-01-01&td=2025-01-31&lim=50
Success Response 200 OK
{
"calls": [{
"calldate": "2025-01-15 10:30:00",
"src": "501", "dst": "33672856190",
"duration": "00:05:23", "disposition": "ANSWERED",
"billsec": 323, "uniqueid": "1705312200.123"
}],
"phoneNumber": "33672856190",
"count": 1
}
GET
/call-history-rules/:phoneNumber
Fetches call history for rules checking with enhanced phone matching and date filtering.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
phoneNumber | string (URL) | Required | Lead's phone number |
userId | string (query) | Required | User ID for token generation |
extensions | string (query) | Optional | Comma-separated extensions |
fd | string (query) | Optional | From date (Y-m-d) |
td | string (query) | Optional | To date (Y-m-d) |
assignmentDateTime | string (query) | Optional | ISO date to filter calls on/after |
POST
/call-history-bulk
Fetches call history for multiple phone numbers in a single request. Used for bulk checking and inactivity monitoring.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
phoneNumbers | string[] | Required | Array of phone numbers |
userId | string | Required | User ID for token generation |
extensions | string | Optional | Comma-separated extensions |
fromDate | string | Optional | From date (Y-m-d) |
toDate | string | Optional | To date (Y-m-d) |
assignmentDateTime | string | Optional | ISO date to filter calls after |
Example
POST /call-history-bulk
Content-Type: application/json
{
"phoneNumbers": ["33672856190", "94771827347"],
"userId": "12345",
"extensions": "501,502",
"fromDate": "2025-01-01",
"toDate": "2025-01-31"
}
Success Response 200 OK
{
"success": true, "hasCalls": true, "callCount": 5,
"calls": [{ "calldate": "2025-01-15 10:30:00", "src": "501", "dst": "33672856190", "disposition": "ANSWERED" }],
"phoneNumbers": ["33672856190", "94771827347"],
"phoneNumbersChecked": 2
}
GET
/extension-metrics
Fetches comprehensive call metrics and statistics for specific extensions.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Required | User ID for token generation |
extensions | string | Required | Comma-separated extensions |
from | string | Optional | From date (Y-m-d) |
to | string | Optional | To date (Y-m-d) |
Example
GET /extension-metrics?userId=12345&extensions=501,502,503&from=2025-01-01&to=2025-01-31
Success Response 200 OK
{
"success": true,
"data": {
"extensions": [{
"extension": "501", "callCount": 150,
"answered": 120, "unanswered": 20, "busy": 10,
"incoming": 80, "outgoing": 70, "answerRate": 80
}],
"summary": {
"totalExtensions": 3, "totalCalls": 450,
"overallAnswerRate": 80,
"dateRange": { "from": "2025-01-01", "to": "2025-01-31" }
}
}
}
GET
/recording
Fetches a call recording file from the PBX system. Returns audio/wav stream.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Required | User ID for token generation |
file | string | Required | Recording filename (with or without .wav) |
download | string | Optional | Set to "true" to download as attachment |
Example
GET /recording?userId=12345&file=out-33672856190-501-20250115-103000-1705312200.123&download=true
Error Responses
400 Missing file parameter
404 Recording not found
403 Access denied
GET
/webhook/voip
Legacy webhook endpoint for VoIP call events (start, answered, hangup). For advanced events, see /webhook-all-events/voip.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
event | string | Required | Event type: start, answered, or hangup |
uniqueid | string | Required | Unique call identifier |
extension | string | Required | Extension number |
callerid | string | Optional | Caller ID |
dialed | string | Optional | Dialed number |
Notes
- Hangup processed only after 3rd hangup event for same uniqueid
- Auto-retrieves recording filename on hangup
- Sends to AI processing if lead found and configured
GET
/webhook-all-events/voip
Advanced webhook receiving all VoIP call events. Tracks full lifecycle, saves call history, calculates duration, updates leads, and forwards answered calls to AI transcription.
Supported Events
| Event | Description | Saved to DB | AI Transcription |
|---|---|---|---|
start | Call initiated | No (tracked in memory) | No |
ringing | Destination ringing | No | No |
answer-live | Media level connect | No | No |
answered | Call answered | Yes (on hangup) | Yes |
busy | Destination busy | Yes (on hangup) | No |
noanswer | Not answered | Yes (on hangup) | No |
cancel | Caller hung up before answer | Yes (on hangup) | No |
failed | Technical error | Yes (on hangup) | No |
hangup | Call ended — triggers processing | Triggers save | If answered |
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
event | string | Required | Event type |
uniqueid | string | Required | Unique call identifier |
extension | string | Required | Extension number |
callerid | string | Optional | Caller ID |
dialed | string | Optional | Dialed destination |
channel | string | Optional | PBX channel ID |
channel_state | string | Optional | Channel state |
dest_channel | string | Optional | Destination channel |
dest_callerid | string | Optional | Destination caller ID |
dest_uniqueid | string | Optional | Destination unique ID |
dialstring | string | Optional | Dial string with trunk info |
dial_status | string | Optional | ANSWER, BUSY, NOANSWER, CANCEL |
cause | string | Optional | Hangup cause code |
cause_txt | string | Optional | Hangup cause description |
fail_reason | string | Optional | Failure reason |
Call Flow
Answered Call: start → ringing → answer-live → answered → hangup → Calculate duration, save CallHistory, fetch recording, AI transcription Busy/NoAnswer/Cancel/Failed: start → ringing → busy/noanswer/cancel/failed → hangup → Save CallHistory (no recording, no AI)
Features
- Live Dashboard Broadcasting via SSE
- Smart Hangup Deduplication — 1st hangup for terminal states, 3rd as fallback
- Call History for All States (answered, busy, noanswer, cancel, failed)
- Phone Number Extraction from recording filename or webhook data
- Lead Lookup by phone number
- Call Duration calculation (answered → hangup)
- Lead.lastCallDate Update on every call
- AI Transcription for answered calls with recordings
- Direction Detection (inbound/outbound)
GET
/pbx-call-track
Live PBX Call Tracker dashboard — real-time web UI displaying all call events as they happen.
Features
- Real-time events via SSE
- Live stats: Total, Active, Answered, No Answer, Busy, Cancel, Failed
- Filter by event type and extension
- Pause/Resume, Clear Events, Reconnect
- Password protected
GET
/pbx-call-track/events
Server-Sent Events endpoint streaming live PBX call events.
Connection Details
| Property | Value |
|---|---|
| Content-Type | text/event-stream |
| Max Connections | 10 concurrent |
| Heartbeat | Every 30 seconds |
Example Usage
// JavaScript
const eventSource = new EventSource('/pbx-call-track/events');
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Call event:', data.event, data.uniqueid);
};
GET
/call-records
Call Records dashboard page — search PBX call records by extension & date range.
POST
/call-records/search
Search/preview call records from PBX (does not save to database).
POST
/call-records/fetch
Fetch call records from PBX and save to CallHistory database.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
extensions | string[] | Required | Array of extension numbers |
fromDate | string | Required | From date (Y-m-d) |
toDate | string | Required | To date (Y-m-d) |
POST
/call-records/transcribe
Bulk-send answered recordings to Vocalitics (
VOCALITICS_REQUEST_URL). Uses the same payload as /webhook-all-events/voip: leadId, userId, leadsPhoneNumber, recordingName, companyId, callHistoryId, tenantId. Requires matching CallHistory (use Fetch & Save first) and a CRM lead with assignedTo and companyId.
Resources & External Documentation
| Resource | Description | Link |
|---|---|---|
| PBX API Live Status | Notion documentation covering PBX API live status, call tracking workflows, event flows, and architecture | Open in Notion → |