简单消息服务SMS

    API详情

    如果您是初次调用百度智能云产品的API,可以观看API入门视频指南,快速掌握调用API的方法。

    短信发送和查询

    短信下发

    描述

    实现短信下发功能,一次支持提交多个手机号。

    注意:

    下发短信前,需要先申请签名和短信模板,并通过审核。系统内置模板可直接使用。

    URL

    /api/v3/sendSms

    HTTP Method

    POST

    请求参数

    参数名称 类型 是否必需 描述 示例
    mobile String 手机号码,支持单个或多个手机号,多个手机号之间以英文逗号分隔,一次请求最多支持200个手机号。国际/港澳台号码请按照E.164规范表示,例如台湾手机号以+886开头,”+“不能省略。 13800138000,13800138001,+886951234567
    template String 短信模板ID,模板申请成功后自动创建,全局内唯一 sms-tmpl-KyAUkV64619
    signatureId String 短信签名ID,签名表申请成功后自动创建,全局内唯一 sms-signQxkiwz88470
    contentVar String 模板变量内容,用于替换短信模板中定义的变量 {"param1":"123","param2":"abc"}
    custom String 用户自定义参数,格式为字符串,状态回调时会回传该值 -
    userExtId String 通道自定义扩展码,上行回调时会回传该值,其格式为纯数字串。默认为不开通,请求时无需设置该参数。如需开通请联系SMS帮助申请 123

    Query参数

    参数名称 类型 是否必需 描述 示例
    clientToken String 幂等性参数,避免client在http响应超时而重试时出现同一条短信多次发送的情况 -

    响应参数

    参数名称 类型 是否必需 描述
    requestId String 短信发送请求唯一流水ID
    code String 短信提交状态,1000表示成功
    message String 短信提交状态描述
    data List SendMessageItem数组,一个SendMessageItem对应一个手机号的响应结果

    HTTP请求示例

    POST http://smsv3.bj.baidubce.com/api/v3/sendSms?clientToken=e325ea68-02c1-47ad-8844-c7b93cafaeba
    Authorization: bce-auth-v1/626e6a284eac4e3f97cc30b38ffea6a4/2019-12-04T06:53:12Z/3600/host;x-bce-console-rpc-id;x-bce-date/d3a5b16483e4d999ce705cb3a8a2f30b728adcd422787a4bd2618b4e215c0327
    Content-Type: application/json
    Host: smsv3.bj.baidubce.com
    x-bce-date: 2019-12-04T06:53:12Z
    
    {
      "mobile": "13800138000",
      "template": "sms-tmpl-awKvRY85349",
      "signatureId": "sms-signQxkiwz88470",
      "contentVar": {
        "code": "23456",
        "minute": "1"
      }
    }

    成功响应示例

    HTTP/1.1 200 OK
    Content-Length: 218
    Content-Type: application/json;charset=UTF-8
    Date: Wed, 04 Dec 2019 06:53:13 GMT
    X-Bce-Request-Id: 5e6dacd5-8815-4183-8255-4ff079bf24e6
    
    {
      "requestId": "5e6dacd5-8815-4183-8255-4ff079bf24e6",
      "code": "1000",
      "message": "成功",
      "data": [
        {
          "code": "1000",
          "message": "成功",
          "mobile": "13800138000",
          "messageId": "e325ea68-02c1-47ad-8844-c7b93cafaeba_13800138000"
        }
      ]
    }

    状态回调

    描述

    将短信下发的状态报告通过回调业务方服务地址的方式告知业务方。

    URL

    由业务方提供。用户可以在“开发配置“中设置自己的上行回调地址

    HTTP Method

    POST

    请求参数

    名称 类型 是否必需 备注
    code String 0-发送成功,2-发送失败
    requestId String 请求id,与短信发送请求中的requestId对应
    messageId String 短信消息id
    mobile String 手机号
    carrierCode String 运营商原生状态码
    custom String 用户在发送请求中自定义的参数
    attemptCount int 尝试推送的次数,推送失败时会重试3次。无重试则为1
    segmentCount int 短信拆分后的条数
    deliverTime String 抵达时间,UTC时间
    requestTime String 请求时间,UTC时间

    响应参数

    响应参数由业务方自定义。百度云SMS会根据回调响应中的HTTP Status来判断是否回调成功,Status为200表示回调成功,非200表示回调失败。

    回调重试策略

    由于网络原因导致的推送失败(如连接超时等),SMS会启动重试策略。重试策略:推送失败,立即重试3次,失败后,间隔一个小时重试一次,最大重试次数是10次,超过最大重试次数停止重试。基于此重试策略,对于同一个messageId可能会重复推送,建议用户忽略第二次收到的状态推送请求,以避免重复处理。

    其他注意事项

    注意百度云SMS的回调请求源IP和端口均不固定,建议业务方不要对回调地址设置IP白名单。

    状态回调请求示例

    {
        "requestTime":"2019-12-03T22:53:00Z",
        "deliverTime":"2019-12-03T22:53:05Z",
        "code":"0",
        "requestId":"a6d5f1d9ca2048e5a5454e75da1db563",
        "custom":"example custom",
        "carrierCode":"DELIVRD",
        "mobile":"13800138000",
        "messageId":"c5366f96477b49ca90bcdff2516fe521"
    }

    响应示例

    HTTP/1.1 200 OK
    Content-Length: 50
    Content-Type: aplication/json;charset=UTF-8
    Date: Wed, 04 Dec 2019 06:53:13 GMT

    上行回调

    描述

    将用户收到短信后所回复的内容通过回调请求告知业务方。

    URL

    由业务方提供。用户可在“开发配置”中设置自己的上行回调地址

    HTTP Method

    POST

    请求参数

    名称 类型 是否必需 描述
    mobile String 手机号
    content String 内容
    sign String 签名
    receiveTime String 接收时间,UTC时间
    userExtId String 通道自定义扩展码,默认不开通,为空。

    响应参数

    响应参数由客户侧提供。百度云SMS会根据回调响应中的HTTP Status来判断是否回调成功,Status为200表示回调成功,非200表示回调失败。

    上行回调请求示例

    {
    	"mobile":"13800138000",
    	"content":"TD",
    	"sign":"百度云",
    	"receiveTime":"2019-12-03T22:53:05Z"
    }

    响应示例

    HTTP/1.1 200 OK
    Content-Length: 50
    Content-Type: aplication/json;charset=UTF-8
    Date: Wed, 04 Dec 2019 06:53:13 GMT
    上一篇
    API设计
    下一篇
    短信发送接口响应码