腾讯云短信 Python SDK

腾讯短信服务

目前腾讯云短信为客户提供国内短信、国内语音和海外短信三大服务，腾讯云短信SDK支持以下操作：

国内短信

国内短信支持操作：

• 指定模板单发短信
• 指定模板群发短信
• 拉取短信回执和短信回复状态

Note 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)开通权限，量大客户可以使用此功能批量拉取，其他客户不建议使用。

海外短信

海外短信支持操作：

• 指定模板单发短信
• 指定模板群发短信
• 拉取短信回执和短信回复状态

Note 海外短信和国内短信使用同一接口，只需替换相应的国家码与手机号码，每次请求群发接口手机号码需全部为国内或者海外手机号码。

语音通知

语音通知支持操作：

• 发送语音验证码
• 发送语音通知
• 上传语音文件
• 按语音文件fid发送语音通知
• 指定模板发送语音通知类

开发

准备

在开始开发云短信应用之前，需要准备如下信息:

• 获取SDK AppID和AppKey

云短信应用SDK AppID和AppKey可在短信控制台的应用信息里获取，如您尚未添加应用，请到短信控制台中添加应用。

• 申请签名

一个完整的短信由短信签名和短信正文内容两部分组成，短信签名须申请和审核，签名可在短信控制台的相应服务模块内容配置中进行申请。

• 申请模板

同样短信或语音正文内容模板须申请和审核，模板可在短信控制台的相应服务模块内容配置中进行申请。

安装

pip

qcloudsms_py采用pip进行安装，要使用qcloudsms功能, 只需要执行:

pip install qcloudsms_py

手动

1. 手动下载或clone最新版本qcloudsms_py代码
2. 在qcloudsms_py目录运行 python setup.py install或直接把qcloudsms_py所在目录加入sys.path

Note python2/python3都支持

文档

若您对接口存在疑问，可以查阅:

• API开发指南
• SDK文档
• 错误码

示例

• 准备必要参数

# 短信应用SDK AppID
appid = 1400009099  # SDK AppID是1400开头

# 短信应用SDK AppKey
appkey = "9ff91d87c2cd7cd0ea762f141975d1df37481d48700d70ac37470aefc60f9bad"

# 需要发送短信的手机号码
phone_numbers = ["21212313123", "12345678902", "12345678903"]

# 短信模板ID，需要在短信应用中申请
template_id = 7839  # NOTE: 这里的模板ID`7839`只是一个示例，真实的模板ID需要在短信控制台中申请

# 签名
sms_sign = "腾讯云"  # NOTE: 这里的签名"腾讯云"只是一个示例，真实的签名需要在短信控制台中申请，另外签名参数使用的是`签名内容`，而不是`签名ID`

• 指定模板ID单发短信

from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPError

ssender = SmsSingleSender(appid, appkey)
params = ["5678"]  # 当模板没有参数时，`params = []`
try:
    result = ssender.send_with_param(86, phone_numbers[0],
        template_id, params, sign=sms_sign, extend="", ext="")  # 签名参数不允许为空串
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(result)

Note 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过，才可能下发成功，否则返回失败。

• 指定模板ID群发

from qcloudsms_py import SmsMultiSender
from qcloudsms_py.httpclient import HTTPError

msender = SmsMultiSender(appid, appkey)
params = ["5678"]
try:
    result = msender.send_with_param(86, phone_numbers,
        template_id, params, sign=sms_sign, extend="", ext="")   # 签名参数不允许为空串
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(result)

Note:群发一次请求最多支持200个号码，如有对号码数量有特殊需求请联系腾讯云短信技术支持(QQ:3012203387)。 Note 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过，才可能下发成功，否则返回失败。

• 发送语音验证码

from qcloudsms_py import SmsVoiceVerifyCodeSender
from qcloudsms_py.httpclient import HTTPError

vvcsender = SmsVoiceVerifyCodeSender(appid, appkey)
try:
    result = vvcsender.send("86", phone_numbers[0], "5678",
        playtimes=2, ext="")
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(result)

Note 语音验证码发送只需提供验证码数字，例如当msg=“5678”时，您收到的语音通知为“您的语音验证码是5678”，如需自定义内容，可以使用语音通知。

• 发送语音通知

