Welcome to the complete documentation for the Signal SDK - a comprehensive TypeScript SDK for Signal CLI with native JSON-RPC support.
- Installation & Setup - Install the SDK and dependencies
- Device Linking - Required first step - Link your device with QR code
- Getting Started - Your first Signal app in minutes
- Complete API Reference - Full SignalCli and SignalBot API documentation
- Examples Guide - Walkthrough of all examples with explanations
- SignalBot Framework - Build powerful bots with minimal code
- Advanced Features - Polls, attachments, account management
- Robust Infrastructure - Error handling, retry, rate limiting, logging
- Maintenance Guide - Architecture, test strategy, and safe change workflow
- Troubleshooting - Common issues and solutions
- FAQ - Frequently asked questions
- Test organization - Focused test commands and naming rules
- Maintenance Guide - Architecture, coverage and safe change workflow
This documentation covers everything you need to know about the Signal SDK:
Start here if you're new to the Signal SDK:
- Installation - Get the SDK installed and ready
- Device Linking - Connect your Signal account (mandatory)
- Getting Started - Send your first message
- Examples Guide - Learn from practical examples
Dive deeper into the SDK capabilities:
- API Reference - Complete method documentation
- SignalBot Framework - Build interactive bots
- Advanced Features - Polls, attachments, account management
- Robust Infrastructure - Enterprise-grade reliability
The current release is aligned with signal-cli v0.14.10. Run npm test for the current test-suite result rather than relying on a documentation snapshot.
- Text styling - Bold, italic, strikethrough, monospace, spoiler
- Mentions - @tag users in messages
- Quotes - Reply to specific messages with context
- Edit messages - Correct previously sent messages
- Link previews - Rich URL previews
- Story replies - Respond to stories
- Advanced receive() - Timeout, maxMessages, ignoreAttachments, ignoreStories, sendReadReceipts
- Safety numbers - Get and verify safety numbers
- Identity verification - Verify contact identities
- Untrusted identities - List identities that need verification
- Set username - Create Signal username for privacy
- Username links - Share username without phone number
- Delete username - Remove username anytime
- MultiAccountManager - Manage multiple Signal accounts simultaneously
- Event routing - Automatic event forwarding per account
- Account isolation - Independent connections and operations
- Contact profiles - Parse givenName, familyName, mobileCoinAddress
- Group details - Parse pendingMembers, bannedMembers, inviteLink
- Helper methods - getContactsWithProfiles(), getGroupsWithDetails()
- Group invite links - Generate and manage invite links
- Banned members - Set and manage banned members list
- Reset links - Invalidate and regenerate invite links
- Unix socket - Connect via Unix socket
- TCP - Connect to remote daemon via TCP
- HTTP - REST API connection mode
- JSON-RPC STDIO - Default high-performance mode
- Poll support - Create, vote, and terminate polls in conversations
- Attachment management - Retrieve attachments, avatars, stickers by ID
- Account management - Update profile, settings, and account details
- Contact export - Send and backup contact lists
- Enhanced group info - Detailed group information with permissions
- Retry mechanism - Exponential backoff for transient failures
- Rate limiting - Client-side rate limiting to prevent API throttling
- Input validation - Comprehensive validation for all operations
- Structured logging - Professional logging system with levels
- Configuration - Centralized configuration management
When things don't work as expected:
- Troubleshooting Guide - Common issues and fixes
- FAQ - Quick answers to common questions
Never used the Signal SDK? Follow this path:
1. Install SDK → 2. Link Device → 3. Send Message → 4. Build Bot
↓ ↓ ↓ ↓
[Installation] → [Device Linking] → [Getting Started] → [Examples]
# 1. Install
npm install signal-sdk
# 2. Link device (mandatory first step)
npx signal-sdk connect
# 3. Set your phone number
echo 'SIGNAL_PHONE_NUMBER="+33111111111"' > .env
# 4. Send your first message
node examples/sdk/01-basic-usage.jsThe Signal SDK provides two main classes:
const { SignalCli } = require('signal-sdk');
const signal = new SignalCli('+33111111111');
await signal.connect();
await signal.sendMessage('+33000000000', 'Hello from Signal SDK!');
await signal.gracefulShutdown();const { SignalBot } = require('signal-sdk');
const bot = new SignalBot({
phoneNumber: '+33111111111',
admins: ['+33000000000'],
group: {
name: 'My Bot Group',
createIfNotExists: true,
},
});
bot.addCommand({
name: 'hello',
handler: () => 'Hello World!',
});
await bot.start();The documentation is organized into the following sections:
-
docs/: Contains all documentation files.installation.md: Step-by-step installation guide.device-linking.md: QR code linking process.getting-started.md: Quick start and basic usage.api-reference.md: Complete API for all classes and methods.examples-guide.md: Detailed walkthrough of all examples.signalbot-framework.md: In-depth guide to the bot framework.advanced-features.md: Advanced topics and techniques.troubleshooting.md: Solutions to common problems.faq.md: Frequently asked questions.README.md: This file, the main entry point.
-
src/tests/: Deterministic unit, transport, compatibility and regression tests. -
examples/: Contains ready-to-run examples.sdk/: Core SDK examples.bot/: SignalBot framework examples.
| Feature | SignalCli | SignalBot | Description |
|---|---|---|---|
| JSON-RPC | Yes | Yes | Native, high-performance communication |
| Device Linking | Yes | Yes | QR code device linking |
| Messaging | Yes | Yes | Send/receive messages, reactions, typing |
| Advanced Messaging | Yes | Yes | Text styling, mentions, quotes, edits |
| Identity Security | Yes | Yes | Safety numbers, verification |
| Username Management | Yes | Yes | Set/delete username, links |
| Multi-Account | Yes | No | Manage multiple accounts simultaneously |
| Enhanced Parsing | Yes | Yes | Detailed profiles & groups |
| Group Management | Yes | Yes | Create, update, manage groups |
| Advanced Groups | Yes | Yes | Invite links, banned members |
| Contact Management | Yes | Yes | List, update, block/unblock contacts |
| File Attachments | Yes | Yes | Send files, images, and other media |
| Polls | Yes | Yes | Create, vote, terminate polls |
| Daemon Modes | Yes | Yes | Unix socket, TCP, HTTP |
| Command System | No | Yes | Built-in command handling with prefixes |
| Admin Permissions | No | Yes | Role-based access control |
| Auto Group Creation | No | Yes | Automatically create and configure a bot group |
| Anti-Spam | No | Yes | Rate limiting and spam protection |
We welcome contributions to the documentation!
- Fork the repository.
- Make your changes in the
docs/directory. - Follow the existing style and formatting.
- Submit a pull request.
Your contributions help make the Signal SDK better for everyone.
Happy coding!