API参考

概述

百度语音通知服务(Voice Message Service,以下简称VMS)是百度智能云为用户提供的一种通信服务能力。通过向指定号码发起一通呼叫,呼叫被应答后,播放一段指定的音频。适用于各类以语音通信触达的场景。

接口速览

VMS API提供下列接口类型:

接口类型 描述
语音通知发起接口 用来发起一次呼叫,并播放通知内容。

通用说明

实名认证

使用VMS API的用户需要实名认证,没有通过实名认证的可以前往百度智能云控制台中的安全认证下的实名认证中进行认证。没有通过实名认证的用户请求将会得到一下错误提示码:

错误码 错误描述 HTTP状态码 中文解释
QualifyNotPass The User has not pass qualify. 403 账号没有通过实名认证

认证机制

所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成,均为字符串。 对于每个HTTP请求,使用下面所描述的算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。 认证字符串的格式为:

bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}

  • version是正整数。
  • timestamp是生成签名时的UTC时间。
  • expirationPeriodInSeconds表示签名有效期限。
  • signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。(本API签名仅使用host和x-bce-date两个header)
  • signature是256位签名的十六进制表示,由64个小写字母组成。

当百度智能云接收到用户的请求后,系统将使用相同的SK和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。

鉴权认证机制的详细内容请参见鉴权认证机制

通信协议

VMS API支持HTTP和HTTPS两种调用方式。为了提升数据的安全性,建议通过HTTPS调用。

请求结构说明

数据交换格式为JSON,所有request/response body内容均采用UTF-8编码。

请求参数包括如下4种:

参数类型 说明
URI 通常用于指明操作实体,如:POST /v{version}/instance/{instanceId}
Query参数 URL中携带的请求参数
HEADER 通过HTTP头域传入,如:x-bce-date
RequestBody 通过JSON格式组织的请求数据体

响应结构说明

响应值分为两种形式:

返回内容 说明
HTTP STATUS CODE 如200,400,403,404等
ResponseBody JSON格式组织的响应数据体

API版本号

参数 类型 参数位置 描述 是否必须
version String URI参数 API版本号 必须

幂等性

当调用创建接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过clientToken参数避免创建出比预期要多的资源,即保证请求的幂等性。

幂等性基于clientToken,clientToken是一个长度不超过64位的ASCII字符串,通常放在query string里,如http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

如果用户使用同一个clientToken值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的clientToken值,来确保只创建一个资源;如果用户提供了一个已经使用过的clientToken,但其他请求参数(包括queryString和requestBody)不同甚至url Path不同,则会返回IdempotentParameterMismatch的错误代码。

clientToken的有效期为24小时,以服务端最后一次收到该clientToken为准。也就是说,如果客户端不断发送同一个clientToken,那么该clientToken将长期有效。

日期与时间规范

日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡需要日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:

  1. 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日
  2. 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
  3. 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。

规范化字符串

通常一个字符串中可以包含任何Unicode字符。在编程中这种灵活性会带来不少困扰。因此引入“规范字符串”的概念。一个规范字符串只包含百分号编码字符以及URI(Uniform Resource Identifier)非保留字符(Unreserved Characters)。

RFC 3986规定URI非保留字符包括以下字符:字母(A-Z,a-z)、数字(0-9)、连字号(-)、点号(.)、下划线(_)、波浪线(~)。

将任意一个字符串转换为规范字符串的方式是:

  • 将字符串转换成UTF-8编码的字节流。
  • 保留所有URI非保留字符原样不变。
  • 对其余字节做一次RFC 3986中规定的百分号编码(Percent-Encoding),即一个%后面跟着两个表示该字节值的十六进制字母。字母一律采用大写形式。

示例:

原字符串:this is an example for 测试,
对应的规范字符串:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95

排版约定

排版格式 含义
< > 变量
[ ] 可选项
{ } 必选项
| 互斥关系
等宽字体Courier New 屏幕输出

服务域名

区域 服务端点Endpoint 协议
全局 vms.baidubce.com HTTP and HTTPS

公共请求头与公共响应头

公共请求头

头域 说明 是否必须
Authorization 包含Access Key与请求签名。 必须
x-bce-date 该请求创建的时间,表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日。如果用户使用了标准的Date域,该头域可以不填。当两者同时存在时,以x-bce-date为准。 可选
x-bce-content-sha256 表示内容部分的SHA256签名的十六进制字符串,其中内容指HTTP Request Payload Body,即Content部分在被HTTP encode之前的原始数据。 可选
x-bce-if-match 同If-Match语义。 可选
x-bce-if-none-match 同If-None-Match语义。 可选

公共响应头

头域 说明
Content-Length 只支持json格式,application/json; charset=utf-8。
x-bce-request-id VMS后端生成,并自动设置到响应头域中。

错误码

错误信息除了HTTP状态码以外,应同时在HTTP body中包含下表的参数,内容如下:

参数名 类型 说明
requestId String 导致该错误的requestId。
code String 表示具体错误类型。
message String 有关该错误的详细说明。

例如:

{ 
    "code":"AccessDenied", 
    "message":"Access denied.",
    "requestId":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7" 
}

公共错误码

