OpenPhone API SDK (Unofficial)

A TypeScript SDK for the OpenPhone Public API, built with Bun and designed for modern JavaScript/TypeScript applications.

⚠️ Important Disclaimers

🚨 This is NOT an official OpenPhone SDK. This is an unofficial, community-created SDK.

🤖 This SDK was primarily generated by AI and should be used with caution in production environments.

👤 Published by: @noobforal - This is NOT affiliated with OpenPhone company.

• Unofficial: This is not an official OpenPhone product and is not endorsed by OpenPhone
• Community Support: This SDK is maintained by the community, not by OpenPhone
• Code Quality: While the code has been tested and follows best practices, it may contain issues that weren't caught during initial development
• Security: Please review all code thoroughly before using in production, especially authentication and API key handling
• Testing: Additional testing is recommended beyond the basic test suite included
• Maintenance: This code may require ongoing maintenance and updates as the OpenPhone API evolves
• Support: Limited support is available for AI-generated code

Recommendations:

• Review all code before production use
• Add comprehensive test coverage for your specific use cases
• Monitor for security vulnerabilities regularly
• Consider contributing improvements back to the project
• Use at your own risk

Features

• 🔧 TypeScript First: Full type safety with auto-generated types from OpenAPI spec
• 🚀 Modern: Built with Bun for fast development and execution
• 📦 Tree-shakable: ES modules with tree-shaking support
• 🛡️ Type-safe: End-to-end type safety for all API calls
• 🔄 Auto-generated: Types and client generated from OpenAPI specification
• 📱 Complete API Coverage: Support for calls, messages, phone numbers, and webhooks

Installation

# Using Bun (recommended)
bun add @noobforal/openphone-api-sdk

# Using npm
npm install @noobforal/openphone-api-sdk

# Using yarn
yarn add @noobforal/openphone-api-sdk

# Using pnpm
pnpm add @noobforal/openphone-api-sdk

Quick Start

import { OpenPhoneClient } from '@noobforal/openphone-api-sdk';

// Initialize the client
const client = new OpenPhoneClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.openphone.com', // optional, defaults to this
});

// List phone numbers
const phoneNumbers = await client.listPhoneNumbers();

// List calls
const calls = await client.listCalls({
  phoneNumberId: 'PN123abc',
  participants: ['+1234567890'],
  maxResults: 10,
});

// Send a message
const message = await client.sendMessage({
  content: 'Hello from the SDK!',
  from: 'PN123abc',
  to: ['+1234567890'],
});

API Reference

Configuration

interface OpenPhoneConfig {
  apiKey: string;           // Your OpenPhone API key
  baseUrl?: string;         // API base URL (default: 'https://api.openphone.com')
  timeout?: number;         // Request timeout in ms (default: 30000)
}

Calls API

listCalls(params)

Retrieve a paginated list of calls.

const calls = await client.listCalls({
  phoneNumberId: 'PN123abc',     // Required: OpenPhone number ID
  userId: 'US123abc',            // Optional: User ID
  participants: ['+1234567890'], // Required: Array of participant phone numbers
  since: '2024-01-01T00:00:00Z', // Optional: Start date filter
  createdAfter: '2024-01-01T00:00:00Z', // Optional: Created after filter
  createdBefore: '2024-01-31T23:59:59Z', // Optional: Created before filter
  maxResults: 50,                // Required: Maximum number of results
  pageToken: 'next-page-token',  // Optional: Pagination token
});

getCall(callId)

Get details for a specific call.

const call = await client.getCall('call-id-here');

Messages API

listMessages(params)

Retrieve a chronological list of messages.

const messages = await client.listMessages({
  phoneNumberId: 'PN123abc',
  participants: ['+1234567890'],
  maxResults: 50,
  // ... other optional filters
});

getMessage(messageId)

Get details for a specific message.

const message = await client.getMessage('message-id-here');

sendMessage(params)

Send a new message.

