Respond.io TypeScript SDK

A professional, type-safe TypeScript SDK for the respond.io Developer API v2.

Features

• 🎯 Full Type Safety - Complete TypeScript definitions for all API endpoints
• 🔄 Automatic Retries - Built-in retry logic for failed requests with exponential backoff
• ⚡ Rate Limiting - Automatic handling of rate limits with retry-after headers
• 🛡️ Error Handling - Comprehensive error handling with detailed error messages
• 📦 Modern API - Clean, intuitive API design inspired by AWS SDK v3
• 🔍 Fully Documented - Extensive JSDoc comments and usage examples
• ✅ Well Tested - 80%+ test coverage with Jest

Table of Contents

• Installation
• Quick Start
• Authentication
• API Reference
  • Contacts
  • Messaging
  • Comments
  • Conversations
  • Space (Workspace)
• Error Handling
• TypeScript Support
• Testing
• Contributing

Installation

npm install @respond-io/typescript-sdk

# or using yarn
yarn add @respond-io/typescript-sdk

# or using pnpm
pnpm add @respond-io/typescript-sdk

Quick Start

import { RespondIO } from '@respond-io/typescript-sdk';

const client = new RespondIO({
  apiToken: 'your-api-token',
});

// Get a contact
const contact = await client.contacts.get('id:123');
console.log(contact.firstName, contact.email);

// Send a message
await client.messaging.send('email:[email protected]', {
  message: {
    type: 'text',
    text: 'Hello from the SDK!',
  },
});

Examples

This repository includes two example projects to demonstrate how to use the SDK in both a Node.js (JavaScript) and a TypeScript environment.

Node.js Example

To run the Node.js example:

cd examples/nodejs-example
npm install
npm start

This will execute a simple test file that uses the SDK.

TypeScript Example

To run the TypeScript example:

cd examples/typescript-example
npm install
npm start

This will compile and run a simple test file that uses the SDK.

Authentication

To use the SDK, you need an API access token from your respond.io workspace:

1. Navigate to Settings > Integrations > Developer API
2. Click Add Access Token to generate a new token
3. Copy the token and use it to initialize the SDK

const client = new RespondIO({
  apiToken: 'your-api-token-here',
  baseUrl: 'https://api.respond.io/v2', // Optional, defaults to this value
  maxRetries: 3, // Optional, defaults to 3
  timeout: 30000, // Optional, defaults to 30000ms
});

API Reference

Contacts

The Contact API allows you to manage contacts in your workspace.

Get a Contact

const contact = await client.contacts.get('id:123');
// or
const contact = await client.contacts.get('email:[email protected]');
// or
const contact = await client.contacts.get('phone:+1234567890');

Create a Contact

await client.contacts.create('email:[email protected]', {
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1234567890',
  language: 'en',
  countryCode: 'US',
  custom_fields: [
    { name: 'Company', value: 'Acme Inc' },
    { name: 'Role', value: 'Developer' },
  ],
});

Update a Contact

await client.contacts.update('id:123', {
  firstName: 'Jane',
  custom_fields: [
    { name: 'Role', value: 'Senior Developer' },
  ],
});

List Contacts

// List all contacts
const result = await client.contacts.list({
  search: '',
  timezone: 'America/New_York',
  filter: { $and: [] },
});

// List with filters
const result = await client.contacts.list({
  search: '',
  timezone: 'UTC',
  filter: {
    $and: [
      {
        category: 'contactField',
        field: 'assigneeUserId',
        operator: 'isEqualTo',
        value: '123',
      },
    ],
  },
}, {
  limit: 50,
  cursorId: 0,
});

Manage Tags

// Add tags
await client.contacts.addTags('id:123', ['vip', 'premium-customer']);

// Remove tags
await client.contacts.deleteTags('id:123', ['old-tag']);

Messaging

The Messaging API allows you to send and retrieve messages.

Send Messages

// Text message
await client.messaging.send('id:123', {
  message: {
    type: 'text',
    text: 'Hello! How can we help you today?',
  },
});

// Message with dynamic variables
await client.messaging.send('id:123', {
  message: {
    type: 'text',
    text: 'Hello {{$contact.name}}, your order #{{$contact.orderId}} is ready!',
  },
});

// Attachment
await client.messaging.send('id:123', {
  message: {
    type: 'attachment',
    attachment: {
      type: 'image',
      url: 'https://example.com/image.jpg',
    },
  },
});

// WhatsApp Template
await client.messaging.send('id:123', {
  channelId: 12345,
  message: {
    type: 'whatsapp_template',
    template: {
      name: 'order_confirmation',
      languageCode: 'en',
      components: [
        {
          type: 'body',
          text: 'Hello {{1}}, your order #{{2}} has been confirmed!',
          parameters: [
            { type: 'text', text: 'John' },
            { type: 'text', text: '12345' },
          ],
        },
      ],
    },
  },
});

Get a Message

const message = await client.messaging.get('id:123', 987654);
console.log(message.status); // Message delivery status

Comments

The Comment API allows you to add internal comments to contacts.

Create a Comment

await client.comments.create('id:123', {
  text: 'Customer requested a callback tomorrow at 2 PM',
});

