skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
team-telnyx/ai50 installs

telnyx-voice-gather-javascript

Collect DTMF input and speech from callers using standard gather or AI-powered gather. Build interactive voice menus and AI voice assistants. This skill provides JavaScript SDK examples.

How do I install this agent skill?

npx skills add https://github.com/team-telnyx/ai --skill telnyx-voice-gather-javascript
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is safe to use for its intended purpose of managing voice calls via the Telnyx API, but it inherently processes untrusted caller input through AI services, which introduces a surface for indirect prompt injection.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

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

Telnyx Voice Gather - 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
  publicKey: process.env['TELNYX_PUBLIC_KEY'], // Required for client.webhooks.unwrap() (webhook verification)
});

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 result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait, then retry the request (bounded exponential backoff)
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    // ...retry the call here (give up after a few attempts)
  } 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');
    }
  }
  throw err; // Re-throw: a failed request must never look like success to the caller
}

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).

Add messages to AI Assistant

Add messages to the conversation started by an AI assistant on the call.

POST /calls/{call_control_id}/actions/ai_assistant_add_messages

Optional: client_state (string), command_id (string), messages (array[object]), trigger_response (boolean)

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

console.log(response.data);

Returns: result (string)

Start AI Assistant

Start an AI assistant on the call. Expected Webhooks:

  • call.conversation.created includes conversation_id during startup
  • call.conversation.ended
  • call.conversation_insights.generated

POST /calls/{call_control_id}/actions/ai_assistant_start

Optional: assistant (object), client_state (string), command_id (string), greeting (string), interruption_settings (object), message_history (array[object]), participants (array[object]), send_message_history_updates (boolean), transcription (object)

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

console.log(response.data);

Returns: conversation_id (uuid), result (string)

Stop AI Assistant

Stops the AI assistant currently engaged on the call. The call remains active and can continue with other call control commands.

POST /calls/{call_control_id}/actions/ai_assistant_stop

Optional: client_state (string), command_id (string)

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

console.log(response.data);

Returns: result (string)

Gather

Gather DTMF signals to build interactive menus. You can pass a list of valid digits. The Answer command must be issued before the gather command.

POST /calls/{call_control_id}/actions/gather

Optional: client_state (string), command_id (string), gather_id (string), initial_timeout_millis (int32), inter_digit_timeout_millis (int32), maximum_digits (int32), minimum_digits (int32), terminating_digit (string), timeout_millis (int32), valid_digits (string)

const response = await client.calls.actions.gather('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ', {
    minimum_digits: 1,
    maximum_digits: 4,
});

console.log(response.data);

Returns: result (string)

Gather stop

Stop current gather. Expected Webhooks:

  • call.gather.ended

POST /calls/{call_control_id}/actions/gather_stop

Optional: client_state (string), command_id (string)

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

console.log(response.data);

Returns: result (string)

Gather using AI

Gather parameters defined in the request payload using a voice assistant. You can pass parameters described as a JSON Schema object and the voice assistant will attempt to gather these informations.

POST /calls/{call_control_id}/actions/gather_using_ai — Required: parameters

Optional: assistant (object), client_state (string), command_id (string), gather_ended_speech (string), greeting (string), interruption_settings (object), language (object), message_history (array[object]), send_message_history_updates (boolean), send_partial_results (boolean), transcription (object), user_response_timeout_ms (integer), voice (string), voice_settings (object)

const response = await client.calls.actions.gatherUsingAI('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ', {
  parameters: {
    properties: 'bar',
    required: 'bar',
    type: 'bar',
  },
});

console.log(response.data);

Returns: conversation_id (uuid), result (string)

Gather using audio

Play an audio file on the call until the required DTMF signals are gathered to build interactive menus. You can pass a list of valid digits along with an 'invalid_audio_url', which will be played back at the beginning of each prompt. Playback will be interrupted when a DTMF signal is received.

POST /calls/{call_control_id}/actions/gather_using_audio

Optional: audio_url (string), client_state (string), command_id (string), inter_digit_timeout_millis (int32), invalid_audio_url (string), invalid_media_name (string), maximum_digits (int32), maximum_tries (int32), media_name (string), minimum_digits (int32), terminating_digit (string), timeout_millis (int32), valid_digits (string)

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

console.log(response.data);

Returns: result (string)

Gather using speak

Convert text to speech and play it on the call until the required DTMF signals are gathered to build interactive menus. You can pass a list of valid digits along with an 'invalid_payload', which will be played back at the beginning of each prompt. Speech will be interrupted when a DTMF signal is received.

POST /calls/{call_control_id}/actions/gather_using_speak — Required: voice, payload

