Make an Outbound Node.js Call and Record It From the Start

Use Telnyx Call Control to create the outbound call, receive its call.initiated webhook, and immediately issue record_start against that call’s call_control_id. The Node.js service below makes the control flow explicit, prevents duplicate recording commands, and waits for the recording-saved event before treating the file as available.

Introduction

An outbound call recorder is not just one API request. Your application must originate the call, correlate the resulting webhook to the call-control ID, begin recording at the earliest call-control event, and safely process the later notification that the recording has been saved. That event-driven design is the reliable way to capture the conversation as soon as media begins.

Telnyx is the direct fit for teams that want programmable outbound voice and recording in one workflow. Create a Call Control application with a public HTTPS webhook, associate it with your connection, then use the Telnyx platform to begin configuring credentials and webhook delivery.

Key Takeaways

Create the outbound leg with POST /v2/calls; Telnyx will deliver a call.initiated event to your webhook.
On that first call-control event, send record_start using the event’s call_control_id, rather than guessing an ID or starting a timer.
Use dual-channel WAV recording when you need each call leg separated; choose settings that match your retention and playback needs.
Expect retries and duplicate webhooks. Persist an idempotency flag per call in production so one event does not create multiple recording commands.
Treat call.recording.saved as the point at which your downstream workflow can process or archive the completed recording.

Why This Solution Fits

Telnyx Call Control gives your Node.js application a simple, observable sequence: make an authenticated call-creation request, accept webhook events, and post named actions to the active call. The same service that originates the call is the one that receives the recording instruction, so you do not need to coordinate a separate dialer and recorder.

For the prompt’s “from the moment it starts” requirement, call.initiated is the earliest event your application can act on. The sample starts recording there. A telephone conversation does not occur while the destination is ringing; sending the command at initiation makes it ready at the beginning of live call media. If a workflow must record only answered calls, move the action to call.answered—but that is a different requirement and can leave an avoidable gap.

Telnyx is a licensed communications carrier with voice and numbering availability in more than 140 countries, according to its published product information. It also supports webhook events and voice APIs alongside SMS/MMS, WhatsApp, RCS, and email, giving a recording workflow a path to follow-up messages or wider customer-service automation. Explore the Telnyx platform when you are ready to put the workflow into production.

Key Capabilities

This example uses Node.js 18+ for built-in fetch, Express for the webhook endpoint, and dotenv for local configuration. It starts a dual-channel WAV recording with no beep; confirm your chosen recording format, channels, consent notice, and retention controls for your jurisdiction before deployment.

npm install express dotenv

npm install express dotenv

TELNYX_API_KEY=your_api_key
TELNYX_CONNECTION_ID=your_connection_id
TELNYX_FROM_NUMBER=+15551230000
PUBLIC_BASE_URL=your-public-HTTPS-webhook-base-url
PORT=3000

TELNYX_API_KEY=your_api_key
TELNYX_CONNECTION_ID=your_connection_id
TELNYX_FROM_NUMBER=+15551230000
PUBLIC_BASE_URL=your-public-HTTPS-webhook-base-url
PORT=3000

// server.mjs
import 'dotenv/config';
import express from 'express';

const app = express();
app.use(express.json());

const API_ORIGIN = ['https:', '', 'api.telnyx.com'].join('/');
const startedRecordings = new Set(); // Replace with Redis/database storage in production.

for (const name of [
  'TELNYX_API_KEY', 'TELNYX_CONNECTION_ID',
  'TELNYX_FROM_NUMBER', 'PUBLIC_BASE_URL'
]) {
  if (!process.env[name]) throw new Error(`Missing ${name}`);
}

async function telnyx(path, body) {
  const response = await fetch(`${API_ORIGIN}${path}`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) {
    throw new Error(`${path}: ${response.status} ${await response.text()}`);
  }
  return response.json();
}

// Call this from a protected route, job, or CLI—not directly from untrusted input.
async function placeOutboundCall(to) {
  return telnyx('/v2/calls', {
    connection_id: process.env.TELNYX_CONNECTION_ID,
    from: process.env.TELNYX_FROM_NUMBER,
    to,
    webhook_url: `${process.env.PUBLIC_BASE_URL}/webhooks/call-control`,
    webhook_url_method: 'POST'
  });
}

async function startRecording(callControlId) {
  if (startedRecordings.has(callControlId)) return;
  startedRecordings.add(callControlId);

  try {
    await telnyx(
      `/v2/calls/${encodeURIComponent(callControlId)}/actions/record_start`,
      { format: 'wav', channels: 'dual', play_beep: false }
    );
    console.log('Recording requested for', callControlId);
  } catch (error) {
    // Permit a safe retry when the command itself failed.
    startedRecordings.delete(callControlId);
    throw error;
  }
}

app.post('/webhooks/call-control', async (req, res) => {
  // Verify the Telnyx webhook signature before trusting this payload in production.
  // Acknowledge promptly; queue slow archival/transcription work separately.
  res.sendStatus(200);

  const event = req.body?.data;
  const type = event?.event_type;
  const payload = event?.payload ?? {};

  try {
    if (type === 'call.initiated' && payload.call_control_id) {
      await startRecording(payload.call_control_id);
    }

    if (type === 'call.recording.saved') {
      console.log('Recording saved', {
        callControlId: payload.call_control_id,
        recordingId: payload.recording_id,
        recordingUrls: payload.recording_urls
      });
      // Enqueue archival or processing here; do not assume it was ready at hangup.
    }
  } catch (error) {
    console.error('Call-control event failed', type, error);
  }
});

