短信上行接口（MO）接入全攻略：从HTTP回调到验签与幂等

做短信业务的朋友，十有八九都遇到过这类需求：用户回复了一条短信，业务系统怎么才能第一时间知道？很多人只做过下行（平台发短信给用户），对上行（MO，即用户手机发起的短信）一脸陌生。我自己第一次接上行接口时也栽过跟头，回头把整个环节梳理了一遍，才发现这件事本身并不复杂，真正麻烦的是协议差异、回调稳定性、签名验签这一连串细节。

这篇文章就从实践角度把用户短信回复功能的完整链路讲清楚。无论你是要做一个简单的关键词自动回复，还是要对接投票、客服、物流查询等业务，只要理解了上行接口的接入原理和常见坑，后续一切都会顺畅很多。

1. 上行接口到底是什么，为什么业务方都在问

1.1 一条短信的完整闭环是怎么跑的

很多人对短信的理解停留在"平台发一条、用户收一条"。这其实是短信下行（MT，Mobile Terminated）的视角。真正完整的业务闭环是双向的：平台先给用户发短信，用户看完之后回复一条，这条回复经过运营商网络、短信网关，最终回到你的业务系统——这个方向统称为上行，也叫MO（Mobile Originated）。

从技术链路上看，上行短信大致要经过这几个环节：用户手机发出短信，内容先到手机号归属的运营商交换机，再通过运营商短信中心进入行业短信网关。如果网关识别到接收方是某个SP服务号，就会按照SP侧的协议配置，把消息转交给服务商的接入平台。服务商再把上行内容以你约定的方式（通常是HTTP回调）送到你的服务器。

注意一个关键点：用户回复的接收号码不是你随便指定的，而是运营商分配给服务商的接入号，通常是一个特服号加扩展码的组合。所以在设计上行功能时，要确认"用户回复到哪个号码""这个号码对应哪个业务"，否则后面做多业务场景时会分不清渠道来源。

1.2 没有上行接口，业务会错过什么

先说一个最简单的场景：营销短信里经常带"回复TD退订"。如果只发下行、不接上行，用户退了也没人知道，退订诉求落在运营商的自动屏蔽策略里，但你的系统里完全没有记录。用户下次还会收到短信，投诉概率直线上升。接了上行接口之后，退订指令可以实时入库，自动加入黑名单，这才是合规运营的基础。

再比如互动类业务：短信投票、竞猜、调查问卷，用户回复"A"代表支持选项A，回复"1"代表选择方案1。这类业务完全依赖上行接口的实时性和准确性，数据进不来就谈不上统计。

还有一类很常见的是客服辅助类场景：用户回复"余额""物流""订单"等关键词，系统自动识别后查询后端数据，再以一条下行短信把结果回过去。整体体验虽然朴素，但对于没有智能机、没装App的边缘用户群体，短信仍然是性价比极高的触达方式。

所以上行的本质是：把用户的主动诉求接入到你的系统里。它解决的不只是一个接口联调问题，而是业务闭环的最后一公里。

2. 方案选型：直连运营商还是走短信服务商

2.1 三种主流协议的核心差异：别被CMPP、SGIP、SMGP吓住

如果选择直连运营商，你会接触到一批缩写：CMPP、SGIP、SMGP。它们分别是移动、联通、电信的短信网关协议，名称不同，但解决的问题高度相似——定义SP（服务提供商）与运营商网关之间如何鉴权、如何提交下行短信、如何推送上行短信。

CMPP是移动的协议，基于TCP长连接，SMPP又在其上做了很多扩展，对象、消息格式、会话管理都有严格规定。SGIP对应联通，SMGP对应电信。这些协议都有固定的消息头、消息体、序列号、时间戳、鉴权方式，通信过程也分连接建立、登录认证、发送、接收回执、接收上行等多个指令类型。

我的建议是：除非你有专职团队、并且短信量大到直连比走服务商便宜很多，否则不要自研直连模块。协议本身的学习成本不高，但维护成本高——运营商侧参数调整、IP白名单变更、长连接保活、重连策略、多节点负载均衡，任何一个环节出问题都够你加班几晚上。

走短信服务商（即"平台转售/接入服务"模式的第三方），通常会把底层协议的差异封装成统一接口，让你用HTTP方式接入。省掉的是协议细节，换来的是快速交付。

2.2 为什么HTTP回调是最适合大多数团队的选择