错误码 消息 HTTP状态码 语义
AccessDenied Access denied. 403 Forbidden 无权限访问对应的资源。
InappropriateJSON The JSON you provided was well-formed and valid, but not appropriate for this operation. 400 Bad Request 请求中的JSON格式正确,但语义上不符合要求。如缺少某个必需项,或者值类型不匹配等。出于兼容性考虑,对于所有无法识别的项应直接忽略,不应该返回这个错误。
InternalError We encountered an internal error. Please try again. 500Internal Server Error 所有未定义的其他错误。在有明确对应的其他类型的错误时(包括通用的和服务自定义的)不应该使用。
InvalidAccessKeyId The Access Key ID you provided does not exist in our records. 403 Forbidden Access Key ID不存在。
InvalidHTTPAuthHeader The HTTP authorization header is invalid. Consult the service documentation for details. 400 Bad Request Authorization头域格式错误。
InvalidHTTPRequest There was an error in the body of your HTTP request. 400 Bad Request HTTP body格式错误。例如不符合指定的Encoding等。
InvalidURI Could not parse the specified URI. 400 Bad Request URI形式不正确。例如一些服务定义的关键词不匹配等。对于ID不匹配等问题,应定义更加具体的错误码,例如NoSuchKey。
MalformedJSON The JSON you provided was not well-formed. 400 Bad Request JSON格式不合法。
InvalidVersion The API version specified was invalid. 404 Not Found URI的版本号不合法。
OptInRequired A subscription for the service is required. 403 Forbidden 没有开通对应的服务。
PreconditionFailed The specified If-Match header doesn't match the ETag header. 412 Precondition Failed 详见ETag。
RequestExpired Request has expired. Timestamp date is XXX. 400 Bad Request 请求超时。XXX要改成x-bce-date的值。如果请求中只有Date,则需要将Date转换为datetime。
IdempotentParameterMismatch The request uses the same client token as a previous, but non-identical request. 403 Forbidden clientToken对应的API参数不一样。
SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details. 400 Bad Request Authorization头域中附带的签名和服务端验证不一致。

VMS错误码

错误码 消息 HTTP状态码 语义
NotImplemented This function has not been implemented. 501 当前不支持该功能。
VerifyFailed Company verify failed. Please check your user type. 403 企业验证失败,用户不是呼叫中心用户或用户类型检查未通过。
VerifyFailed Whitelist verify failed. 403 服务白名单检查失败。
VerifyFailed Template has not been verified. 403 发起语音通知使用的模板没有审核通过。
VerifyFailed Content is illegal. 403 内容非法,审核失败。
RequestFailed Sql injection was detected. 400 检测到SQL注入攻击。
RequestFailed Request failed. Template does not exist or invalid. 400 模板不存在或格式错误。
RequestFailed Request failed. Please check your request parameters. 400 请求失败,请检查请求参数。
RequestFailed Request failed. Please check input template parameters. 400 输入参数与模板未完全匹配。
RequestFailed Request failed. Please check your callback url. 400 客户回调地址不可用。
ExceedLimit Template number exceeded limitation. 403 当前模板数量已经达到最大值,无法再新增。
QueueFull Request queue is full. 429 超过了最大并发数。
IllegalNumber Called number is illegal or forbidden. 400 被叫号码被限制拨打。

语音通知发起接口

接口描述

这个接口负责发起一次呼叫,并播放通知内容。

权限说明

请求发起人需要具有合法的AccessKeyID和SecretAccessKey才能发起请求,请参考 鉴权认证
注意事项

发起语音通知前,需要先申请模板,并通过审核。

请求(Request)

  • 请求语法

    POST /v1/call HTTP/1.1
    Host: vms.baidubce.com
    x-bce-date: <Date> 
    Content-Length: <Content_Length> 
    Content-Type:application/json; charset=utf-8 
    Authorization: <Authorization_String> 
    { 
        "calledShowNumber":"12345678", 
        "calledNumber":"87654321", 
        "type":0, 
        "voiceMessageTemplateId":"123", 
        "voiceMessageVar":"name=test&number=1", 
        "userDefinedTag":"test", 
        "playTimes":1, 
        "voiceVolume":10
    }
    
  • 请求参数

名称 类型 描述 是否必须
calledShowNumber String 主显号码。 必须
calledNumber String 被叫号码。 必须
type Int 呼叫类型,目前仅支持0,即模板文本。 必须
voiceMessageTemplateId String 信息模板ID。 必须
voiceMessageVar String 对应ID模板的变量赋值,用&分割,每个变量用=号。 必须
playTimes Int 重复播放的次数,默认为1。 可选
voiceVolume Int 播放的音量,默认10,范围-20到20。 可选
userDefinedTag String 客户自定义的tag,为方便项目管理,原样返回给客户。 可选

响应(Response)

  • 响应头域

    除公共头域外,无其它特殊头域。

  • 响应参数

    名称 类型 描述
    callId String 本次发起请求的唯一id
    userDefinedTag String 客户自定义的tag,为方便项目管理,原样返回给客户
    dateCreate DateTime 请求建立时间,例如“2018-06-21T12:00:00Z”,请求不成功的时候为“”
    showNum String 发起呼叫的外显号码

示例

  • 请求示例

    POST /v1/call HTTP/1.1 
    Host: vms.baidubce.com 
    x-bce-date: <Date> 
    Content-Length: <Content_Length> 
    Content-Type:application/json; charset=utf-8 
    Authorization: <Authorization_String>  
    { 
        "calledShowNumber":"12345678", 
        "calledNumber":"87654321", 
        "type":0, 
        "voiceMessageTemplateId":"123", 
        "voiceMessageVar":"name=test&number=1", 
        "userDefinedTag":"test", 
        "playTimes":1, 
        "voiceVolume":10 
    }
    
  • 响应示例

    HTTP/1.1 200 OK 
    Date: Thu, 12 Jun 2018 09:26:46 GMT 
    Content-Type: application/json; charset=utf-8 
    x-bce-request-id:98f651c-e230-4810f-8092-f77506d848 
    { 
        "callId":"8ba82aacd62ad0595a9f8f68d1e3641d", 
        "userDefinedTag":"test", 
        "dateCreate":"2018-06-12T12:00:00Z", 
        "showNum":"12345678" 
    }
    

点击下载 Go SDK示例文件