Skip to main content

Twilio

NearSync integrates with Twilio to provide browser-based voice calling directly from the admin dashboard. This integration powers the Voice tab in Comms HQ, allowing users to make and receive phone calls without leaving the platform.

How Calls Works​

The voice integration uses Twilio's Programmable Voice with the WebRTC-based Voice SDK. Here is the flow:

Call Initiation​

  1. A user clicks to call a contact from the admin dashboard (Comms HQ, or inline from a CRM record).
  2. The frontend requests a voice access token from the hyper-worker edge function. The token is a short-lived JWT scoped to the user's identity with a VoiceGrant permission.
  3. The @nearsync/comms-service package initializes a Twilio Device using this token. The Device connects to Twilio's signaling servers over WebRTC.
  4. When the user places a call, the Device sends the request to Twilio, which hits the configured TwiML webhook on the hyper-worker.
  5. The hyper-worker returns TwiML instructions (the XML-based call control language) telling Twilio how to route the call -- typically a <Dial> verb connecting to the destination phone number.
  6. Twilio bridges the WebRTC audio from the browser to the PSTN (phone network).

Call Events​

During the call, Twilio sends webhook events back to the hyper-worker for state changes like call answered, call ended, and recording completed. These events update the call log in the database so the UI can display call status in real time.

Codec Support​

The Twilio Device is configured with Opus and PCMU codec preferences for optimal audio quality across different network conditions.

What You Can Do​

  • Outbound calls: Click-to-call any phone number from the admin dashboard
  • Call controls: Mute, unmute, and disconnect from the browser UI
  • Call logging: All calls are logged with duration, status, and participant information
  • Demo mode: In development or when Twilio credentials are not configured, the integration falls back to a mock device that simulates call behavior without making real calls

Architecture​

The integration spans two parts of the stack:

  • @nearsync/comms-service package -- Runs in the browser. Handles token retrieval, Twilio Device initialization, call state management, and the mock fallback. This package also handles WhatsApp operations (see the WhatsApp Business integration).
  • hyper-worker edge function -- Runs server-side. Generates voice access tokens using the Twilio SDK, serves TwiML responses for call routing, and processes call event webhooks.

Credentials Required​

To enable voice calling, the following Twilio credentials must be configured:

  • Account SID -- Your Twilio account identifier
  • API Key -- A Twilio API key (not the auth token) used for token generation
  • API Secret -- The secret paired with the API key
  • TwiML App SID -- The SID of a TwiML Application configured in your Twilio console, which tells Twilio where to send webhook requests when calls are initiated

These credentials are configured as edge function secrets. For Managed deployments, NearSync manages the Twilio account. For BYOK deployments, you provide your own Twilio credentials during setup.

Twilio Console Setup​

To configure the TwiML Application in your Twilio console:

  1. Create a TwiML App in the Twilio console under Voice > TwiML Apps
  2. Set the Voice Request URL to your hyper-worker's voice endpoint
  3. Set the HTTP method to POST
  4. Note the TwiML App SID for use in your edge function configuration

If Twilio Is Unavailable​

  • Voice calling is completely unavailable
  • Other Comms HQ features (WhatsApp, email) continue to work independently
  • The UI will show an error state on the Voice tab
  • In development environments, the mock device fallback activates automatically