CRM Telephony API

The CRM Telephony API provides endpoints for configuring the company-wide telephony carrier in Admin Settings, minting ephemeral WebRTC tokens for authenticated agents, initiating outbound softphone calls to leads or brokers, and terminating active call sessions. Controller: CrmTelephonyController (/api/crm/telephony and /telephony).

1. Get Active Telephony Configuration

Returns the currently active organization-wide telephony configuration. Sensitive secrets (Auth Tokens, API Keys, Application SIDs) are masked for UI display safety.

GET /api/crm/telephony/config

Response (200 OK)

{
  "id": "c1f7b7f1-8cb4-4db6-9e67-d86ea5278df2",
  "provider": "TWILIO",
  "name": "Twilio Production Trunk",
  "isActive": true,
  "accountSid": "AC12••••••••3456",
  "apiKey": "SK98••••••••7654",
  "subdomain": null,
  "sipDomain": null,
  "fromNumbers": [
    "+12025550199"
  ],
  "applicationSid": "AP11••••••••2233",
  "createdAt": "2026-10-13T10:00:00.000Z",
  "updatedAt": "2026-10-13T10:00:00.000Z"
}

If no provider has been activated, returns null.

2. Connect / Update Telephony Carrier

Validates carrier credentials against the third-party telecom API, auto-provisions required application resources if needed, deactivates any previously active carrier, and sets the new carrier active.

POST /api/crm/telephony/connect
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`provider`	string	Yes	One of `TWILIO`, `TELNYX`, `EXOTEL`, `VOBIZ`.
`name`	string	Yes	Friendly label for this connection (e.g., `Twilio Production`).
`accountSid`	string	Optional	Carrier Account SID (Required for Twilio and Exotel).
`authToken`	string	Optional	Primary secret auth token (Required for Twilio).
`apiKey`	string	Optional	API Key SID or username. For Twilio, auto-provisioned if left blank.
`apiToken`	string	Optional	API Key secret. For Twilio, auto-provisioned if left blank.
`subdomain`	string	Optional	API subdomain (e.g. `api.exotel.com` for Exotel).
`sipDomain`	string	Optional	SIP trunk domain if using custom SIP.
`fromNumbers`	string[]	Optional	Array of registered caller ID phone numbers in E.164 format.
`applicationSid`	string	Optional	TwiML Application SID (`AP...`) or Telnyx App ID. Auto-provisioned for Twilio if blank.

Request Example

{
  "provider": "TWILIO",
  "name": "Company Twilio Softphone",
  "accountSid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "authToken": "your_twilio_auth_token",
  "fromNumbers": [
    "+12025550199"
  ]
}

Response (201 Created)

Returns the activated configuration with masked credentials.

3. Disconnect Carrier

Deactivates the current active carrier configuration.

DELETE /api/crm/telephony/disconnect/:id

Response (200 OK)

{
  "success": true,
  "message": "Carrier TWILIO disconnected."
}

4. Verify Carrier (Outbound Test Call)

Places an outbound verification call to the specified administrator phone number to verify trunk authorization and dial tone.

POST /api/crm/telephony/verify
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`toPhone`	string	Yes	Destination phone number in E.164 format (e.g. `+12025550155`).
`fromNumber`	string	Optional	Selected caller ID from the registered numbers list. Defaults to the first configured number.

Response (200 OK)

