Signal SDK - TypeScript SDK for Signal Messenger

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

1npm 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:

1# View all available commands
2npx signal-sdk --help
3
4# Link a new device to your Signal account
5npx signal-sdk connect
6
7# Link with a custom device name
8npx signal-sdk connect "My Custom Device Name"

Device Linking

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

1# Using npx (recommended)
2npx signal-sdk connect
3
4# Or with a custom device name
5npx signal-sdk connect "My Bot Device"
6
7# Get help for the CLI
8npx 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

1const { SignalCli } = require("signal-sdk");
2
3// Initialize SignalCli with phone number
4const signal = new SignalCli("+1234567890");
5
6// Connect to signal-cli daemon
7await signal.connect();
8
9// Send a message
10await signal.sendMessage("+0987654321", "Hello from Signal CLI SDK!");
11
12// Listen for incoming messages
13signal.on("message", (message) => {
14  console.log("Received message:", message.envelope.dataMessage.message);
15});
16
17// Graceful shutdown
18await signal.gracefulShutdown();

Create a Bot

1const { SignalBot } = require("signal-sdk");
2
3// Initialize bot with configuration
4const bot = new SignalBot({
5  phoneNumber: "+1234567890",
6  admins: ["+0987654321"],
7  group: {
8    name: "My Bot Group",
9    description: "A group managed by my bot",
10    createIfNotExists: true,
11  },
12});
13
14// Add custom commands
15bot.addCommand({
16  name: "hello",
17  description: "Greet the user",
18  handler: async (message, args) => {
19    const name = args.join(" ") || "friend";
20    return `Hello ${name}! How can I help you today?`;
21  },
22});
23
24// Handle events
25bot.on("ready", () => {
26  console.log("Bot is ready and listening for messages!");
27});
28
29bot.on("message", (message) => {
30  console.log(`Received: ${message.text} from ${message.sender}`);
31});
32
33// Start the bot
34await 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

1const { SignalCli } = require("signal-sdk");
2const signal = new SignalCli("+1234567890");
3
4await signal.connect();
5await signal.sendMessage("+0987654321", "Hello World!");
6await signal.gracefulShutdown();

Send Files

1// Send file with message
2await signal.sendMessage("+0987654321", "Here's the document:", {
3  attachments: ["./path/to/document.pdf"],
4});
5
6// Send multiple files
7await signal.sendMessage("+0987654321", "Photos from today:", {
8  attachments: ["./photo1.jpg", "./photo2.jpg"],
9});

Group Management

1// Create a new group
2const group = await signal.createGroup("My Group", [
3  "+0987654321",
4  "+1122334455",
5]);
6console.log("Group ID:", group.groupId);
7
8// Send message to group
9await signal.sendMessage(group.groupId, "Welcome to the group!");
10
11// Update group info
12await signal.updateGroup(group.groupId, {
13  title: "Updated Group Name",
14  description: "This is our group chat",
15});

Bot with Custom Commands

1const { SignalBot } = require("signal-sdk");
2
3const bot = new SignalBot({
4  phoneNumber: "+1234567890",
5  admins: ["+0987654321"],
6});
7
8// Add weather command
9bot.addCommand({
10  name: "weather",
11  description: "Get weather information",
12  handler: async (message, args) => {
13    const city = args.join(" ") || "New York";
14    // Integrate with weather API
15    return `Weather in ${city}: 22°C, sunny`;
16  },
17});
18
19// Add custom event handler
20bot.on("groupMemberJoined", async (event) => {
21  await bot.sendMessage(event.groupId, `Welcome ${event.member.name}!`);
22});
23
24await bot.start();

Testing

1# Run all tests
2npm test
3
4# Run specific test suite
5npm test -- --testNamePattern="SignalCli"
6
7# Run with coverage
8npm run test:coverage

Development

1# Clone the repository
2git clone https://github.com/your-username/signal-cli-sdk.git
3cd signal-cli-sdk
4
5# Install dependencies
6npm install
7
8# Build the project
9npm run build
10
11# Run examples
12npm run build && node examples/sdk/01-basic-usage.js
13
14# Run tests
15npm test

Configuration

Environment Variables

Create a .env file in your project root:

1SIGNAL_PHONE_NUMBER="+1234567890"
2SIGNAL_ADMIN_NUMBER="+0987654321"
3SIGNAL_RECIPIENT_NUMBER="+1122334455"
4SIGNAL_GROUP_NAME="My Bot Group"

SignalCli Configuration

1const { SignalCli } = require("signal-sdk");
2
3// Basic configuration
4const signal = new SignalCli(configPath, phoneNumber);
5// configPath: Path to signal-cli config directory (optional)
6// phoneNumber: Your registered Signal phone number (required)
7
8// Example with custom config path
9const signal = new SignalCli("/custom/signal-cli/config", "+1234567890");

SignalBot Configuration

1const { SignalBot } = require("signal-sdk");
2
3const bot = new SignalBot({
4  phoneNumber: "+1234567890", // Required: Your Signal phone number
5  admins: ["+0987654321"], // Required: Admin phone numbers
6  group: {
7    name: "My Bot Group", // Group name
8    description: "Managed by my bot", // Group description
9    createIfNotExists: true, // Create group if it doesn't exist
10    avatar: "./group-avatar.jpg", // Group avatar image
11  },
12  settings: {
13    commandPrefix: "/", // Command prefix (default: "/")
14    logMessages: true, // Log incoming messages (default: false)
15    welcomeNewMembers: true, // Welcome message for new members
16    cooldownSeconds: 2, // Command cooldown in seconds
17  },
18});

Troubleshooting

Common Issues

1. signal-cli not found

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

2. Java not installed

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

3. Phone number not registered

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

4. Connection timeout

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

5. Permission denied on config directory

   1# Fix permissions on signal-cli config directory
   2chmod -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.17 - 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