# Air724UG 短信/来电转发设备 — 二次开发与对接文档

本设备基于 Air724UG（LuatOS / RDA8910）+ ESP8266 WiFi 模块，可接收短信与来电，并通过网络推送到企业微信、钉钉、飞书、Bark、Server酱、PushPlus 等渠道，也支持推送到你自己的服务器。

本文档面向希望在**设备外部**对设备进行集成/二次开发的开发者。**无需修改或获取设备固件源码**，通过设备提供的两类网络能力即可完成对接：

1. **主动推送（出站）**：设备收到短信/来电后，主动向你配置的地址 POST 数据；若配置了 `sms` 渠道，则会以**短信对短信**的方式转发到指定手机号（不依赖 WiFi / 数据网络）；
2. **管理接口（入站 HTTP API）**：你的程序主动调用设备接口，查询状态、读取短信、收发短信、拨打电话、修改配置等。

---

## 一、网络与访问前提

| 工作模式 | 说明 | 对接方式 |
|---|---|---|
| **WiFi 模式**（WIFI_MODE=1，默认） | 设备连接你局域网内的 WiFi 上网，4G 仅用于通话/短信 | 设备既可以主动外发推送，也会在局域网内开启 HTTP 服务，你可通过 `http://<设备IP>` 访问管理接口。 |
| **4G 模式**（WIFI_MODE=2） | 设备用 4G 蜂窝网络上网，并关闭 ESP8266 WiFi | 设备可主动**外发**推送；但设备位于运营商内网，**外部无法直接访问**设备的 HTTP 管理接口。此模式下建议用"主动推送"方式对接。 |

- WiFi 模式下，设备与你的电脑/服务器需在**同一个局域网（同一网段）**。
- 设备 IP 可在设备管理面板中扫描获得，或在路由器后台查看（设备名通常为 Air724/ESP8266）。
- 管理接口端口为 **80**，路径即下文所列。
- 无论哪种模式，只要 SIM 卡注册上网络，设备都能**收发短信**，因此 `sms`（短信对短信转发）渠道在两种模式下都可用，且**不依赖网络是否连通**。

---

## 二、对接方式一：主动推送（出站，推荐）

设备收到短信或来电后，会把内容 POST 到你配置的接收地址。你只需提供一个能接收 HTTP POST 的服务地址（公网服务器、内网服务器、或 Server酱/钉钉/企微等机器人地址均可）。若配置的是 `sms` 渠道，则不是 POST，而是把内容以短信发送到指定手机号（见 2.3）。

### 2.1 支持的内置渠道

配置通知类型（`NOTIFY_TYPE`）为以下之一或多个，设备会按对应平台格式推送：

| 渠道标识 | 平台 | 需要配置 |
|---|---|---|
| `sms` | **短信对短信转发**（转到指定手机号） | 目标号码 `SMS_FORWARD_NUMBER`（可选前缀 `SMS_FORWARD_PREFIX`） |
| `wecom` | 企业微信群机器人 | 机器人 Webhook 地址 |
| `dingtalk` | 钉钉群机器人 | Webhook 地址（可带加签 Secret） |
| `feishu` | 飞书群机器人 | Webhook 地址 |
| `bark` | Bark（iOS 推送） | Bark 服务器地址 + Key |
| `serverchan` | Server酱（方糖） | SendKey（只需填 SendKey，设备自动拼接地址） |
| `pushplus` | PushPlus | Token/Key |
| `pushdeer` | PushDeer | Key |
| `inotify` | INotify | API 地址（Key 已含在地址中） |
| `telegram` | Telegram Bot | API 地址 + Chat ID |
| `gotify` | Gotify | API 地址 + Token |
| `pushover` | Pushover | API Token + User Key |
| `next-smtp-proxy` | 邮件代理（转发到邮箱） | 代理 API + SMTP 账号 + 收件邮箱 |
| `custom_post` | **自定义 POST（对接自有系统）** | URL + Content-Type + 请求体模板 |

### 2.2 自定义 POST（custom_post）—— 对接你自己的系统

这是二次开发最常用的方式。配置三个参数：