短信服务商提供的上行接入方式，目前最主流的就是HTTP回调。服务商在收到用户上行短信后，把你的业务地址作为回调URL，通过POST或GET请求把消息内容推送过来，你的服务只需要响应一个约定格式即可。

HTTP回调相比直连协议有几个非常现实的优势。第一，你的业务服务器不需要对外建立长连接，只需要提供一个公网HTTP服务，这对部署在云上的大多数应用来说是天然友好的。第二，调试简单，用浏览器或curl就能模拟请求，问题定位路径短。第三，扩展方便，一个回调地址可以对应多个业务，通过扩展码区分即可。

当然HTTP回调也有缺点：实时性受网络影响、回调可能重复或丢失、需要处理响应超时。但这些缺点都有成熟的应对方案，后文会展开讲。对于绝大多数中小团队和项目来说，HTTP回调是"足够好"的默认选择。

这里补充一个选型建议：如果你的短信量达到每月百万级，并且对成本敏感，再考虑CMPP/SGIP/SMGP直连。在此之前，把自己的精力和时间花在业务逻辑上，比花在网关协议上划算得多。

3. 接口开发实操：从回调地址到自动回复

这部分我直接用一个可运行的最小实现做演示。技术栈选Python + Flask，数据库用MySQL，核心逻辑是通用的，换成其他语言也只是语法差异。

3.1 字段约定与建表

在动手写代码之前，先弄清楚服务商回调时会带哪些字段。不同服务商字段名略有差异，但核心信息几乎逃不开这几类：

• 手机号：用户回短信的手机号码，通常是11位手机号。
• 上行内容：用户发送的短信原文，注意可能是经过URL编码或Base64编码的。
• 接收号码：用户回复到的服务号+扩展码，用来区分业务渠道。
• 上行时间：运营商接收到上行短信的时间。
• 消息ID：本次上行的唯一标识，服务商用来做幂等或重推。
• 签名参数：用于验证回调请求合法性的字段，常见是token+字段+时间戳组合计算的MD5或HMAC值。

建表时，建议至少包含这些列：

