## 一、接口基础信息与能力说明
### 1.1 核心接口信息
- 统一编码：UTF-8
- 请求方式：GET / POST 均支持
- 服务可用性：7×24小时全天候提交

### 1.2 核心能力特性
- 支持全球境外手机、固话外呼，覆盖多国家与地区
- 提供双重鉴权模式：固定APIKEY快速接入、动态MD5加密提升安全等级
- 两种播报模式：完整文本自定义播报、备案模板变量播报
- 响应同时兼容 JSON / XML 两种格式，自动适配请求类型
- 单次请求支持提交1个境外号码，可通过批量循环实现群发

## 二、接入前环境与账号准备
### 2.1 账号注册与凭证获取
1. 登录用户中心，进入【云语音】-【国际语音通知】-【产品总览】板块
2. 获取两个核心鉴权参数：
   - `account`：APIID，接口调用的唯一账号标识
   - `APIKEY`：固定鉴权密钥，可直接调用接口，也可用于生成动态加密密码
3. 确认账号已开通国际语音通知业务权限，并在后台配置服务器出口IP白名单，避免调用时触发IP拦截。

### 2.2 号码格式规范
国际语音通知对号码格式有严格要求，单次请求仅支持传入1个号码，统一遵循「国家区号 + 空格 + 手机号」规则，港澳台及国际固话同理，示例如下：
- 美国手机号：`1 978234523`
- 中国香港手机号：`852 61234567`

## 三、接口请求规范详解
### 3.1 请求头要求
调用接口时需统一设置请求头，确保表单参数正确解析：

| 参数名称 | 参数固定值 | 类型 | 必填 |
| ---- | ---- | ---- | ---- |
| Content-Type | application/x-www-form-urlencoded | string | 是 |

### 3.2 核心请求参数说明
接口支持完整文本播报、模板变量播报两种模式，核心请求参数如下：

| 参数名称 | 参数说明 | 示例 | 类型 | 必填 |
| ---- | ---- | ---- | ---- | ---- |
| account | APIID，从产品总览页面获取 | 12345678 | string | 是 |
| password | 鉴权密码，二选一：<br>1. 固定鉴权：直接传入APIKEY<br>2. 动态鉴权：传入MD5加密后的动态密码 | abcdef123456 | string | 是 |
| mobile | 国际接收号码，单次仅传1个，格式为国家区号+空格+号码 | 1 978234523 | string | 是 |
| content | 语音播报内容：<br>完整播报模式直接填写文本；模板模式下多变量用英文竖线`\|`分隔 | 您的国际订单已发货，运单号HK20260731 | string | 否 |
| templateid | 国际语音模板ID，使用模板变量播报时必填；官方测试模板ID：2361 | 2361 | int | 否 |
| time | 10位Unix时间戳，仅动态密码鉴权模式下必填 | 1754064000 | string | 动态鉴权必填 |

## 四、响应参数与状态码对照表
### 4.1 基础返回参数
接口调用后会返回统一结构的响应结果，核心字段说明如下：

| 参数名称 | 参数说明 | 成功示例 | 类型 | 是否必返回 |
| ---- | ---- | ---- | ---- | ---- |
| code | 业务状态码，`2` 代表提交成功 | 2 | int | 是 |
| msg | 提交结果的文字描述 | 提交成功 | string | 是 |
| ivmid | 语音呼叫唯一流水号，调用失败时返回0或空字符串 | 17540640009876 | string | 提交成功时返回 |

### 4.2 常见错误状态码
接入调试过程中，可通过以下状态码快速定位并解决问题：

| code | msg 提示 | 问题说明 |
| ---- | ---- | ---- |
| 2 | 提交成功 | 呼叫任务已受理并进入排队队列 |
| 400 | 非法ip访问 | 服务器出口IP未添加至后台白名单 |
| 405 | 用户名或密码不正确 | account与APIKEY不匹配 |
| 406 | 手机格式不正确 | 境外号码缺少国家区号或格式不符合规范 |
| 4051 | 剩余条数不足 | 国际语音账户余额/条数不足 |
| 407 | 语音内容含有敏感字符 | 播报文本包含违规敏感词 |
| 4072 | 提交的语音内容必须与报备过的模板格式相匹配 | 传入变量数量与备案模板变量数量不一致 |
| 4082 | 超出同一手机号一天之内10条语音限制 | 单号码单日呼叫次数达到上限 |