| 参数 | 说明 | 示例 |
|---|---|---|
| `CUSTOM_POST_URL` | 你的接收地址 | `https://your-server.com/api/sms` |
| `CUSTOM_POST_CONTENT_TYPE` | 请求格式，**建议默认用 `application/json`** | `application/json` |
| `CUSTOM_POST_BODY_TABLE` | 请求体模板（Lua Table），其中 `{msg}` 会被替换为通知内容 | `{ ["title"]="短信", ["desp"]="{msg}" }` |

**占位符**：模板中所有字符串里的 `{msg}` 会在发送时被替换成完整通知文本（含短信内容、发件号码、发件时间、本机号码、信号、WiFi 等信息）。

**字段名规则（重要）**：模板里的字段名（如 `title`、`desp`）不是设备规定的，必须与你的接收方要求一致：
- 推给 Server酱：用 `title` / `desp`；
- 推给 PushPlus：用 `token` / `title` / `content`；
- 推给你自己的服务器：字段名由你的后端自行定义，后端按同名取值即可。

**Content-Type 选择**：
- `application/json`：请求体为 JSON，如 `{"title":"短信","desp":"...内容..."}`。企业微信/飞书/PushPlus/大多数自建 API 使用此格式。
- `application/x-www-form-urlencoded`：请求体为表单，如 `title=短信&desp=...`，字段值会自动做 URL 编码。仅当接收方明确要求表单时使用（如部分老接口、Bark、PushDeer）。

**自建接收端示例（Node.js / Express）**：
```js
// 设备以 application/json POST 到 /api/sms
app.post('/api/sms', express.json(), (req, res) => {
  console.log('收到设备推送:', req.body);
  // req.body.desp 即完整短信通知文本，自行解析处理
  res.json({ code: 0 });   // 返回 200 即可
});
```

**自建接收端示例（Python / Flask）**：
```python
from flask import Flask, request, jsonify
app = Flask(__name__)

@app.post("/api/sms")
def sms():
    data = request.get_json(force=True)
    print("收到设备推送:", data)
    # data["desp"] 为通知文本
    return jsonify(code=0)
```

> 设备判断推送是否成功以 HTTP 状态码为准：返回 **2xx** 视为成功；5xx 会自动重试；4xx 视为配置错误不重试。请确保你的接口对正确请求返回 200。

### 2.3 短信对短信转发（sms）—— WiFi/网络断开也能用

`sms` 渠道会把通知内容（收到短信、开机、插卡等）以**短信**形式转发到指定手机号，即"短信对短信"转发。它走的是 **4G 短信通道**，因此：

- **不依赖 WiFi / 数据网络**，WiFi 掉线或设备未联网时依然能转发；
- WiFi 模式（`WIFI_MODE=1`）和 4G 模式（`WIFI_MODE=2`）下**都可用**；
- 只要 SIM 卡注册上网络并有余额/短信功能即可。

**配置项**：

| 参数 | 说明 | 示例 |
|---|---|---|
| `SMS_FORWARD_NUMBER` | 转发目标手机号，建议带国家码（中国大陆为 `86` 开头） | `8613800138000` |
| `SMS_FORWARD_PREFIX` | 可选，转发短信内容前缀，便于识别来源 | `【短信转发】` |

**转发内容**：`SMS_FORWARD_PREFIX` + 通知正文。通知正文默认包含短信内容、发件号码、发件时间，以及本机号码、信号、WiFi 等设备信息（由 `NOTIFY_APPEND_MORE_INFO` 控制是否追加）。

**注意**：

- 转发短信由运营商正常计费，请留意短信条数；
- 当转发内容较长时（含中文约 70 字、纯英文约 160 字为一条），设备会自动拆分为多条长短信发送；如只想转发原始内容、减小长度，可把 `NOTIFY_APPEND_MORE_INFO` 设为 `false`；
- **不要把目标号码设为本机号码**，也不要配置成 `A→B→A` 的互相转发，否则会形成循环转发。

**配置方式**（任选其一）：