// Mention users in comments
await client.comments.create('id:123', {
  text: 'Please follow up with this contact {{@user.456}}',
});

Conversations

The Conversation API allows you to manage conversation status and assignments.

Assign/Unassign Conversations

// Assign to user by ID
await client.conversations.assign('id:123', {
  assignee: 456,
});

// Assign to user by email
await client.conversations.assign('id:123', {
  assignee: '[email protected]',
});

// Unassign conversation
await client.conversations.assign('id:123', {
  assignee: null,
});

Open/Close Conversations

// Open conversation
await client.conversations.updateStatus('id:123', {
  status: 'open',
});

// Close conversation with notes
await client.conversations.updateStatus('id:123', {
  status: 'close',
  category: 'Resolved',
  summary: 'Issue was resolved by providing documentation',
});

Space (Workspace)

The Space API provides workspace-level operations.

List Users

const users = await client.space.listUsers({ limit: 50 });
for (const user of users.items) {
  console.log(user.firstName, user.email, user.role);
}

Create Custom Field

// Text field
await client.space.createCustomField({
  name: 'Customer ID',
  slug: 'customer_id',
  description: 'Unique customer identifier',
  dataType: 'text',
});

// List field with allowed values
await client.space.createCustomField({
  name: 'Priority',
  dataType: 'list',
  allowedValues: ['Low', 'Medium', 'High', 'Critical'],
});

List Channels

const channels = await client.space.listChannels();
for (const channel of channels.items) {
  console.log(channel.name, channel.source);
}

Manage Tags

// Create tag
await client.space.createTag({
  name: 'VIP Customer',
  description: 'High-value customers',
  colorCode: '#FF5733',
  emoji: '⭐',
});

// Update tag
await client.space.updateTag({
  currentName: 'VIP Customer',
  name: 'Premium Customer',
  colorCode: '#FFD700',
});

// Delete tag
await client.space.deleteTag({ name: 'Old Tag' });

Error Handling

The SDK provides detailed error information through the RespondIOError class:

import { RespondIOError } from '@respond-io/typescript-sdk';

try {
  await client.contacts.get('id:999999');
} catch (error) {
  if (error instanceof RespondIOError) {
    console.error('Status:', error.statusCode);
    console.error('Code:', error.code);
    console.error('Message:', error.message);
    
    // Check error type
    if (error.isRateLimitError()) {
      console.error('Rate limit reached!');
      console.error('Retry after:', error.rateLimitInfo?.retryAfter, 'seconds');
    } else if (error.isNotFoundError()) {
      console.error('Resource not found');
    } else if (error.isAuthError()) {
      console.error('Authentication failed');
    } else if (error.isValidationError()) {
      console.error('Invalid request parameters');
    } else if (error.isServerError()) {
      console.error('Server error occurred');
    }
  }
}

TypeScript Support

The SDK is written in TypeScript and provides complete type definitions:

import type {
  Contact,
  Message,
  WhatsAppTemplateMessage,
  CustomField,
  SpaceUser,
} from '@respond-io/typescript-sdk';

// All API responses and requests are fully typed
const contact: Contact = await client.contacts.get('id:123');

// Type-safe message construction
const message: WhatsAppTemplateMessage = {
  type: 'whatsapp_template',
  template: {
    name: 'welcome_message',
    languageCode: 'en',
    components: [
      {
        type: 'body',
        text: 'Welcome {{1}}!',
        parameters: [{ type: 'text', text: 'John' }],
      },
    ],
  },
};

Testing

The SDK includes comprehensive unit tests with 80%+ coverage:

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run tests in CI mode
npm run test:ci

Test Structure

tests/
├── setup.ts                    # Test configuration
├── client.test.ts             # HTTP client tests
├── errors.test.ts             # Error class tests
├── clients/
│   ├── contact.test.ts        # Contact client tests
│   ├── messaging.test.ts      # Messaging client tests
│   ├── comment-conversation-space.test.ts
└── integration/
    └── sdk.test.ts            # Integration tests

Project Structure

respondio-sdk/
├── src/
│   ├── index.ts              # Main export
│   ├── client.ts             # HTTP client
│   ├── types/
│   │   ├── index.ts         # Type exports
│   │   ├── common.ts        # Common types
│   │   ├── contact.ts       # Contact types
│   │   ├── message.ts       # Message types
│   │   ├── space.ts         # Space types
│   │   ├── conversation.ts  # Conversation types
│   │   └── comment.ts       # Comment types
│   ├── clients/
│   │   ├── index.ts         # Client exports
│   │   ├── contact.ts       # Contact client
│   │   ├── messaging.ts     # Messaging client
│   │   ├── comment.ts       # Comment client
│   │   ├── conversation.ts  # Conversation client
│   │   └── space.ts         # Space client
│   └── errors/
│       └── index.ts         # Error classes
├── tests/                    # Test files
├── examples/                 # Usage examples
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format
npm run format:check

# Type check
npm run typecheck

# Run all validations
npm run validate

Requirements

• Node.js 14+
• TypeScript 5.0+ (for TypeScript projects)
• Valid respond.io API access token

Support

• Documentation: https://developers.respond.io
• Help Center: https://respond.io/help
• Contact Support: https://respond.io/contact

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Made with ❤️ by the respond.io community