Signal SDK - TypeScript SDK for Signal Messenger

A comprehensive TypeScript SDK for interacting with signal-cli
providing JSON-RPC communication and a powerful bot framework.

Features

Core Capabilities

• JSON-RPC Communication - Direct communication with signal-cli daemon via JSON-RPC
• TypeScript Support - Complete type definitions with full IntelliSense support
• Message Management - Send, receive, and manage Signal messages
• Real-time Events - Listen to incoming messages and notifications
• Production Ready - Robust error handling and connection management

SignalBot Framework

• Simple Bot Creation - Create powerful bots with minimal setup
• Command System - Built-in command parsing and routing
• Event Handling - React to messages, group events, and user actions
• Admin Controls - Role-based permissions and access control
• Group Management - Automated group creation and member management
• Extensible - Plugin-style architecture for custom functionality

Advanced Features

• File Attachments - Send and receive files, images, and media
• Group Operations - Create, manage, and configure groups
• Contact Management - Add, update, remove, and manage contacts
• Message Reactions - React to messages with emoji reactions
• Typing Indicators - Send and receive typing notifications
• Read Receipts - Track message delivery and read status
• Profile Management - Update profile information and avatars
• Payment Notifications - Send payment receipts and notifications
• Custom Sticker Packs - Upload and manage custom sticker packs
• User Status Checking - Verify Signal registration status
• Rate Limit Recovery - Handle and recover from rate limiting
• Phone Number Changes - Change registered phone numbers
• Progress Tracking - Monitor upload progress for large files

Quick Start

Installation

npm install signal-sdk

Prerequisites

1. Node.js (version 16 or later)
2. Java Runtime Environment (required by signal-cli)

Note: signal-cli binaries are included with the SDK - no separate installation required.

Detailed installation guide

CLI Commands

The SDK includes a command-line interface for common operations:

# View all available commands
npx signal-sdk --help

# Link a new device to your Signal account
npx signal-sdk connect

# Link with a custom device name
npx signal-sdk connect "My Custom Device Name"

Device Linking

Before using the SDK, you need to link a device to your Signal account:

# Using npx (recommended)
npx signal-sdk connect

# Or with a custom device name
npx signal-sdk connect "My Bot Device"

# Get help for the CLI
npx signal-sdk --help

This command will:

1. Generate a QR code in your terminal
2. Display instructions for scanning with your Signal app
3. Complete the device linking process

Note: You only need to do this once per device. After linking, your device will be permanently connected to your Signal account.

Basic Usage

const { SignalCli } = require("signal-sdk");

// Initialize SignalCli with phone number
const signal = new SignalCli("+1234567890");

// Connect to signal-cli daemon
await signal.connect();

// Send a message
await signal.sendMessage("+0987654321", "Hello from Signal CLI SDK!");

// Listen for incoming messages
signal.on("message", (message) => {
  console.log("Received message:", message.envelope.dataMessage.message);
});

// Graceful shutdown
await signal.gracefulShutdown();

Create a Bot

const { SignalBot } = require("signal-sdk");

// Initialize bot with configuration
const bot = new SignalBot({
  phoneNumber: "+1234567890",
  admins: ["+0987654321"],
  group: {
    name: "My Bot Group",
    description: "A group managed by my bot",
    createIfNotExists: true,
  },
});

// Add custom commands
bot.addCommand({
  name: "hello",
  description: "Greet the user",
  handler: async (message, args) => {
    const name = args.join(" ") || "friend";
    return `Hello ${name}! How can I help you today?`;
  },
});

// Handle events
bot.on("ready", () => {
  console.log("Bot is ready and listening for messages!");
});

bot.on("message", (message) => {
  console.log(`Received: ${message.text} from ${message.sender}`);
});

// Start the bot
await bot.start();

Your bot will automatically:

• Handle command parsing (default prefix: /)
• Provide built-in commands (/help, /ping)
• Manage group creation and membership
• Enforce admin permissions
• Handle errors gracefully

Documentation

Getting Started

• Installation & Setup
• Getting Started Guide
• Device Linking

API Reference

• SignalCli Class
• SignalBot Class
• TypeScript Interfaces

Examples

• Device Linking - Link your device to Signal
• Basic SDK Usage - Simple message sending
• Quick Start - Complete getting started example
• Group Management - Create and manage groups
• Contact Management - Handle contacts
• File Handling - Send and receive files
• Minimal Bot - Simple bot implementation
• Advanced Bot - Full-featured bot example

Advanced Topics

• Advanced Features
• SignalBot Framework
• Feature Coverage Analysis
• Implementation Plan
• FAQ
• Troubleshooting

Common Use Cases

Send Messages

const { SignalCli } = require("signal-sdk");
const signal = new SignalCli("+1234567890");

await signal.connect();
await signal.sendMessage("+0987654321", "Hello World!");
await signal.gracefulShutdown();

Send Files

// Send file with message
await signal.sendMessage("+0987654321", "Here's the document:", {
  attachments: ["./path/to/document.pdf"],
});

// Send multiple files
await signal.sendMessage("+0987654321", "Photos from today:", {
  attachments: ["./photo1.jpg", "./photo2.jpg"],
});

Group Management

