lingshu-gateway 0.10.0

Multi-platform messaging gateway for the Lingshu agent
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

# lingshu-gateway

> **Why this crate?** Your agent shouldn't live only in a terminal tab. `lingshu-gateway`  
> connects Lingshu to 15 messaging platforms — Telegram, Discord, Slack, WhatsApp, Signal,  
> Matrix, SMS, email, Home Assistant, and more — so you can reach it (and it can reach you)  
> from anywhere, on any device, without opening a laptop.

Part of [Lingshu](https://www.lingshu.com) — the Rust SuperAgent.

---

## Supported platforms

| Platform | Crate feature | Required env vars |
|----------|--------------|-------------------|
| Telegram | `telegram` | `TELEGRAM_BOT_TOKEN` |
| Discord | `discord` | `DISCORD_BOT_TOKEN` |
| Slack | `slack` | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` |
| WhatsApp | `whatsapp` | `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_ACCESS_TOKEN` |
| Signal | `signal` | `SIGNAL_CLI_PATH` |
| Matrix | `matrix` | `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` |
| Mattermost | `mattermost` | `MATTERMOST_URL`, `MATTERMOST_TOKEN` |
| DingTalk | `dingtalk` | `DINGTALK_APP_KEY`, `DINGTALK_APP_SECRET` |
| SMS (Twilio) | `sms` | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` |
| Email | `email` | `EMAIL_PROVIDER`, `EMAIL_FROM`, provider SMTP / API creds |
| Home Assistant | `homeassistant` | `HASS_URL`, `HASS_TOKEN` |
| Webhook | `webhook` | *(any HTTP caller)* |
| API server | `api_server` | `API_SERVER_PORT` *(optional, default 8080)* |

## Quick start

```bash
# Start the gateway (Telegram example)
export TELEGRAM_BOT_TOKEN=...
lingshu gateway --platforms telegram
```

```toml
# Or in ~/.lingshu/config.yaml
gateway:
  platforms: [telegram, discord]
  allowed_users: ["@alice", "123456789"]
```

## How it works

```
Platform adapter → DeliveryRouter → Agent.chat() → tool loop → reply
                                                              ↓
                                              StreamConsumer (live token edit)
```

Each platform implements the `PlatformAdapter` trait. `SessionManager` keeps one conversation  
per `(platform, user_id)` pair with configurable idle timeout. `DeliveryRouter` handles the  
`MEDIA://path` protocol for native photo / audio / document delivery.

## Per-user approval (DM pairing)

New users generate a pairing code your bot sends you in a DM. You approve with  
`/approve <code>` in the gateway session — no server restart needed.

## Add to your binary

```toml
[dependencies]
lingshu-gateway = { path = "../lingshu-gateway" }
```

```rust
use lingshu_gateway::GatewayRunner;

GatewayRunner::new(agent, config)
    .add_platform("telegram")?
    .run()
    .await?;
```

---

> Full docs, guides, and release notes → [lingshu.com](https://www.lingshu.com)