文档中心

语音服务

单次发送

单次发送（SingleBatchAppend）

批量创建单次发送任务。

接口说明

请求方式：POST
接口地址：https://cloud-vms.volcengineapi.com?Action=SingleBatchAppend&Version=2022-01-01

请求参数

Header

参数	数据类型	是否必填	示例值	描述
X-Date	String	是	20201103T104027Z	鉴权字段。请参考文档中心-火山引擎。
Authorization	String	是	HMAC-SHA256 Credential***	鉴权字段。请参考文档中心-火山引擎。
ServiceName	String	是	vms	服务名称。语音服务的服务名称为`vms`。
Region	String	是	cn-north-1	区域名称。
Content-Type	String	是	application/json	指定请求消息体的结构化格式。

Query

参数	数据类型	是否必填	示例值	描述
Action	String	是	SingleBatchAppend	接口名称。该接口固定值为`SingleBatchAppend`。
Version	String	是	2022-01-01	接口版本。

Body

参数	数据类型	是否必填	示例值	描述
List	List	是	无	追加请求列表

SingleParam

参数	数据类型	是否必填	示例值	描述
Phone	String	是	13333334444	号码
Type	Integer	是	0	类型：0-录音文件（默认）, 1-TTS模板，2-IVR流程
Resource	String	是	3cf1c12fc6c842faa451b23ad02324f1	话术资源id，比如语音文件id、tts模版id、ivr流程id
NumberPoolNo	String	是	NP160084061100694433	号码池编号
NumberList	List	否	["13344445555","13255556666"]	设置用于拨打的主叫号码列表，不填则走号码池选号逻辑，建议不填写
RingAgainTimes	Integer	否	1	重呼次数，默认0
RingAgainInterval	Integer	否	5	重呼间隔，最小5分钟，默认5
NumberType	Integer	否	0	号码池选号选择情况，0代表从整个号码池选号, 1代表从NumberList中选号，按照号码选号时需要设置，按照规则选号不设置该值
Ext	String	否	测试	用户自定义参数
PhoneParam	Map<String,Object>	否		tts模板的参数、ivr流程的变量值（最多支持2048个字符，超过直接返回报错）
TriggerTime	Date	否	2021-09-23 11:11:11	发送时间
MaxQueueWaitMinutes	Long	否	5	最大调度等待时长，64位整数，单位分钟，最小1分钟。未传则不限制等待时长。详见下方“最大等待时长说明”。
SingleOpenId	String	是	842faaecd	用户定义的唯一ID，用于幂等，重复的OpenId不会呼叫
SelectNumberRule	Integer	否	5	选号规则，目前仅支持5（根据被叫归属地选号），强烈建议走被叫归属地选号
CallRecordPostUrl	String	否	http:xxxx	话单推送地址，支持将当前号码产生话单推送至特定地址，需要在后台开启并配置通用回调地址之后才能生效
AudioPostUrl	String	否	http:xxxx	录音推送地址
ForbidTimeList	List	否	[{"Times":["10:00-11:00"],"Weekdays":[3]}]	禁呼时间设置
SmsConfig	SmsConfig	否	{"Items":[{"TemplateId":"xxxxx","Sign":"xxxxxx","StatusSet":[1,2,3]}],"Param":{}}	挂机短信配置

最大等待时长说明

作用： 设置语音通知的最大调度等待时长，避免告警过期后继续拨打。功能默认支持，传入 List[].MaxQueueWaitMinutes 后生效；未传则沿用原流程，不限制等待时长。
计时： 从 TriggerTime 开始，未设置则从首次入库开始；重呼和失败重试不重新计时、不续期。
到期： 停止后续拨打，生成 callResult=101（排队等待超时）的语音通知话单，通过现有话单回调推送。字段说明及示例见语音通知话单中的“排队超时话单”。
参数校验： 等待时长须为不少于1分钟的正整数，且截止时间不得溢出；不符合要求时，在 FailList 中返回 Type=INVALID_QUEUE_WAIT_MINUTES，详见通用错误码。

ForbidTimeItem

参数	数据类型	是否必填	示例值	描述
Weekdays	Set	否	[1,2]	1表示周日，2表示周一，以此类推，该参数不传代表每天都生效
Times	List	是	["09:00-10:00","15:00-16:00"]	禁呼时间段

SmsConfig

参数	数据类型	是否必填	示例值	描述
Items	List	是	[{"TemplateId":"xxxxx","Sign":"xxxxxx","StatusSet":[1,2,3]}]	挂机短信配置项
Param	Map<String,String>	否	{"name":"张三"}	挂机短信模板参数，会和 PhoneParam 中的参数合并，如果重复以 SmsParam 为准。

例子：

PhoneParam 配了 {"k1":"p1","k2":"p2"}，SmsParam 配了 {"k1":"s1","k3":"s3"}，最终 SmsParam 会变成 {"k1":"s1","k2":"p2","k3":"s3"}。

SmsConfigItem

参数	数据类型	是否必填	示例值	描述
TemplateId	String	是	ST_712d9312	模板id
Sign	String	是	测试	签名内容
StatusSet	Set	是	[1,2,3,4]	呼叫状态，1 已接通，2 未接通，3 呼叫失败，4 未拨打

返回参数

参数	数据类型	描述
ResponseMetadata	ResponseMetadata	见 ResponseMetadata
Result	Result	见下方

Result

参数	数据类型	示例值	描述
SuccessList	List	无	成功列表
FailList	List	无	失败列表

SingleResult

参数	数据类型	示例值	描述
Phone	String	18928398389	手机号
SingleOpenId	String	842faaecd	用户定义的唯一ID，用于幂等，重复的SingleOpenId不会呼叫
Ext	String	测试	用户自定义参数
Type	String	NO_PERMISSION	失败类型，如果成功则为 null

请求示例

{
  "List": [
    {
      "Ext": "1234",
      "NumberList": [
        "0571123455"
      ],
      "NumberPoolNo": "NP123456",
      "NumberType": "1",
      "Phone": "13344445555",
      "Resource": "123",
      "RingAgainInterval": 5,
      "RingAgainTimes": 1,
      "TriggerTime": "2021-09-23 11:40:05",
      "MaxQueueWaitMinutes": 5,
      "OpenId": "842faaecd"
    }
  ]
}

返回示例

{
  "ResponseMetadata": {
    "RequestId": "2021052017361001022509205912000B28",
    "Action": "SingleBatchAppend",
    "Version": "2022-01-01",
    "Service": "vms",
    "Region": "cn-north-1"
  },
  "Result": {
    "SuccessList": [
      {
        "Phone": "13344444444",
        "SingleOpenId": "1233333",
        "Ext": "1234"
      }
    ],
    "FailList": [
      {
        "Phone": "13344444444",
        "Type": "手机号格式错误"
      }
    ]
  }
}

最近更新时间：2026.10.30 14:28:35

这个页面对您有帮助吗？

有用

无用