1. 配置生成器：勾选「短信转发」，填写转发目标号码（可选前缀），生成 `config_update.lua` 后放入 U 盘更新；
2. 设备管理面板：在「通知配置」中把通知类型选为「短信转发」并保存；
3. HTTP 接口：调用 `/setnotify`，传 `notify_type: "sms"` 和 `sms_forward_number`（见 3.9）。

**示例（直接改 config.lua）**：
```lua
NOTIFY_TYPE = { "sms" }
SMS_FORWARD_NUMBER = "8613800138000"
SMS_FORWARD_PREFIX = "【短信转发】"
```

---

## 三、对接方式二：管理接口（入站 HTTP API）

仅 WiFi 模式可用。基础地址：`http://<设备IP>`，所有接口返回 JSON，`success` 字段表示是否成功。

### 3.1 查询设备状态

```
GET /status
```

返回示例：
```json
{
  "success": true,
  "data": {
    "sim_number": "189****9154",
    "wifi_mode": 2,
    "wifi_ssid": "your-wifi",
    "wifi_ip": "192.168.1.29",
    "imei": "86xxxxxxxxxxxx",
    "uptime": 3600,
    "server_running": true,
    "temperature": "42.5",
    "signal_4g": 24
  }
}
```

### 3.2 读取短信记录

```
GET /sms
```

返回最近的短信记录（最多约 50 条），每条含绝对行号 `index`（用于删除）、时间、发件人、内容：
```json
{
  "success": true,
  "count": 12,
  "data": [
    { "index": 120, "time": "2026-09-02 16:47:05", "sender": "10001", "content": "您的余额为..." }
  ]
}
```

### 3.3 删除单条短信

```
POST /deletesms
Content-Type: application/json

{ "index": 120 }
```
`index` 使用 `/sms` 返回的绝对行号。成功返回 `{"success":true}`。

### 3.4 清空短信记录

```
POST /clearsms
```

### 3.5 发送短信

```
POST /sendsms
Content-Type: application/json

{ "to": "13800000000", "content": "短信内容" }
```
> `to` 也可写成 `phone`，`content` 也可写成 `message`。返回 `{"success":true,"message":"sms sending"}` 表示已提交发送。

### 3.6 拨打电话

```
POST /call
Content-Type: application/json

{ "phone": "13800000000" }
```

### 3.7 挂断电话

```
POST /hangup
```

### 3.8 修改 WiFi 配置

```
POST /setwifi
Content-Type: application/json

{ "ssid": "WiFi名称", "password": "WiFi密码" }
```
> 仅支持 2.4GHz WiFi。修改后设备会重连。

### 3.9 修改通知（转发）配置

```
POST /setnotify
Content-Type: application/json

{
  "notify_type": "custom_post",
  "custom_post_url": "https://your-server.com/api/sms",
  "custom_post_content_type": "application/json"
}
```

- `notify_type`：渠道标识，多个渠道用英文逗号分隔，如 `"wecom,custom_post"`、`"sms,wecom"`。可取值：`sms`、`wecom`、`dingtalk`、`feishu`、`bark`、`serverchan`、`pushplus`、`pushdeer`、`inotify`、`telegram`、`gotify`、`pushover`、`custom_post`。
- 各渠道地址/密钥参数（按所选渠道传对应字段即可）：

| 字段名 | 用途 |
|---|---|
| `sms_forward_number` | 短信转发目标号码（`SMS_FORWARD_NUMBER`） |
| `sms_forward_prefix` | 短信转发内容前缀，可空（`SMS_FORWARD_PREFIX`） |
| `wecom_webhook` | 企业微信 Webhook |
| `dingtalk_webhook` / `dingtalk_secret` | 钉钉 Webhook / 加签 Secret |
| `feishu_webhook` | 飞书 Webhook |
| `bark_api` / `bark_key` | Bark 服务器地址 / Key |
| `serverchan_api` | Server酱 SendKey（只填 SendKey 即可） |
| `pushplus_key` | PushPlus Key |
| `pushdeer_key` | PushDeer Key |
| `inotify_api` | INotify 地址（Key 已含在地址中） |
| `custom_post_url` | 自定义 POST 地址 |
| `custom_post_content_type` | 自定义 POST 格式（`application/json` 或 `application/x-www-form-urlencoded`） |

