@keystrokehq/twilio

Official Keystroke integration for Twilio. Phase 1 ships Twilio's core transactional communication surface: Programmable SMS/MMS, Messaging Services (A2P 10DLC, toll-free verification, alpha senders), Programmable Voice (calls, recordings, conferences), Verify v2 (OTP, factors, challenges), Lookups v1/v2, Conversations v1 (default and service-scoped), phone-number provisioning, and account / API-key management.

Later phases will add Studio, TaskRouter, Flex, Programmable Video, Event Streams, Super SIM, Serverless, Sync, Insights, Bulk Exports, Trust Hub, Numbers (porting / hosted / regulatory), SIP, Marketplace, Pricing, Notify, Monitor, and Access Token minting.

Install

pnpm add @keystrokehq/twilio

Connect

Twilio is an API-key integration. Store these values in your Keystroke vault:

| Vault key | Required | Notes | | --------------------------- | -------- | ------------------------------------------------------------------- | | TWILIO_ACCOUNT_SID | yes | Primary or subaccount SID (AC…). | | TWILIO_AUTH_TOKEN | yes | Primary account auth token. Used for REST fallback and HMAC-SHA1 webhook signature verification. | | TWILIO_API_KEY_SID | no | Preferred REST principal (SK…). Use with TWILIO_API_KEY_SECRET. | | TWILIO_API_KEY_SECRET | no | Secret paired with TWILIO_API_KEY_SID. | | TWILIO_SUBACCOUNT_SID | no | Target a subaccount without rotating principals. |

import { twilio } from '@keystrokehq/twilio/connection';

Send an SMS

import { sendMessage } from '@keystrokehq/twilio/messaging';

await sendMessage.run({
  to: '+15551230001',
  from: '+15559990001',
  body: 'Hello from Keystroke.',
});

Verify an OTP

import {
  createVerification,
  createVerificationCheck,
} from '@keystrokehq/twilio/verify';

await createVerification.run({
  serviceSid: 'VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  to: '+15551230001',
  channel: 'sms',
});

await createVerificationCheck.run({
  serviceSid: 'VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  to: '+15551230001',
  code: '123456',
});

Look up a phone number (line type intelligence)

import { lookupPhoneNumberV2 } from '@keystrokehq/twilio/lookups';

const profile = await lookupPhoneNumberV2.run({
  phoneNumber: '+15551230001',
  fields: ['line_type_intelligence', 'caller_name'],
});

Triggers

Every Phase 1 trigger is a direct-binding webhook helper verified with X-Twilio-Signature. Expose the returned bindings inside a Keystroke workflow.

import { webhooks } from '@keystrokehq/twilio/triggers';

export const onInboundSms = webhooks.incomingMessage({
  filter: (payload) => payload.body?.includes('STOP') === false,
});

export const onCallCompleted = webhooks.callStatusCompleted();

export const onVerificationApproved = webhooks.verifyVerificationApproved();

export const onMessageAdded = webhooks.conversationsOnMessageAdded();

Support surface

| Subpath | Purpose | | ---------------------------------------------------- | ----------------------------------------------------------- | | @keystrokehq/twilio/connection | Public credential set, TwilioCredentials type. | | @keystrokehq/twilio/client | Hand-rolled fetch client (for custom operations). | | @keystrokehq/twilio/schemas | Zod schemas for every resource and webhook payload. | | @keystrokehq/twilio/events | Twilio event-type string unions and enums. | | @keystrokehq/twilio/verification | verifyTwilioWebhookRequest, signature base-string helper. | | @keystrokehq/twilio/errors | TwilioApiError class and classification. | | @keystrokehq/twilio/messaging | Programmable SMS / MMS / Media / Short Codes. | | @keystrokehq/twilio/messaging-services | Messaging Services + A2P 10DLC + toll-free verification. | | @keystrokehq/twilio/voice | Calls, call events, feedback, notifications. | | @keystrokehq/twilio/recordings | Recordings, transcriptions, add-on results. | | @keystrokehq/twilio/conferences | Conferences, participants, conference recordings. | | @keystrokehq/twilio/phone-numbers | Available + incoming phone numbers, caller IDs, addresses. | | @keystrokehq/twilio/accounts | Accounts, subaccounts, balance. | | @keystrokehq/twilio/keys | API keys, signing keys, connect apps, network traversal. | | @keystrokehq/twilio/verify | Verify v2: services, verifications, factors, challenges. | | @keystrokehq/twilio/lookups | Lookups v1 + v2. | | @keystrokehq/twilio/conversations | Conversations v1 default scope. | | @keystrokehq/twilio/conversation-services| Conversations v1 service-scoped. |

Hidden subpaths (_official, _runtime) are for Keystroke platform use only. End-user authoring code must not import them.

Webhook signature verification

All Phase 1 triggers call verifyTwilioWebhookRequest internally. For custom webhook endpoints outside this package, import the helper directly:

import { verifyTwilioWebhookRequest } from '@keystrokehq/twilio/verification';

const result = verifyTwilioWebhookRequest({
  url: request.url,
  method: request.method,
  headers: request.headers,
  rawBody: request.rawBody,
  form: request.form,
  authToken: credentials.TWILIO_AUTH_TOKEN,
});

if (!result.valid) {
  throw new Error(`Twilio webhook rejected: ${result.reason}`);
}

JSON-bodied webhooks (Conversations service-scoped, Event Streams, some Flex callbacks) are verified via the bodySHA256 query parameter plus the signature; the helper handles both encodings.

License

MIT