Optional: client_state (string), command_id (string), inter_digit_timeout_millis (int32), invalid_payload (string), language (enum: arb, cmn-CN, cy-GB, da-DK, de-DE, en-AU, en-GB, en-GB-WLS, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, is-IS, it-IT, ja-JP, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sv-SE, tr-TR), maximum_digits (int32), maximum_tries (int32), minimum_digits (int32), payload_type (enum: text, ssml), service_level (enum: basic, premium), terminating_digit (string), timeout_millis (int32), valid_digits (string), voice_settings (object)

const response = await client.calls.actions.gatherUsingSpeak('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ', {
  payload: 'say this on call',
  voice: 'male',
});

console.log(response.data);

Returns: result (string)


Webhooks

Webhook Verification

Telnyx signs webhooks with Ed25519. Each request includes telnyx-signature-ed25519 and telnyx-timestamp headers. Always verify signatures in production:

Verification needs your account's public key (Mission Control Portal → API Keys → Public Key). The SDK reads it from TELNYX_PUBLIC_KEY (the ## Setup block above passes it explicitly); without it every valid webhook fails verification and the handler below returns 400.

// In your webhook handler (e.g., Express — use raw body, not parsed JSON):
app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await client.webhooks.unwrap(req.body.toString(), {
      headers: req.headers,
    });
    // Signature valid — event is the parsed webhook payload
    console.log('Received event:', event.data.event_type);
    res.status(200).send('OK');
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    res.status(400).send('Invalid signature');
  }
});

The following webhook events are sent to your configured webhook URL. All webhooks include telnyx-timestamp and telnyx-signature-ed25519 headers for Ed25519 signature verification. Use client.webhooks.unwrap() to verify.

EventDescription
CallAIGatherEndedCall AI Gather Ended
CallAIGatherMessageHistoryUpdatedCall AI Gather Message History Updated
CallAIGatherPartialResultsCall AI Gather Partial Results
callGatherEndedCall Gather Ended

Webhook payload fields

CallAIGatherEnded

FieldTypeDescription
data.record_typeenum: eventIdentifies the type of the resource.
data.event_typeenum: call.ai_gather.endedThe type of event being delivered.
data.iduuidIdentifies the type of resource.
data.occurred_atdate-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_idstringCall ID used to issue commands via Call Control API.
data.payload.connection_idstringTelnyx connection ID used in the call.
data.payload.call_leg_idstringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_idstringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_statestringState received from a command.
data.payload.fromstringNumber or SIP URI placing the call.
data.payload.tostringDestination number or SIP URI of the call.
data.payload.message_historyarray[object]The history of the messages exchanged during the AI gather
data.payload.resultobjectThe result of the AI gather, its type depends of the parameters provided in the command
data.payload.statusenum: valid, invalidReflects how command ended.

CallAIGatherMessageHistoryUpdated

FieldTypeDescription
data.record_typeenum: eventIdentifies the type of the resource.
data.event_typeenum: call.ai_gather.message_history_updatedThe type of event being delivered.
data.iduuidIdentifies the type of resource.
data.occurred_atdate-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_idstringCall ID used to issue commands via Call Control API.
data.payload.connection_idstringTelnyx connection ID used in the call.
data.payload.call_leg_idstringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_idstringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_statestringState received from a command.
data.payload.fromstringNumber or SIP URI placing the call.
data.payload.tostringDestination number or SIP URI of the call.
data.payload.message_historyarray[object]The history of the messages exchanged during the AI gather

CallAIGatherPartialResults

FieldTypeDescription
data.record_typeenum: eventIdentifies the type of the resource.
data.event_typeenum: call.ai_gather.partial_resultsThe type of event being delivered.
data.iduuidIdentifies the type of resource.
data.occurred_atdate-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_idstringCall ID used to issue commands via Call Control API.
data.payload.connection_idstringTelnyx connection ID used in the call.
data.payload.call_leg_idstringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_idstringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_statestringState received from a command.
data.payload.fromstringNumber or SIP URI placing the call.
data.payload.tostringDestination number or SIP URI of the call.
data.payload.message_historyarray[object]The history of the messages exchanged during the AI gather
data.payload.partial_resultsobjectThe partial result of the AI gather, its type depends of the parameters provided in the command

callGatherEnded

FieldTypeDescription
data.record_typeenum: eventIdentifies the type of the resource.
data.event_typeenum: call.gather.endedThe type of event being delivered.
data.iduuidIdentifies the type of resource.
data.occurred_atdate-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_idstringCall ID used to issue commands via Call Control API.
data.payload.connection_idstringCall Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_leg_idstringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_idstringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_statestringState received from a command.
data.payload.fromstringNumber or SIP URI placing the call.
data.payload.tostringDestination number or SIP URI of the call.
data.payload.digitsstringThe received DTMF digit or symbol.
data.payload.statusenum: valid, invalid, call_hangup, cancelled, cancelled_amd, timeoutReflects how command ended.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/team-telnyx/ai/telnyx-voice-gather-javascript">View telnyx-voice-gather-javascript on skillZs</a>