from qcloudsms_py import SmsVoicePromptSender
from qcloudsms_py.httpclient import HTTPError

vpsender = SmsVoicePromptSender(appid, appkey)
try:
    result = vpsender.send("86", phone_numbers[0], 2, "5678",
        playtimes=2, ext="")
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(result)

• 拉取短信回执以及回复

from qcloudsms_py import SmsStatusPuller
from qcloudsms_py.httpclient import HTTPError

max_num = 10  # 单次拉取最大量
spuller = SmsStatusPuller(appid, appkey)
try:
    # 拉取短信回执
    callback_result = spuller.pull_callback(max_num)
    # 拉取回复
    reply_result = spuller.pull_reply(max_num)
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(callback_result)
print(reply_result)

Note: 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)，量大客户可以使用此功能批量拉取，其他客户不建议使用。

• 拉取单个手机短信状态

from qcloudsms_py import SmsMobileStatusPuller
from qcloudsms_py.httpclient import HTTPError

begin_time = 1511125600  # 开始时间(unix timestamp)
end_time = 1511841600    # 结束时间(unix timestamp)
max_num = 10             # 单次拉取最大量
mspuller = SmsMobileStatusPuller(appid, appkey)
try:
    # 拉取短信回执
    callback_result = mspuller.pull_callback("86", phone_numbers[0],
        begin_time, end_time, max_num)
    # 拉取回复
    reply_result = mspuller.pull_reply("86", phone_numbers[0],
        begin_time, end_time, max_num)
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(callback_result)
print(reply_result)

Note: 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)，量大客户可以使用此功能批量拉取，其他客户不建议使用。

• 发送海外短信

海外短信与国内短信发送类似, 发送海外短信只需替换相应国家码。

• 上传语音文件

from qcloudsms_py import VoiceFileUploader
from qcloudsms_py.httpclient import HTTPError

# Note: 语音文件大小上传限制400K字节
with open("/path/to/example.mp3", "rb") as f:
    content = f.read()
uploader = VoiceFileUploader(appid, appkey)
try:
    result = uploader.upload(content, content_type="mp3")
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

# 上传成功后，result里会带有语音文件的fid
print(result)

Note '语音文件上传'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通

• 按语音文件fid发送语音通知

from qcloudsms_py import FileVoiceSender
from qcloudsms_py.httpclient import HTTPError

# Note：这里fid来自`上传语音文件`接口返回的响应，要按语音
#   文件fid发送语音通知，需要先上传语音文件获取fid
fid = "c799d10a43ec109f02f2288ca3c85b79e7700c98.mp3"
fvsender = FileVoiceSender(appid, appkey)
try:
    result = fvsender.send(fid, phone_numbers[0],
        nationcode="86", playtimes=2, ext="")
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(result)

Note 按'语音文件fid发送语音通知'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通

• 指定模板发送语音通知

from qcloudsms_py import TtsVoiceSender
from qcloudsms_py.httpclient import HTTPError

template_id = 12345
params = ["5678"]
tvsender = TtsVoiceSender(appid, appkey)
Try:
    result = tvsender.send(template_id, params, phone_numbers[0],
        nationcode="86", playtimes=2, ext="")
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(result)

使用代理

有的环境需要使用代理才能上网，可以指定HTTPSimpleClient的proxy参数来实现, 示例如下:

from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPSimpleClient, HTTPError

httpclient = HTTPSimpleClient(proxy="www.proxysever.com:8080")
ssender = SmsSingleSender(appid, appkey, httpclient=httpclient)
template_id = 7839
params = ["5678"]
try:
    result = ssender.send_with_param(86, phone_numbers[0],
        template_id, params, sign=sms_sign, extend="", ext="")
except HTTPError as e:
    print(e)
except Exception as e:
    print(e)

print(result)

统一创建对象

短信和语音各类的对象可以通过 qcloudsms_py.QcloudSms 统一创建，这种 方式可以避免创建对象时多次传入参数appid 和 appkey, 示例如下:

from qcloudsms_py import QcloudSms

# 创建QcloudSms对象
qcloudsms = QcloudSms(appid, appkey)

# 创建单发短信(SmsSingleSender)对象
ssender = qcloudsms.SmsSingleSender()

# 创建上传语音文件(VoiceFileUploader)对象
uploader = qcloudsms.VoiceFileUploader()