## 五、接口调用实战示例
### 5.1 GET方式：完整文本播报
直接传入完整播报内容，适合内容固定、无需动态替换的通知场景：
```
https://api.ihuyi.com/ivm/Submit.json?account=12345678&password=abcdef123456&mobile=1 978234523&content=您的国际订单已发货，运单号HK20260731
```

### 5.2 GET方式：模板变量播报
使用已备案的模板ID+动态变量，适合批量发送、内容包含动态参数的场景。官方提供测试模板ID `2361`，对应3个变量位，示例如下：
```
https://api.ihuyi.com/ivm/Submit.json?account=12345678&password=abcdef123456&mobile=852 61234567&templateid=2361&content=HK20260731|顺丰国际|180美元
```

### 5.3 GET方式：动态MD5鉴权
为提升接口调用安全性，推荐使用动态密码鉴权模式。密码通过MD5加密生成，请求时需同步传入10位Unix时间戳：
```
https://api.ihuyi.com/ivm/Submit.json?account=12345678&password=md5加密后字符串&mobile=1 978234523&templateid=2361&content=HK20260731|顺丰国际|180美元&time=1754064000
```

### 5.4 响应返回示例
#### 成功返回（JSON格式）
```json
{
  "code": 2,
  "msg": "提交成功",
  "ivmid": "17540640009876"
}
```

#### 失败返回（JSON格式）
```json
{
  "code": 406,
  "msg": "手机格式不正确"
}
```

## 六、PHP 动态密码MD5加密实现
动态密码的加密规则为：`md5(account + 原始APIKEY + mobile + content + time)`，所有拼接内容必须统一为 UTF-8 编码后再进行加密，完整示例代码如下：

```php
<?php
// 账号鉴权配置
$account = '12345678';
$apikey = 'abcdef123456';

// 业务请求参数
$mobile = '1 978234523';
$content = 'HK20260731|顺丰国际|180美元';
$time = (string)time(); // 生成10位Unix时间戳

// 拼接明文字符串，统一使用UTF-8编码
$originStr = $account . $apikey . $mobile . $content . $time;
// 执行MD5加密，生成动态鉴权密码
$password = md5($originStr);

// 最终将 $password 作为 password 参数传入接口请求即可
?>
```

## 七、接入注意事项与排错指南
1. **号码格式校验**：所有境外号码必须携带对应国家/地区区号，区号与号码之间使用英文空格分隔，不可使用`+`号、短横线等其他连接符。
2. **模板报备要求**：使用模板变量模式前，需先在用户后台提交模板内容并通过审核，否则会触发模板未备案、格式不匹配等错误。
3. **调用频率限制**：接口对单号码有严格频率限制：每秒最多1次、每分钟最多3次、每日最多10次，业务逻辑中需做好频率控制，避免触发限流拦截。
4. **IP白名单配置**：生产环境建议提前配置服务器出口IP白名单，既可以提升接口调用安全性，也能避免非法IP访问报错。
5. **编码一致性**：所有请求参数必须统一使用 UTF-8 编码，避免中文播报内容出现乱码、敏感词误判等异常问题。


确认账号已开通国际语音通知业务权限，并在后台配置服务器出口IP白名单，避免调用时触发IP拦截。

国际语音通知SDK接入流程：开发者从环境配置到首条语音发送实战

在国际电商、国际社交、金融出海等业务场景中，短信触达率受限、高风险操作核验强度不足的问题普遍存在，国际语音通知凭借强提醒、高触达的特性，成为OTP身份核验、订单状态同步、异常风控告警的核心补充方案。
作为拥有22年行业经验的云通信服务商，提供稳定的国际语音通知API接口，支持全球多国家与地区的境外手机、固定电话外呼，开发者可通过原生API或国际语音通知SDK快速集成，实现7×24小时全天候语音呼叫

人工智能

国际语音通知接口支持全球境外号码外呼，提供固定APIKEY与动态MD5双重鉴权，兼容JSON/XML响应格式。号码需按国家区号+空格+手机号规范提交，单次请求限1个号码。支持完整文本与模板变量两种播报模式，附PHP动态加密示例。接口有单号码频率限制，需配置IP白名单并统一UTF-8编码。

代码解释

服务器

JSON

Unix

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

国际语音通知SDK接入流程：开发者从环境配置到首条语音发送实战-腾讯云开发者社区-腾讯云

国际语音通知SDK接入流程：开发者从环境配置到首条语音发送实战

国际语音通知SDK接入流程：开发者从环境配置到首条语音发送实战

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