// Create a new group
const group = await signal.createGroup("My Group", [
  "+0987654321",
  "+1122334455",
]);
console.log("Group ID:", group.groupId);

// Send message to group
await signal.sendMessage(group.groupId, "Welcome to the group!");

// Update group info
await signal.updateGroup(group.groupId, {
  title: "Updated Group Name",
  description: "This is our group chat",
});

Bot with Custom Commands

const { SignalBot } = require("signal-sdk");

const bot = new SignalBot({
  phoneNumber: "+1234567890",
  admins: ["+0987654321"],
});

// Add weather command
bot.addCommand({
  name: "weather",
  description: "Get weather information",
  handler: async (message, args) => {
    const city = args.join(" ") || "New York";
    // Integrate with weather API
    return `Weather in ${city}: 22°C, sunny`;
  },
});

// Add custom event handler
bot.on("groupMemberJoined", async (event) => {
  await bot.sendMessage(event.groupId, `Welcome ${event.member.name}!`);
});

await bot.start();

Testing

# Run all tests
npm test

# Run specific test suite
npm test -- --testNamePattern="SignalCli"

# Run with coverage
npm run test:coverage

Development

# Clone the repository
git clone https://github.com/your-username/signal-cli-sdk.git
cd signal-cli-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run examples
npm run build && node examples/sdk/01-basic-usage.js

# Run tests
npm test

Configuration

Environment Variables

Create a .env file in your project root:

SIGNAL_PHONE_NUMBER="+1234567890"
SIGNAL_ADMIN_NUMBER="+0987654321"
SIGNAL_RECIPIENT_NUMBER="+1122334455"
SIGNAL_GROUP_NAME="My Bot Group"

SignalCli Configuration

const { SignalCli } = require("signal-sdk");

// Basic configuration
const signal = new SignalCli(configPath, phoneNumber);
// configPath: Path to signal-cli config directory (optional)
// phoneNumber: Your registered Signal phone number (required)

// Example with custom config path
const signal = new SignalCli("/custom/signal-cli/config", "+1234567890");

SignalBot Configuration

const { SignalBot } = require("signal-sdk");

const bot = new SignalBot({
  phoneNumber: "+1234567890", // Required: Your Signal phone number
  admins: ["+0987654321"], // Required: Admin phone numbers
  group: {
    name: "My Bot Group", // Group name
    description: "Managed by my bot", // Group description
    createIfNotExists: true, // Create group if it doesn't exist
    avatar: "./group-avatar.jpg", // Group avatar image
  },
  settings: {
    commandPrefix: "/", // Command prefix (default: "/")
    logMessages: true, // Log incoming messages (default: false)
    welcomeNewMembers: true, // Welcome message for new members
    cooldownSeconds: 2, // Command cooldown in seconds
  },
});

Troubleshooting

Common Issues

1. signal-cli not found

   # Make sure signal-cli is installed and in your PATH
   # Download from: https://github.com/AsamK/signal-cli/releases
   signal-cli --version

2. Java not installed

   # Install Java (required by signal-cli)
   # Ubuntu/Debian
   sudo apt update && sudo apt install default-jre
   
   # macOS with Homebrew
   brew install openjdk
   
   # Windows: Download from Oracle or use package manager

3. Phone number not registered

   # Register your phone number with Signal first
   signal-cli -a +1234567890 register
   signal-cli -a +1234567890 verify CODE_FROM_SMS

4. Connection timeout

   # Test signal-cli directly
   signal-cli -a +1234567890 send +0987654321 "Test message"

5. Permission denied on config directory

   # Fix permissions on signal-cli config directory
   chmod -R 755 ~/.local/share/signal-cli/

Complete troubleshooting guide

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• signal-cli - The underlying Signal CLI client
• Signal Protocol - The Signal messaging protocol
• The Signal community for their excellent work

Support

• Documentation: docs/
• Examples: examples/
• Issues: Report bugs and request features
• Contributing: See CONTRIBUTING.md

---

Built with TypeScript for the Signal community

---

API Methods

Compatible with signal-cli v0.13.18 - 100% Feature Coverage

Category	Method	Description	Status
Messaging	send	Send text messages and attachments	✅
	sendReaction	React to messages with emoji	✅
	sendTyping	Send typing indicators	✅
	sendReceipt	Send read receipts	✅
	sendPaymentNotification	Send payment notifications	✅
Groups	createGroup	Create new groups	✅
	updateGroup	Update group settings	✅
	listGroups	List all groups	✅
	quitGroup	Leave a group	✅
Contacts	listContacts	List all contacts	✅
	updateContact	Update contact information	✅
	removeContact	Remove contacts with options	✅
	block / unblock	Block/unblock contacts	✅
	getUserStatus	Check registration status	✅
Stickers	listStickerPacks	List sticker packs	✅
	addStickerPack	Install sticker packs	✅
	uploadStickerPack	Upload custom sticker packs	✅
Advanced	submitRateLimitChallenge	Handle rate limiting	✅
	startChangeNumber	Start phone number change	✅
	finishChangeNumber	Complete phone number change	✅
	sendMessageWithProgress	Enhanced messaging with progress	✅

Complete API documentation

---

Support the Project

If you find signal sdk useful, consider supporting its development:

Your support helps maintain and improve signal-sdk

---

Made with ❤️ for the Signal community