/telnyx-voice-javascript

name: telnyx-voice-javascript
description: >-
  Programmatic call control: make/receive calls, transfer, bridge, gather DTMF,
  stream audio. Real-time call events via webhooks.
metadata:
  author: telnyx
  product: voice
  language: javascript
  generated_by: telnyx-ext-skills-generator
  profile: northstar-v2

<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Voice - JavaScript

Installation

npm install telnyx@6.74.2

Setup

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

All examples below assume `client` is already initialized as shown above.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

try {
  const response = await client.calls.dial({
    connection_id: '7267xxxxxxxxxxxxxx',
    from: '+18005550101',
    to: '+18005550100;secure=srtp',
  });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}

Common error codes: `401` invalid API key, `403` insufficient permissions, `404` resource not found, `422` validation error (check field formats), `429` rate limited (retry with exponential backoff).

Important Notes

• **Phone numbers** must be in E.164 format (e.g., `+13125550001`). Include the `+` prefix and country code. No spaces, dashes, or parentheses.
• **Pagination:** List methods return an auto-paginating iterator. Use `for await (const item of result) { ... }` to iterate through all pages automatically.

Operational Caveats

• Call Control is event-driven. After `dial()` or an inbound webhook, issue follow-up commands from webhook handlers using the `call_control_id` in the event payload.
• Outbound and inbound flows are different: outbound calls start with `dial()`, while inbound calls must be answered from the incoming webhook before other commands run.
• A publicly reachable webhook endpoint is required for real call control. Without it, calls may connect but your application cannot drive the live call state.

Reference Use Rules

Do not invent Telnyx parameters, enums, response fields, or webhook fields.

• If the parameter, enum, or response field you need is not shown inline in this skill, read [references/api-details.md](references/api-details.md) before writing code.
• Before using any operation in `## Additional Operations`, read [the optional-parameters section](references/api-details.md#optional-parameters) and [the response-schemas section](references/api-details.md#response-schemas).
• Before reading or matching webhook fields beyond the inline examples, read [the webhook payload reference](references/api-details.md#webhook-payload-fields).

Core Tasks

Dial an outbound call

Primary voice entrypoint. Agents need the async call-control identifiers returned here.

`client.calls.dial()` — `POST /calls`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string (E.164) | Yes | The DID or SIP URI to dial out to. | | `from` | string (E.164) | Yes | The `from` number to be used as the caller id presented to t... | | `connection_id` | string (UUID) | Yes | The ID of the Call Control App (formerly ID of the connectio... | | `timeout_secs` | integer | No | The number of seconds that Telnyx will wait for the call to ... | | `billing_group_id` | string (UUID) | No | Use this field to set the Billing Group ID for the call. | | `client_state` | string | No | Use this field to add state to every subsequent webhook. | | ... | | | +56 optional params in [references/api-details.md](references/api-details.md) |

const response = await client.calls.dial({
  connection_id: '7267xxxxxxxxxxxxxx',
  from: '+18005550101',
  to: '+18005550100;secure=srtp',
});

console.log(response.data);

Primary response fields:

• `response.data.callControlId`
• `response.data.callLegId`
• `response.data.callSessionId`
• `response.data.isAlive`
• `response.data.recordingId`
• `response.data.callDuration`

Answer an inbound call

Primary inbound call-control command.

`client.calls.actions.answer()` — `POST /calls/{call_control_id}/actions/answer`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `call_control_id` | string (UUID) | Yes | Unique identifier and token for controlling the call | | `billing_group_id` | string (UUID) | No | Use this field to set the Billing Group ID for the call. | | `client_state` | string | No | Use this field to add state to every subsequent webhook. | | `webhook_url` | string (URL) | No | Use this field to override the URL for which Telnyx will sen... | | ... | | | +29 optional params in [references/api-details.md](references/api-details.md) |

const response = await client.calls.actions.answer('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);

Primary response fields:

• `response.data.result`
• `response.data.recordingId`

Transfer a live call

Common post-answer control path with downstream webhook implications.

`client.calls.actions.transfer()` — `POST /calls/{call_control_id}/actions/transfer`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string (E.164) | Yes | The DID or SIP URI to dial out to. | | `call_control_id` | string (UUID) | Yes | Uni