const message = await client.sendMessage({
  content: 'Hello, world!',
  from: 'PN123abc',              // OpenPhone number ID
  to: ['+1234567890'],           // Array of recipient phone numbers
  phoneNumberId: 'PN123abc',     // Optional: Alternative to 'from'
  userId: 'US123abc',            // Optional: User ID
  setInboxStatus: 'done',        // Optional: Set inbox status
});

Phone Numbers API

listPhoneNumbers(params?)

Retrieve the list of phone numbers and users.

const phoneNumbers = await client.listPhoneNumbers({
  userId: 'US123abc', // Optional: Filter by user ID
});

Webhooks API

listWebhooks(params?)

List all webhooks for a user.

const webhooks = await client.listWebhooks({
  userId: 'US123abc', // Optional: Filter by user ID
});

getWebhook(webhookId)

Get details for a specific webhook.

const webhook = await client.getWebhook('webhook-id-here');

Create Webhooks

Create webhooks for different event types:

// Message webhook
const messageWebhook = await client.createMessageWebhook({
  url: 'https://your-app.com/webhooks/messages',
  events: ['message.received', 'message.delivered'],
  label: 'My Message Webhook',
  resourceIds: ['PN123abc'], // or '*' for all resources
  status: 'enabled',
});

// Call webhook
const callWebhook = await client.createCallWebhook({
  url: 'https://your-app.com/webhooks/calls',
  events: ['call.completed', 'call.ringing'],
  label: 'My Call Webhook',
  resourceIds: '*',
  status: 'enabled',
});

// Call summary webhook
const summaryWebhook = await client.createCallSummaryWebhook({
  url: 'https://your-app.com/webhooks/summaries',
  events: ['call.summary.completed'],
  label: 'My Summary Webhook',
  resourceIds: '*',
  status: 'enabled',
});

// Call transcript webhook
const transcriptWebhook = await client.createCallTranscriptWebhook({
  url: 'https://your-app.com/webhooks/transcripts',
  events: ['call.transcript.completed'],
  label: 'My Transcript Webhook',
  resourceIds: '*',
  status: 'enabled',
});

Utility Methods

getConfig()

Get the current client configuration.

const config = client.getConfig();
console.log(config.apiKey); // 'your-api-key-here'

updateConfig(newConfig)

Update the client configuration.

client.updateConfig({
  baseUrl: 'https://staging-api.openphone.com',
  timeout: 60000,
});

Error Handling

All API methods return a response object with data, error, and response properties:

const { data, error, response } = await client.listCalls(params);

if (error) {
  console.error('API Error:', error);
  console.error('Status:', response.status);
  console.error('Status Text:', response.statusText);
} else {
  console.log('Success:', data);
}

TypeScript Support

This SDK is built with TypeScript and provides full type safety. All API responses, request parameters, and client methods are fully typed.

import { OpenPhoneClient, OpenPhoneConfig } from '@openphone/api-sdk';
import type { paths } from '@openphone/api-sdk';

// Full type safety for all operations
const client: OpenPhoneClient = new OpenPhoneClient({
  apiKey: 'your-api-key',
});

// TypeScript will provide autocomplete and type checking
const calls = await client.listCalls({
  phoneNumberId: 'PN123abc',
  participants: ['+1234567890'],
  maxResults: 10,
});

Development

Prerequisites

• Bun (recommended) or Node.js 18+
• TypeScript 5+

Building

# Install dependencies
bun install

# Build the project
bun run build

# Run in development mode
bun run dev

# Run tests
bun test

# Lint code
bun run lint

# Format code
bun run format

Project Structure

src/
├── index.ts          # Main entry point
├── client.ts         # OpenPhoneClient class
└── types.ts          # Auto-generated TypeScript types
dist/                 # Built output
├── index.js          # Bundled JavaScript
├── index.d.ts        # TypeScript declarations
└── index.d.ts.map    # Source maps

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the build and tests
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [email protected]
• 📚 Documentation: https://support.openphone.com/hc/en-us
• 🐛 Issues: GitHub Issues

Changelog

1.0.1

• Initial release
• Full TypeScript support
• Complete API coverage for calls, messages, phone numbers, and webhooks
• Auto-generated types from OpenAPI specification
• Modern ES modules with tree-shaking support