sql复制CREATE TABLE mo_log (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    msg_id VARCHAR(64) NOT NULL UNIQUE COMMENT '上行消息唯一ID',
    mobile VARCHAR(20) NOT NULL COMMENT '用户手机号',
    content VARCHAR(500) NOT NULL COMMENT '上行内容',
    sp_code VARCHAR(20) NOT NULL COMMENT '服务号/扩展码',
    receive_time DATETIME NOT NULL COMMENT '上行时间',
    raw_data TEXT COMMENT '原始报文，留作审计',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    KEY idx_mobile (mobile),
    KEY idx_sp_code (sp_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='上行短信记录表';

msg_id设置唯一索引非常重要，这是后面处理重复回调的根基。sp_code单独建索引，是因为经常需要按业务渠道统计和路由；mobile字段也建议建索引，后续查用户历史回复会很频繁。

3.2 回调接口实现与验签逻辑

先看一个最常见的回调格式（服务商一般用JSON）：

json复制{
  "mobile": "13800138000",
  "content": "Y2hhZF96aA==",
  "spCode": "1069xxxx",
  "moTime": "2024-05-20 10:30:00",
  "msgId": "90000000001",
  "sign": "a1b2c3d4e5f6..."
}

content字段这里是Base64编码后的内容，解码出来可能是"查询订单"的原文。验签通常是把token、mobile、content、moTime按照一定顺序拼接后做MD5，具体拼接规则每个服务商不一样，接入前仔细看服务商文档，或者直接问客服要一份签名示例。

回调接口的完整实现如下：

python复制# app.py
import base64
import hashlib
import json
from datetime import datetime

from flask import Flask, request, jsonify

app = Flask(__name__)

# 配置项，请替换成你自己的
APP_TOKEN = "your-service-token"
APP_SECRET = "your-service-secret"


def verify_sign(params):
    """验签：具体拼接规则以服务商文档为准"""
    raw = f"{APP_TOKEN}{params.get('mobile', '')}{params.get('content', '')}{params.get('moTime', '')}"
    return params.get("sign", "") == hashlib.md5(raw.encode("utf-8")).hexdigest()


def decode_content(content):
    """兼容Base64编码和明文两种情况"""
    if not content:
        return ""
    try:
        return base64.b64decode(content).decode("utf-8")
    except Exception:
        # 有些服务商会直接回明文
        return content


@app.route("/mo/callback", methods=["POST"])
def mo_callback():
    # 1. 解析JSON
    try:
        params = request.get_json(force=True)
    except Exception:
        return jsonify({"code": 400, "msg": "invalid json"}), 400

    # 2. 验签
    if not verify_sign(params):
        return jsonify({"code": 401, "msg": "invalid sign"}), 401

    # 3. 解析字段
    mobile = params.get("mobile", "")
    content = decode_content(params.get("content", ""))
    sp_code = params.get("spCode", "")
    mo_time = params.get("moTime", "")
    msg_id = params.get("msgId", "")

    # 4. 入库（此处省略具体数据库操作，SQL见上文）
    # save_mo_log(msg_id, mobile, content, sp_code, mo_time, json.dumps(params))

    # 5. 触发业务逻辑，比如关键词自动回复
    trigger_business(mobile, content, sp_code)

    # 6. 快速响应
    return jsonify({"code": 0, "msg": "success"})

这段代码有几个细节要特别说明。验签放在最前面，如果验签失败但服务商不强制要求白名单，那你的回调地址就是开放的，任何人都可以伪造请求往你的库里灌数据。所以验签不是可选项，是必须项。content解码要兼容Base64和明文两种情况，少写一个分支就会出现一批乱码。

入库和业务处理是同步做的，但在高并发场景下这不够。后面4.2小节会给出异步优化方案。

3.3 关键词指令解析与自动回复

收到上行短信之后，最常见的需求就是触发下行短信回复。指令解析不难，难的是边界情况处理。以"回复TD退订""回复查询订单"为例，业务侧通常要做这几件事：

python复制def normalize_text(text):
    """归一化：去掉首尾空白，统一转小写，全角转半角"""
    if not text:
        return ""
    text = text.strip().lower()
    # 全角转半角
    table = str.maketrans({chr(0xFF01 + i): chr(0x21 + i) for i in range(94)})
    return text.translate(table)


def trigger_business(mobile, content, sp_code):
    text = normalize_text(content)

    # 退订指令
    if text in ("td", "td退订", "退订", "0000"):
        # 加入黑名单、更新用户退订状态
        # unsubscribe(mobile, sp_code)
        return

    # 关键词查询
    if text.startswith("查询订单"):
        order_no = text.replace("查询订单", "").strip()
        # 根据order_no查订单，再调下行接口推送结果
        return

    # 其他指令
    ...

全半角归一化这个操作，很多人会忽略。用户手机输入法千奇百怪，全角字母、全角空格、大小写混用都很常见，不归一化就会出现指令明明在业务规则里定义了，用户发了却没法正确触发的情况。"TD"和"td"如果不统一处理，就要在判断条件里写两个分支，后患无穷。

自动回复要走服务商的下行接口，也就是再调一次HTTP POST，把目标手机号和回复内容提交过去。这里要注意，下行接口可能也有频控限制，同一手机号短期内不要连续下发多条，否则容易被运营商侧的频控策略拦截。

3.4 部署阶段的三件关键事

第一件事，保证回调地址公网可达。很多人开发环境在本地，回调URL写成localhost或者内网地址，服务商那边自然永远推不过来。部署时必须用一个云服务器公网IP或域名，并且确保防火墙放行对应端口。上线前可以用curl模拟一个POST请求自测，而不是等着真机验证。

第二件事，配置响应超时策略。服务商对回调响应时间通常要求在3到5秒内返回，超过时间会判定失败并触发重推。所以回调接口内部不要做耗时操作，比如同步请求外部API、执行复杂计算。正确姿势是：先快速验签、快速入库，然后马上返回成功，再异步去处理业务。

第三件事，准备好HTTPS。短信属于敏感业务场景，回调链路里包含了用户手机号、消息内容，明文HTTP容易被中间人截获。条件允许的话，在Nginx或云负载均衡层配置HTTPS证书，同时要求服务商回调也走HTTPS。这样做一方面保护数据，另一方面也避免某些运营商侧网关对明文HTTP的兼容性限制。

Nginx反向代理的参考配置：

nginx复制server {
    listen 443 ssl;
    server_name mo.example.com;

    ssl_certificate     /etc/nginx/ssl/mo.pem;
    ssl_certificate_key /etc/nginx/ssl/mo.key;

    location /mo/callback {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 10s;
    }
}

这里要注意，Nginx的proxy_read_timeout不要设得太短，否则上游Flask还没处理完，Nginx就已经返回504了，服务商看到非200就会重推，容易造成重复。

4. 高频问题排查与工程化加固

4.1 高频问题速查表

做短信上行接入，遇到最多的就是下面这几类问题。我整理成一张速查表，基本覆盖了联调和初上线阶段八成以上的故障：

这中间最隐蔽的是编码问题。运营商侧最早的上行短信编码是UCS-2（即UTF-16），服务商网关转换后可能输出GBK，也可能输出Base64编码的UTF-8，如果你的解码方向和它不一致，出来的就是一堆问号。建议在联调阶段就主动发一条中文回复、一条英文回复、一条特殊字符回复，把三种样本全部跑通，再上线。

其次是重复问题。服务商为了保证送达，普遍会对未收到成功响应的回调做间隔重推。这个机制本身是合理的，但如果你的入库没有唯一约束，重推一次就多一条脏数据。所以msgId唯一索引必须建，并且插入时用INSERT IGNORE或ON DUPLICATE KEY UPDATE。

4.2 幂等、限流、异步：把"能用"变成"好用"

走到能收能回这一步，只是入门。真正能扛住运营活动的系统，还要做好三件事。

第一件，幂等处理。除了在数据库层面对msgId加唯一索引，业务逻辑层也要做防重。比如用户回复退订，重推导致的重复触发退订逻辑虽然最终状态一致，但过程可能多打一次通知、多写一次操作日志。更稳妥的做法是在业务入口处做一个Redis缓存判断：

python复制import redis

r = redis.Redis(host="localhost", port=6379, db=0)


def is_dup(msg_id):
    """利用Redis SETNX做去重，类似分布式锁"""
    return not r.set(f"mo:{msg_id}", "1", nx=True, ex=600)

判断到重复msgId直接返回成功，不再重复执行业务，这样既不影响服务商的重推机制，又保证了业务只被执行一次。

第二件，限流。短信上行是天然的高峰流量场景，一次电视直播互动可能瞬间涌入上万条回复。如果处理接口没有限流，数据库和下游接口都会被冲垮。最简单的方案是在IP层面做令牌桶限流，也可以在服务商回调入口处加一层基于Redis的计数器限流，每秒允许的最大请求数根据你的库容量和下行接口配额来设定。

第三件，异步化。回调接口的快速响应是第一位的要求。无论你想在收到上行后做什么，数据库入库、黑名单更新、下行回复、数据分析，全部可以往消息队列里丢。收到请求后，把整个报文原样扔进队列，立即返回"接收成功"，再由worker慢慢消费。这个模式在短信业务里几乎是标配，原因很简单：回调接口不是你控制节奏的，服务商随时会推，你必须能瞬间消化"接收"这个动作，把所有计算留到自己的节奏里。

监控方面，建议至少盯三个指标：回调接收成功率（收到的请求中验签通过的比例）、入库及时性（从收到请求到写入库的耗时）、业务触发成功率（上行触发下行回复的占比）。任何一个指标出现明显下滑，都能快速定位是服务商链路问题还是自己业务逻辑问题。

5. 沉淀下来的几点运营心得

接入短信上行接口到现在，我在实际项目中感受最深的一点是：回调接口本身不是瓶颈，链路里的各种隐性约定才是。比如不同服务商的验签规则、编码规则、重推策略、响应格式要求，没有任何标准可循，全靠文档一字一字抠。所以接入新服务商时，我习惯先找一个不那么重要的业务场景做灰度，跑通后再全量切流量。

另外，字段的审计很重要。原始报文建议完整保留在库里或者日志里，不要只存解析后的字段。出现数据不一致或者纠纷时，有原始报文兜底，比事后到处翻日志强得多。我见过不止一次，用户投诉"我明明回复了退订为什么还在发"，最后就是靠原始报文定位到是某个环节的编码转换丢了字符。

还有一个容易被忽略的小技巧：上线前用真实的手机号发一条对照测试。模拟工具能验证接口接收流程，但真实链路里运营商侧还会做内容过滤、频控等动作，这些只有真机测试才能暴露。建议准备一张测试卡，每次改动上线后都发一条中文、一条英文、一条特殊字符的回复，确认链路完好。

用户短信回复这个功能，做好之后会变成业务里非常顺手的一环。退订、查询、互动、客服，都靠它撑起来。希望这篇文章能帮你少走一些弯路，顺利把上行接口跑通。如果后面遇到具体问题，多从"服务商文档约定""链路可达性""重推幂等"这三个角度排查，绝大部分故障都能定位到根因。