> 注：自定义 POST 的**请求体模板**（`CUSTOM_POST_BODY_TABLE`）为结构化配置，建议通过"配置生成器 + U盘更新"设置；多数场景使用默认模板 `{title/desp}` 即可。

### 3.10 查询当前配置

```
GET /config
```
返回设备当前主要配置（敏感字段如 WiFi 密码会脱敏为 `***`）。

### 3.11 远程重启

```
POST /reboot
```
设备会先返回成功响应，约 2 秒后重启。

---

## 四、配置方式（三种，任选其一）

1. **设备管理面板（网页）**：浏览器打开设备管理面板，扫描到设备后图形化配置 WiFi、转发方式、自定义 POST 等。
2. **配置生成器 + U盘**：用《配置生成器》网页生成 `config_update.lua`，放入 U盘（FAT32）插到设备，自动读取并应用后重启。文件名必须为 `config_update.lua`。
3. **HTTP 接口**：调用上文 `/setwifi`、`/setnotify` 等接口远程修改。

---

## 五、典型对接场景

**场景 A：把短信接入自己的业务系统（推荐，最简单）**
1. 部署一个公网可访问的 HTTP 接口（如 `https://your-server.com/api/sms`），接收 JSON 并返回 200；
2. 将设备通知方式设为 `custom_post`，URL 填你的接口，Content-Type 用 `application/json`；
3. 设备收到短信/来电即自动推送，你的系统入库、告警、二次分发均可。

**场景 B：局域网内轮询/控制设备**
- 设备与服务器在同一 WiFi 局域网，定时调用 `GET /sms` 拉取新短信、`GET /status` 监控在线状态，需要时调用 `/sendsms`、`/call`。

**场景 C：4G 环境下对接**
- 4G 模式下设备无法被外网主动访问，请使用"场景 A"的**主动推送**方式（设备主动外连你的公网接口）。

**场景 D：短信对短信转发（无需服务器）**
1. 设备通知方式设为 `sms`，`SMS_FORWARD_NUMBER` 填你的手机号（建议带国家码，如 `8613800138000`）；
2. 设备收到短信/来电通知后，会直接把内容以短信转发到该号码；
3. 因为走 4G 短信通道，**没网、WiFi 掉线时也能收到转发**，适合无服务器、纯短信场景；代价是转发短信按运营商计费。

---

## 六、常见问题

- **收不到推送？** ① 确认接收接口返回 200；② 自定义 POST 的字段名与接收方一致；③ 优先用 `application/json`，除非接收方明确要求表单；④ Server酱只需填 SendKey。
- **访问不了管理接口？** 确认设备工作在 WiFi 模式、与调用方同网段、IP 正确（用管理面板扫描）。
- **推送会重复吗？** 设备内置短信去重与通知队列；网络失败时对"安全可重试"错误（连接失败、发送失败）自动重试，对"可能已送达"的超时错误不盲目重试，避免重复。
- **支持长短信吗？** 支持，设备会自动合并长短信分段后再推送。
- **短信转发收不到？** ① 确认 `SMS_FORWARD_NUMBER` 填写正确（建议带国家码，如 `8613800138000`）；② 确认 SIM 卡已注册网络、未欠费且开通短信功能；③ 短信转发走 4G 短信通道，与 WiFi/网络无关，因此网络不通不影响它，但 **WiFi 模式与 4G 模式都要求 SIM 卡在网**；④ 转发短信按运营商计费，欠费会发送失败。

---

## 附：渠道标识速查

```
sms          短信对短信转发(转发到指定手机号)
wecom        企业微信
dingtalk     钉钉
feishu       飞书
bark         Bark
serverchan   Server酱(方糖)
pushplus     PushPlus
pushdeer     PushDeer
inotify      INotify
telegram     Telegram
gotify       Gotify
pushover     Pushover
next-smtp-proxy 邮件代理(转发到邮箱)
custom_post  自定义POST(自有系统)
```