# SipBot
[](https://crates.io/crates/sipbot)
[](https://docs.rs/sipbot)
A flexible, high-performance SIP bot implementation in Rust, designed for testing and simulating SIP call flows. It uses [rsipstack](https://github.com/restsend/rsipstack) for signaling and supports customizable call handling stages including ringing, answering, media playback, echo, and automatic hangup.
The media transport uses [rustrtc](https://github.com/restsend/rustrtc).
## Features
- **Multi-Account Support**: Configure multiple SIP accounts in a single instance.
- **Flexible Call Flow Stages**:
- **Ringing (Stage 1)**: Send `180 Ringing` or `183 Session Progress` with custom ringback tone (WAV).
- **Answer (Stage 2)**: Auto-answer calls with `200 OK`.
- **Media Handling**:
- **Play**: Play a specified `.wav` file.
- **Echo**: Echo received RTP packets back to the sender (Latency testing).
- **Local**: Use local audio device for playback and capture (Mic/Speaker).
- **Hangup (Stage 3)**: Automatically hang up after a configurable duration or reject calls with specific SIP codes.
- **Outbound Calls**: Ability to initiate calls to a target URI.
- **Call Recording**: (Experimental) Record call audio to WAV files. (Requires configuration)
- **Registration**: Supports SIP registration with authentication (WIP).
## Quick start
Install the `sipbot` from `crates.io`.
```bash
cargo install sipbot
```
### CLI Usage
You can also run `sipbot` with CLI arguments for quick testing.
#### Global Options
- `-C, --conf <FILE>`: Path to the configuration file.
- `-E, --external <IP>`: External IP address for SDP (NAT traversal).
#### Initiate a Call
```bash
cargo run -- call -t sip:user@domain --caller sip:me@mydomain --play audio.wav --hangup 10 --total 10 --concurrent 2
```
- `-t, --target <TARGET>`: Target URI (e.g., sip:user@domain).
- `-c, --caller <URI>`: Caller (username or full URI).
- `--auth-user <USER>`: Auth username (optional).
- `--password <PASS>`: Auth password.
- `--hangup <SECONDS>`: Hangup after seconds.
- `--play <FILE>`: Play file (wav).
- `--local`: Use local audio device for playback and capture.
- `--record <FILE>`: Record to file (wav). If multiple calls are made, the filename will be suffixed with the call index (e.g., `record_1.wav`).
- `--srtp`: Enable SRTP/SDES.
- `--total <COUNT>`: Total number of calls to make (default: 1).
- `--concurrent <COUNT>`: Max concurrent calls (default: 1).
#### Wait for Calls
```bash
cargo run -- wait --addr 0.0.0.0:5060 --username sipbot --answer welcome.wav
```
- `-a, --addr <ADDR>`: Bind address (e.g., 0.0.0.0:5060).
- `-u, --username <USER>`: Username (e.g., sipbot).
- `-d, --domain <DOMAIN>`: Domain (e.g., 127.0.0.1).
- `--ringback <FILE>`: Ringback file (wav).
- `--ring-duration <SECONDS>`: Ring duration in seconds.
- `--answer <FILE>`: Answer and play file (wav).
- `--echo`: Answer and echo.
- `--local`: Answer and use local audio device.
- `--hangup <SECONDS>`: Hangup after seconds.
- `--reject <CODE>`: Reject with code (e.g. 486, 603).
- `--reject-prob <PROB>`: Randomly reject call with probability 1-99% (default code 480).
- `--srtp`: Enable SRTP/SDES.
> **Note**: By default, `wait` mode does not record calls. To enable recording, you must use a configuration file and specify the `recorders` directory.
#### Other Commands
- `options`: Send OPTIONS request.
- `info`: Send INFO request.
## Typical Usage Examples
### 1. Echo Test (Latency & Connectivity)
Answer incoming calls and echo the audio back to the caller. This is perfect for testing network latency and packet loss.
```bash
sipbot wait --username echo-bot --echo
```
### 2. Intercom Mode (Local Audio)
Use your computer's microphone and speakers to talk to a SIP caller.
```bash
sipbot wait --username intercom --local
```
### 3. Automated Announcement
Answer calls, play a welcome message, and hang up after 10 seconds.
```bash
sipbot wait --username announcer --answer welcome.wav --hangup 10
```
### 4. Load Testing (Outbound)
Make 100 calls to a target, with 5 calls running concurrently, playing an audio file for 30 seconds each.
```bash
sipbot call -t sip:100@192.168.1.10 --play music.wav --total 100 --concurrent 5 --hangup 30
```
### 5. High-Quality Audio (G.722)
SipBot supports G.722 (16kHz) for high-definition audio. It automatically negotiates the best codec.
```bash
# Make a call using G.722 if supported by the remote end
sipbot call -t sip:hd-user@domain --play high_res.wav
```
### 6. Call Recording
Record all incoming calls to a specific directory. (Requires `recorders` path in `config.toml`)
```bash
# In config.toml:
# recorders = "./wavs"
sipbot wait --username recorder-bot
```
## Configuration
Create a `config.toml` file in the root directory. The configuration allows you to define the behavior for each account.
### Example `config.toml`
```toml
# Global settings
addr = "0.0.0.0:5060" # Local bind address
external_ip = "1.2.3.4" # External IP for SDP (NAT traversal)
recorders = "/tmp/recorders" # Directory for recordings (Required for recording)
[[accounts]]
username = "1001"
domain = "sip.example.com"
password = "secretpassword"
register = true # Enable registration
reject_prob = 20 # Randomly reject 20% of calls with 480
# --- Call Handling Flow ---
# Stage 1: Ringing
# Wait for 5 seconds before answering.
# If 'ringback' is provided, sends 183 Session Progress and plays the file.
# If 'ringback' is omitted, sends 180 Ringing.
[accounts.ring]
duration_secs = 5
# ringback = "sounds/ringback.wav"
# Stage 2: Answer
# Answer the call (200 OK) and perform an action.
[accounts.answer]
action = "play" # Options: "play", "echo", "local"
wav_file = "sounds/welcome.wav" # Required if action is "play"
# [accounts.answer]
# action = "echo" # Alternative: Echo test
# [accounts.answer]
# action = "local" # Alternative: Use local audio device (Mic/Speaker)
# Stage 3: Hangup
# Automatically hang up after the media finishes or a timeout.
[accounts.hangup]
code = 200 # SIP code (not fully used for BYE yet, mainly for rejection)
after_secs = 10 # Send BYE after 10 seconds
```
### Configuration Reference
- **`addr`**: (Optional) The local IP and port to bind to. Defaults to `0.0.0.0:35060`.
- **`external_ip`**: (Optional) The external IP address to use in SDP offers/answers (useful for NAT).
- **`recorders`**: (Optional) Path to save call recordings.
- **`accounts`**: List of account configurations.
- `username`: SIP username.
- `domain`: SIP domain/registrar.
- `password`: SIP password.
- `register`: (Bool) Whether to register with the domain.
- `reject_prob`: (Optional) Probability (1-99) to randomly reject incoming calls with 480.
- `target`: (Optional) URI to call on startup (for outbound bot).
- **`early_media`**: Configuration for the early media phase (183).
- `wav_file`: (Optional) Path to WAV file.
- `local`: (Optional) `true` to use local audio device for capture and playback.
- **`ring`**: Configuration for the ringing phase.
- `duration_secs`: How long to stay in ringing state.
- `ringback`: (Optional) Path to WAV file for early media (183).
- `local`: (Optional) `true` to use local audio device for capture and playback.
- **`answer`**: Configuration for the answered phase.
- `action`: `play`, `echo` or `local`.
- `wav_file`: Path to WAV file (if action is `play`).
- **`hangup`**: Configuration for ending the call.
- `code`: SIP status code (used for rejection if no answer config exists).
- `after_secs`: (Optional) Time in seconds to wait before sending BYE.
## Benchmarking and Testing
`SipBot` is designed to facilitate SIP performance testing and benchmarking by simulating multiple callers and callees with customizable behaviors.
### Example Scenario
To run a benchmark, you typically need two instances of `SipBot`: one for caller and another for callee. they will register on sip server with alice and bob respectively.
#### Callee Configuration (`callee.toml`)
This bot listens for incoming calls, rings for a few seconds, and randomly rejects 50% of the calls to test error handling.
```toml
# Local bind address for the callee
addr = "0.0.0.0:3333"
[[accounts]]
register = true
proxy = "127.0.0.1:15060" # sip server address
username = "alice"
domain = "127.0.0.1"
password = "123456"
reject_prob = 20 # 20% probability to reject incoming calls
[accounts.hangup]
code = 486 # reject with code 486
[accounts.ring]
duration_secs = 3 # Wait for 3 seconds in ringing state before answering
```
#### Caller Configuration (`caller.toml`)
This bot initiates calls to a target, with a 30% chance of canceling the call before it is answered.
```toml
# Local bind address for the caller
addr = "0.0.0.0:4444"
[[accounts]]
register = true
proxy = "127.0.0.1:15060"
username = "bob"
domain = "127.0.0.1"
password = "123456"
target = "sip:alice@127.0.0.1" # The destination to call
# Probability to randomly cancel calls
cancel_prob = 30
[accounts.hangup]
after_secs = 5 # If the call is answered, hang up (send BYE) after 5 seconds
code = 486 # currectly not used for caller
```
> Note: if cancel_prob is set, caller will randomly deside cancel before or after ringing 50:50.
### How to Run
0. **Start the Sip Server**
1. **Start the Callee**:
The callee should be running first to receive calls.
```bash
cargo run -- wait --conf callee.toml
```
2. **Start the Caller**:
The caller initiates the calls. You can use `--total` and `--concurrent` to control the load.
```bash
sipbot --conf caller.toml call --total 100 --concurrent 3
```
## License
MIT