Twilio

Twilio

Typed Twilio REST API client for Deno, Bun, Node.js and Cloudflare Workers. Send SMS and MMS through the Messages resource; place, list, update and delete voice calls through the Calls resource; and verify webhook signatures. A lightweight alternative to the official twilio Node.js SDK for the endpoints it covers.

Overview

Twilio provides validated sendMessage() and createCall()/getCall()/ listCalls()/updateCall()/deleteCall() calls over the Messages and Calls resources, mapping a camelCase options object to Twilio's form-encoded PascalCase fields and validating the JSON response. It uses RESTler for transport (HTTP Basic Auth, built in) and Guardian for runtime request/response validation. The Calls resource covers placing and managing calls only — not TwiML/IVR generation (the markup that tells Twilio what a call should say/do), which is out of scope for this connect.

Testing your code

Your tests don't need to fake HTTP. Have your code take a Twilio instance and pass in a stand-in that returns the shapes from @tundraconnect/twilio/schemas or throws a real TwilioError:

import { TwilioError } from '@tundraconnect/twilio/errors';

const outage = new TwilioError('SERVICE_UNAVAILABLE', { status: 503 });
console.log(outage.code);

To exercise the client itself against a fake transport, subclass it and reassign the protected _fetch.

Documentation

Topic	Description
API	Client configuration and endpoint methods
Errors	Error codes and diagnostic metadata
Schemas	Public Guardian schemas and inferred types

Upstream

• Twilio REST API reference
• Twilio Programmable Messaging API reference
• Create a Twilio account

Installation

Deno:

deno add jsr:@tundraconnect/twilio

Bun:

bunx jsr add @tundraconnect/twilio

Node.js:

npx jsr add @tundraconnect/twilio

Quick Start

import { Twilio } from '@tundraconnect/twilio';

const client = new Twilio({
  accountSid: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  authToken: 'your-auth-token',
});

const message = await client.sendMessage({
  to: '+14155552671',
  from: '+15017122661',
  body: 'Hello from Twilio!',
});

console.log(message.sid, message.status);

const call = await client.createCall({
  to: '+14155552671',
  from: '+15017122661',
  url: 'http://demo.twilio.com/docs/voice.xml',
});

console.log(call.sid, call.status);

Webhooks

import { Twilio } from '@tundraconnect/twilio';

const client = new Twilio({
  accountSid: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  authToken: 'your-auth-token',
});

export async function onWebhook(req: Request): Promise<void> {
  const raw = await req.text(); // text(), never json()
  const type = req.headers.get('content-type') ?? '';
  if (type.startsWith('application/x-www-form-urlencoded')) {
    // Form-encoded (most webhooks): verify the parsed parameters.
    const params = Object.fromEntries(new URLSearchParams(raw));
    await client.verifyWebhook({ url: req.url, headers: req.headers, params });
  } else {
    // JSON: verify the raw body.
    await client.verifyWebhook({
      url: req.url,
      headers: req.headers,
      payload: raw,
    });
  }
}

See API → Webhooks.

License

MIT. Part of Tundra Connect, typed vendor API clients for Deno, Bun, Node.js and Cloudflare Workers.