## H2 一、国际营销语音电话接口概述
国际语音通知 API 支持 GET、POST 两种提交方式，编码统一 UTF-8，7×24 小时稳定提交。鉴权提供两种方案：固定 APIKEY 鉴权适合快速调试接入；动态 MD5 密码鉴权安全性更高，适合生产环境对外暴露服务的场景。接口单次支持提交单个境外号码呼叫，响应自动兼容 JSON、XML 两种格式，后端开发者可以按需选择解析格式。
>重要提醒：营销类语音外呼需要遵守目标国家和地区的通信法规，客户号码需要获得用户许可，提前报备语音模板，避免号码被标记、账号风控冻结。

## H2 二、接口基础调用规范

### H3 2.1 请求地址

```
https://api.ihuyi.com/ivm/Submit.json
```### H3 2.2 请求头


表格

|参数名称|参数固定值|类型|必填|
|:-:|:-:|:-:|:-:|
|Content-Type|application/x-www-form-urlencoded|string|是|
### H3 2.3 请求参数说明


表格

|参数名称|参数说明|示例|类型|必填|
|:-:|:-:|:-:|:-:|:-:|
|account|APIID获取路径：用户中心【云语音】-【国际语音通知】-【产品总览】|12345678|string|是|||
|password|鉴权密码二选一：1. 固定鉴权：APIKEY（产品总览查看）2. 动态鉴权：MD5 加密动态密码（文末提供加密代码）|abcdef123456|string|是|||
|mobile|国际接收号码，单次仅传 1 个；格式规范：国家区号 + 空格 + 手机号港澳台 / 海外固话同理：区号空格号码|

|templateid|国际语音模板 ID，使用模板变量播报时必填调试测试模板 ID：2361默认测试模板内容：您的海外订单号：【变量】，承运商：【变量】，金额：【变量】，请注意接听|2361|int|否|||
|time|10 位 Unix 时间戳仅使用**动态密码鉴权**时必填|1754064000|string|动态鉴权必填|||
### H3 2.4 返回参数


表格

|参数名称|参数说明|成功示例|类型|是否必返回|
|:-:|:-:|:-:|:-:|:-:|
|code|业务状态码，2 = 提交成功|2 / 1|int|是|
|msg|提交结果文字描述|提交成功 / 手机号格式错误|string|是|
|ivmid|语音呼叫唯一流水号；失败返回 0 或空字符串|17540640009876|string|提交成功返回|
## H2 三、状态码排查对照表（营销外呼高频报错）

营销场景批量外呼最容易碰到频率限制、模板未报备、风控拦截问题，开发对接时建议提前做好异常分支判断：

表格

|code|msg提示|问题说明|
|:-:|:-:|:-:|
|0|提交失败|通用未知提交异常|
|2|提交成功|呼叫任务已受理排队|
|400|非法 ip 访问|服务器出口 IP 未备案 / 未添加白名单|
|401|帐号不能为空|account 参数缺失|
|402|密码不能为空|password 参数缺失|
|403|手机号码不能为空|mobile 参数为空|
|4030|手机号码已被列入黑名单|该境外号码限制外呼|
|404|语音内容不能为空|未传 content 且未传合法 templateid|
|405|用户名或密码不正确|account/APIKEY 不匹配|
|4050|账号被冻结|账户欠费 / 违规冻结，联系客服|
|40505|没有签定合同|未开通国际语音业务权限|
|4051|剩余条数不足|国际语音余额不足|
|4052|访问 ip 与备案 ip 不符|服务器出口 IP 和后台备案不一致|
|406|手机格式不正确|境外号码缺少国家区号、格式不规范|
|407|语音内容含有敏感字符|播报文本包含违规敏感词|
|4071|没有提交备案模板|使用 templateid 但模板未报备审核|
|4072|提交的语音内容必须与报备过的模板格式相匹配|传入变量数量与备案模板变量数量不一致|
|40722|变量内容超过指定的长度|单个变量文本超出模板限制字数|
|4077|播报内容未在运营商报备|完整文本播报模式未提前报备文案|
|408|您的帐户疑被恶意利用，已被自动冻结，如有疑问请与客服联系。|风控检测异常自动冻结账号|
|4080|同一手机号码同一秒钟之内发送频率不能超过 1 条|单号码每秒呼叫上限 1 次|
|4081|同一手机号一分钟之内发送超过 3 条|单号码每分钟呼叫上限 3 次|
|4082|超出同一手机号一天之内 10 条语音限制|单号码单日最大呼叫 10 次|
|4086|提交失败|接口服务内部异常，稍后重试|
>营销场景开发建议：单独对 4080、4081、4082 做限流排队，接入异步队列，不要循环暴力重试；4077、4071 属于模板合规问题，上线营销语音务必提前提交模板审核。

## H2 四、调用示例

### H3 4.1 GET 固定密钥调用（完整文本播报，营销场景）