{
  "success": true,
  "callId": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

5. Generate Agent WebRTC Access Token

Mints an ephemeral token for the authenticated user session. For Twilio, generates a JWT Access Token with VoiceGrant allowing both incoming and outgoing browser audio.

POST /api/crm/telephony/token

Response (200 OK)

{
  "provider": "TWILIO",
  "identity": "agent_usr_981247",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6InR3aWxpby1mcGE7dj0xIn0...",
  "fromNumber": "+12025550199"
}

6. Initiate Outbound Call

Creates an initial CallRecord in PostgreSQL, marks the calling agent as isOnCall = true, and initiates the outbound call session.

POST /api/crm/telephony/call
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`leadId`	string	Yes	ID of the target lead being called.
`phone`	string	Yes	Destination phone number to dial.
`brokerId`	string	Optional	ID of the broker if calling a Channel Partner.

Request Example

{
  "leadId": "lead_luxury_872",
  "phone": "+12025550144"
}

Response (201 Created)

{
  "callRecordId": "rec_91823746",
  "leadId": "lead_luxury_872",
  "leadName": "Ananya Sharma",
  "toPhone": "+12025550144",
  "fromNumber": "+12025550199",
  "provider": "TWILIO",
  "bridgeType": "WEBRTC",
  "tokenData": {
    "provider": "TWILIO",
    "identity": "agent_usr_981247",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC...",
    "fromNumber": "+12025550199"
  }
}

7. Hangup Call

Terminates an active softphone call session, calculates total elapsed duration in seconds, updates CallRecord.endedAt, and resets User.isOnCall = false.

POST /api/crm/telephony/hangup
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
`callRecordId`	string	Yes	ID of the CallRecord to finalize.

Response (200 OK)

{
  "success": true
}

8. Carrier Webhooks Directory

The following webhook endpoints receive events from carriers during and after softphone calls:

Endpoint	Method	Provider	Description
`/api/crm/telephony/webhooks/twilio-voice`	POST	Twilio	Returns TwiML dial instructions when an agent places a WebRTC call. Enables dual-channel recording.
`/api/crm/telephony/webhooks/twilio-status`	POST	Twilio	Receives call completion status and duration. Resets agent `isOnCall` state.
`/api/crm/telephony/webhooks/twilio-recording`	POST	Twilio	Receives recording URL, uploads audio to Vercel Blob, and triggers Groq Whisper transcription.
`/api/crm/telephony/webhooks/telnyx-voice`	POST	Telnyx	Returns TeXML to bridge lead to agent with dual recording.
`/api/crm/telephony/webhooks/telnyx-recording`	POST	Telnyx	Processes audio recording for Telnyx bridged calls.
`/api/crm/telephony/webhooks/exotel-status`	POST	Exotel	Updates call duration and triggers transcription for Exotel bridged calls.
`/api/crm/telephony/webhooks/vobiz-answer`	POST	Vobiz	Returns Vobiz XML to bridge call to agent phone.
`/api/crm/telephony/webhooks/vobiz-recording`	POST	Vobiz	Processes audio recording for Vobiz calls.
`/api/crm/telephony/webhooks/mock-call`	POST	Dev / Test	Simulates a completed call with transcription for local testing.

System Architecture

API Reference

CRM Telephony API

1. Get Active Telephony Configuration

Response (200 OK)

2. Connect / Update Telephony Carrier

Request Parameters

Request Example

Response (201 Created)

3. Disconnect Carrier

Response (200 OK)

4. Verify Carrier (Outbound Test Call)

Request Parameters

Response (200 OK)

5. Generate Agent WebRTC Access Token

Response (200 OK)

6. Initiate Outbound Call

Request Parameters

Request Example

Response (201 Created)

7. Hangup Call

Request Parameters

Response (200 OK)

8. Carrier Webhooks Directory

​1. Get Active Telephony Configuration

​Response (200 OK)

​2. Connect / Update Telephony Carrier

​Request Parameters

​Request Example

​Response (201 Created)

​3. Disconnect Carrier

​Response (200 OK)

​4. Verify Carrier (Outbound Test Call)

​Request Parameters

​Response (200 OK)

​5. Generate Agent WebRTC Access Token

​Response (200 OK)

​6. Initiate Outbound Call

​Request Parameters

​Request Example

​Response (201 Created)

​7. Hangup Call

​Request Parameters

​Response (200 OK)

​8. Carrier Webhooks Directory

1. Get Active Telephony Configuration

Response (200 OK)

2. Connect / Update Telephony Carrier

Request Parameters

Request Example

Response (201 Created)

3. Disconnect Carrier

Response (200 OK)

4. Verify Carrier (Outbound Test Call)

Request Parameters

Response (200 OK)

5. Generate Agent WebRTC Access Token

Response (200 OK)

6. Initiate Outbound Call

Request Parameters

Request Example

Response (201 Created)

7. Hangup Call

Request Parameters

Response (200 OK)

8. Carrier Webhooks Directory