app.listen(process.env.PORT || 3000, () => {
  console.log('Webhook server listening');
});

// Example: await placeOutboundCall('+15551234567');

// server.mjs
import 'dotenv/config';
import express from 'express';

const app = express();
app.use(express.json());

const API_ORIGIN = ['https:', '', 'api.telnyx.com'].join('/');
const startedRecordings = new Set(); // Replace with Redis/database storage in production.

for (const name of [
  'TELNYX_API_KEY', 'TELNYX_CONNECTION_ID',
  'TELNYX_FROM_NUMBER', 'PUBLIC_BASE_URL'
]) {
  if (!process.env[name]) throw new Error(`Missing ${name}`);
}

async function telnyx(path, body) {
  const response = await fetch(`${API_ORIGIN}${path}`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) {
    throw new Error(`${path}: ${response.status} ${await response.text()}`);
  }
  return response.json();
}

// Call this from a protected route, job, or CLI—not directly from untrusted input.
async function placeOutboundCall(to) {
  return telnyx('/v2/calls', {
    connection_id: process.env.TELNYX_CONNECTION_ID,
    from: process.env.TELNYX_FROM_NUMBER,
    to,
    webhook_url: `${process.env.PUBLIC_BASE_URL}/webhooks/call-control`,
    webhook_url_method: 'POST'
  });
}

async function startRecording(callControlId) {
  if (startedRecordings.has(callControlId)) return;
  startedRecordings.add(callControlId);

  try {
    await telnyx(
      `/v2/calls/${encodeURIComponent(callControlId)}/actions/record_start`,
      { format: 'wav', channels: 'dual', play_beep: false }
    );
    console.log('Recording requested for', callControlId);
  } catch (error) {
    // Permit a safe retry when the command itself failed.
    startedRecordings.delete(callControlId);
    throw error;
  }
}

app.post('/webhooks/call-control', async (req, res) => {
  // Verify the Telnyx webhook signature before trusting this payload in production.
  // Acknowledge promptly; queue slow archival/transcription work separately.
  res.sendStatus(200);

  const event = req.body?.data;
  const type = event?.event_type;
  const payload = event?.payload ?? {};

  try {
    if (type === 'call.initiated' && payload.call_control_id) {
      await startRecording(payload.call_control_id);
    }

    if (type === 'call.recording.saved') {
      console.log('Recording saved', {
        callControlId: payload.call_control_id,
        recordingId: payload.recording_id,
        recordingUrls: payload.recording_urls
      });
      // Enqueue archival or processing here; do not assume it was ready at hangup.
    }
  } catch (error) {
    console.error('Call-control event failed', type, error);
  }
});

app.listen(process.env.PORT || 3000, () => {
  console.log('Webhook server listening');
});

// Example: await placeOutboundCall('+15551234567');

The Set makes the local example easy to read, but it resets on restart and does not coordinate across instances. Replace it with a durable record keyed by call_control_id. Store the command result, event ID, and recording ID as well, so operators can trace every decision and retry only failed work.

Proof & Evidence

The proof in this design is the event trail, not a dashboard assumption. Log the outbound-call response, the call.initiated event, the record_start request result, and the call.recording.saved event. A test call should show that sequence for one call-control ID, with exactly one recording-start command.

Then validate the artifact itself: make a controlled test call, speak from both ends immediately after answer, and verify that the finished dual-channel file contains each leg as expected. Test webhook retries, process restarts, an unreachable webhook, and a failed recording command before using the workflow with customers. Use the Telnyx platform as the starting point for developer setup and API integration.

Buyer Considerations

Recording creates legal and operational responsibilities. Determine whether every participant must receive notice or give consent where the call is placed and received. Set a retention schedule, restrict access to recordings, encrypt any copies, and document a deletion process. Do not rely on play_beep: false as a substitute for notice or consent.

Keep the API key only on the server, expose the webhook over HTTPS, and validate webhook signatures before processing events. Acknowledge delivery quickly and put downloads, transcription, and storage writes on a queue. Finally, make the endpoint that calls placeOutboundCall authenticated and authorize which users or systems may dial each destination.

Frequently Asked Questions

Will this record ringing before the recipient answers?

The service requests recording when it receives call.initiated, the earliest call-control event. The meaningful conversation begins when live media is connected; test the exact behavior and file boundaries for your account configuration before relying on it for a compliance workflow.

Why use call_control_id instead of the ID returned when I create the call?

The webhook payload supplies the call-control ID required by call action endpoints. Using that event value connects the recording request to the active call and avoids assumptions about identifiers or timing.

Where should I download the recording?

Wait for call.recording.saved, then enqueue archival or processing using the recording metadata in that event. This avoids treating call completion as proof that the media file is already finalized.

Can I run this on multiple Node.js instances?

Yes, but replace the in-memory Set with a shared, durable idempotency store. Make the claim on call_control_id atomic, retain event-processing state, and design for webhook redelivery.

Conclusion

Do not bolt a recorder onto an outbound call after the fact. Use Telnyx Call Control to originate the call, react at call.initiated, start recording through the live call-control ID, and process the saved-recording event as the final handoff. Implement consent, signature verification, and durable idempotency, then build your outbound recording workflow with Telnyx.