Twilsock Client Library

Common errors

• Error: Can't connect to twilsock

  cause This error typically indicates an issue with the Twilio Access Token (invalid, expired, incorrect identity) or a network connectivity problem to the Twilsock endpoint.
  fix Verify that the Access Token is freshly generated on your backend, contains the correct identity, and has not expired. Check network connectivity and firewall rules. Ensure the Twilsock URL is correct for your Twilio service.

• TypeError: Twilsock is not a constructor

  cause This usually means the `Twilsock` class was not imported correctly, or the module being imported does not export a constructor named `Twilsock`.
  fix Ensure you are using `import { Twilsock } from 'twilsock';` for ESM environments with TypeScript. Double-check the package installation and file paths if you are attempting to import from a non-standard location.

Warnings

• breaking When integrating `twilsock` into other Twilio SDKs like Twilio Sync, explicitly passing your own `Twilsock` instance via options (e.g., `SyncClient` options) will prevent the SDK from automatically initiating the connection. Developers must manage the `Twilsock` connection lifecycle manually in such advanced scenarios.
  Fix: If providing a custom `Twilsock` instance, ensure you manually call `connect()` on that instance. Otherwise, allow the SDK to manage its internal `Twilsock` client.
• gotcha Twilio client-side SDKs, including those utilizing `twilsock`, require an Access Token that MUST be generated on your application's backend server. Using test credentials or attempting to generate tokens directly client-side is a common mistake and will lead to authentication failures.
  Fix: Implement a secure server-side endpoint to generate Twilio Access Tokens. This endpoint should use your Twilio Account SID and Auth Token (kept secret on the server) to create a token with the appropriate grants and user identity, then return it to your client-side application.
• gotcha The TwilSock service has limits on the number of messages per connection. Exceeding these limits can result in an `ERROR: 51128: Twilsock: Too many messages per connection` and potential disconnection or degraded service.
  Fix: Monitor your application's message rates. If high message volumes are expected, ensure your application logic handles message queuing, rate limiting, or consult Twilio support to discuss increasing account limits if legitimate high throughput is required.
• gotcha The `engines` field in `package.json` specifies `"node": ">=20"`. Running this package with older Node.js versions may lead to unexpected behavior or runtime errors, although it might install without warning.
  Fix: Ensure your Node.js environment is version 20 or newer. Use `nvm` or similar tools to manage Node.js versions if necessary.

Install

• npm install twilsock npm
• yarn add twilsock yarn
• pnpm add twilsock pnpm

Imports

• Twilsock
  wrong:

  const Twilsock = require('twilsock');

  correct:

  import { Twilsock } from 'twilsock';

  The primary class for instantiating the Twilsock client. While CommonJS `require` might work in some environments, ESM named imports are the recommended modern approach for Node.js projects with TypeScript.
• Twilsock.ConnectionState

  import { Twilsock, TwilsockConnectionState } from 'twilsock';
  // or
  import type { TwilsockConnectionState } from 'twilsock';

  Twilsock typically exposes types and enums for connection states (e.g., `CONNECTED`, `DISCONNECTED`). Use named imports for these.

Quickstart

Demonstrates how to initialize the Twilsock client, establish a connection using a (server-generated) access token, handle common connection events, and send/receive basic messages.

import { Twilsock } from 'twilsock';

// In a real application, the ACCESS_TOKEN would be securely fetched from your server.
// DO NOT hardcode Twilio Access Tokens or API keys in client-side code.
// For demonstration, we'll use a placeholder and emphasize server-side generation.
const getAccessTokenFromServer = async (): Promise<string> => {
  // Replace with actual server endpoint to generate Twilio Access Token
  // For example: fetch('/api/twilio-token', { method: 'POST' }).then(res => res.json()).then(data => data.token);
  console.warn('Fetching a placeholder access token. In production, this must come from your backend.');
  return process.env.TWILIO_ACCESS_TOKEN ?? 'YOUR_GENERATED_TWILIO_ACCESS_TOKEN';
};

const main = async () => {
  const accessToken = await getAccessTokenFromServer();
  if (!accessToken || accessToken === 'YOUR_GENERATED_TWILIO_ACCESS_TOKEN') {
    console.error('Failed to get a valid Twilio Access Token. Please provide one.');
    return;
  }

  // Example Twilsock URL. This would be specific to your Twilio service/region.
  const twilsockUrl = 'wss://your-twiliosock-endpoint.twilio.com/v1/ws';

  const client = new Twilsock(twilsockUrl, accessToken, {
    // Optional: Add logging or other configuration
    logLevel: 'debug',
  });

  client.on('connected', () => {
    console.log('Twilsock client connected successfully!');
    // You can now send messages or interact with Twilio services
    client.sendMessage('Hello Twilio!');
  });

  client.on('message', (message: string) => {
    console.log('Received message:', message);
  });

  client.on('disconnected', (reason: string) => {
    console.log('Twilsock client disconnected:', reason);
  });

  client.on('error', (error: Error) => {
    console.error('Twilsock client error:', error.message);
  });

  console.log('Connecting to Twilsock...');
  client.connect();

  // Disconnect after some time for demonstration
  setTimeout(() => {
    console.log('Disconnecting Twilsock after 10 seconds...');
    client.disconnect();
  }, 10000);
};

main().catch(console.error);