```### H3 4.2 GET 模板变量模式

```

```### H3 4.3 GET 动态 MD5 鉴权模式（生产推荐）

```

```### H3 4.4 返回结果示例

✅ JSON 成功返回
```
{
  "code": 2,
  "msg": "提交成功",
  "ivmid": "17540640009876"
}
```✅ XML 成功返回
```
<?xml version="1.0" encoding="utf-8"?>
<SubmitResult>
  <code>2</code>
  <msg>提交成功</msg>
  <ivmid>17540640009876</ivmid>
</SubmitResult>
```❌ JSON 失败示例
```
{
  "code": 406,
  "msg": "手机格式不正确"
}
```❌ XML 失败示例
```
<?xml version="1.0" encoding="utf-8"?>
<SubmitResult>
  <code>406</code>
  <msg>手机格式不正确</msg>
</SubmitResult>
```## H2 五、PHP MD5 动态加密代码（UTF-8 编码）

加密规则：`md5(account + 原始APIKEY + mobile + content + time)`
全部字符串拼接前统一 UTF-8 编码，避免不同语言环境加密结果不一致：
```
<?php
$account = '12345678';
$apikey = 'abcdef123456';
$mobile = '1 978234523';

$time = '1754064000';

// 拼接明文
$originStr = $account . $apikey . $mobile . $content . $time;
// 生成动态密码
$password = md5($originStr);

// 最终请求参数 $password 传入加密后字符串
?>
```## H2 六、系统集成开发方案（营销批量外呼重点）

国际营销语音电话接口开发和普通通知语音不一样，营销业务一般是批量号码导入、定时触达、重试、数据统计，这里给一套成熟的开发思路：

1. **号码清洗层**：提前校验国际号码格式，统一处理国家区号，过滤黑名单号码，防止 406、4030 报错；

2. **异步队列层**：使用 MQ、Redis 队列削峰，严格遵守单号码限流规则（秒 1、分钟 3、日 10），避免触发风控；

3. **鉴权分层**：测试环境使用固定 APIKEY 快速开发，生产环境全部切换 MD5 动态鉴权；

4. **回执与统计**：保存 ivmid 流水号，对接回执接口，统计接通率、未接通、拒接数据，用于营销转化分析；

5. **模板管理模块**：营销文案统一后台提交审核，缓存已通过 templateid，减少上线合规风险；

6. **多环境兼容**：Java、PHP、Python、Go 等后端语言统一使用 UTF-8 编码，重点处理中文、特殊符号编码错乱导致 MD5 结果不一致问题。


## H2 七、多语言 SDK 示例清单


- Java

- PHP

- Python

- C

- C++

- C#

- Go

- Shell

- Ruby

- Node.js

- Objective-C

国际语音通知 API 支持 GET、POST 两种提交方式，编码统一 UTF-8，7×24 小时稳定提交。鉴权提供两种方案：固定 APIKEY 鉴权适合快速调试接入；动态 MD5 密码鉴权安全性更高，适合生产环境对外暴露服务的场景。接口单次支持提交单个境外号码呼叫，响应自动兼容 JSON、XML 两种格式，后端开发者可以按需选择解析格式。

国际营销语音电话接口如何集成？全球外呼 API 系统开发实现教程

国际营销语音电话接口，也就是全球外呼 API，主要面向跨境商家、出海企业、海外营销团队，用来自动拨打境外手机、港澳台以及海外固话，播放营销通知、活动回访、产品推介、客户唤醒等语音内容。和普通国际短信相比，语音外呼触达更强，适合高优先级营销触达、老客召回、活动提醒等业务场景。

编程语言

国际营销语音电话接口支持GET/POST提交、UTF-8编码，提供APIKEY与MD5动态鉴权双方案，适配JSON/XML响应。单次外呼需遵守目标地区法规，用户需许可并报备模板。接口返回code 2成功，常见错误码覆盖黑名单、频率限制、模板违规等。开发方案强调号码清洗、异步队列限流及回执统计，多语言SDK齐全，适合营销批量外呼场景。

代码解释

Objective-C

服务器

Python

Redis

JSON

Java

Unix

腾讯云双十一大促

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

国际营销语音电话接口支持GET/POST提交、UTF-8编码，提供APIKEY与MD5动态鉴权双方案，适配JSON/XML响应。单次外呼需遵守目标地区法规，用户需许可并报备模板。接口返回code 2成功，常见错误码覆盖黑名单、频率限制、模板违规等。开发方案强调号码清洗、异步队列限流及回执统计，多语言SDK齐全，适合营销...

国际营销语音电话接口如何集成？全球外呼 API 系统开发实现教程-腾讯云开发者社区-腾讯云

国际营销语音电话接口如何集成？全球外呼 API 系统开发实现教程

国际营销语音电话接口如何集成？全球外呼 API 系统开发实现教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