迁移到 API v2 文档
迁移到 API v2
v2
迁移到 API v2
v2
迁移到 API v2
为现有集成提供基于令牌的认证
您的集成通过 /api/v1 调用 SparkTG API,并在每次请求中发送 SparkTG 用户名和密码。API 认证正在迁移到签名 API 令牌,同样的接口可在 /api/v2 使用。接口、参数和响应保持不变:对于大多数集成,只需更改基础 URL 和 Authorization 请求头。
为什么迁移到 v2
用户名 + 密码(v1)
API 令牌(v2)
发送的内容
用户名 + 密码(v1):每次请求都发送登录密码
API 令牌(v2):签名令牌;任何密码都不会离开您的管理员
如果泄露
用户名 + 密码(v1):在密码更改前一直有效,且同一密码可能还能登录控制台
API 令牌(v2):在 API Access Tokens 页面立即撤销该令牌;控制台登录不受影响
范围
用户名 + 密码(v1):该用户能访问的一切
API 令牌(v2):仅一个服务,固定在令牌中
有效期
用户名 + 密码(v1):永不过期
API 令牌(v2):一年后过期;生成新令牌即可轮换
谁可以创建
用户名 + 密码(v1):任何知道密码的人
API 令牌(v2):仅限服务管理员,并需通过一次性密码(OTP)验证
稳定性
用户名 + 密码(v1):有人更改密码后即失效
API 令牌(v2):不依赖任何登录密码
可追溯性
用户名 + 密码(v1):—
API 令牌(v2):每个请求都会记录到令牌所属的服务
生成 API 令牌
- 1在 SparkTG 控制台中打开 Admin → Settings → API Access Tokens。
- 2在 Generate a new token 下选择接收一次性密码的方式(SMS、WhatsApp 或 Email)并发送请求。
- 3输入 OTP,可选择添加标签(例如集成名称),然后生成令牌。
- 4复制令牌并妥善保存。令牌仅显示一次,有效期一年。
令牌由服务管理员生成。同一页面会列出您的令牌,并可撤销其中任意一个。令牌过期前,请生成新令牌并将集成切换过去。
有哪些变化
v1(现行)
v2
基础 URL
v1(现行):https://telephonycloud.co.in/api/v1
v2:https://telephonycloud.co.in/api/v2
认证
v1(现行):Authorization: Basic <username:password>
v2:Authorization: Bearer <YOUR_TOKEN>
服务 id(svc-id / service-id)
v1(现行):用于选择服务。
v2:可选。服务始终取自令牌。如果发送,必须与令牌的服务一致,否则返回 HTTP 403。
执行操作的坐席
v1(现行):取自您发送的参数。
v2:相同。如果未发送 agent-sip、agent-id 或 agent-number,操作将由生成令牌的管理员执行,因此请发送坐席的 agent-sip、agent-id 或 agent-number。
删除预约呼叫
v1(现行):GET 或 POST
v2:仅限 DELETE,参数放在查询字符串中
发送 WhatsApp 消息
v1(现行):以该用户的坐席身份发送
v2:可选的 agent-id 查询参数用于选择发送坐席
列出服务
v1(现行):该用户的所有服务
v2:仅令牌所属的服务
成功响应和各接口特有的错误与 v1 相同。每个 v2 请求都会被记录,用于 API 用量计费。
示例
用户名 + 密码(v1)
curl -u '<username>:<password>' \
'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'API 令牌(v2)
curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'将 <YOUR_TOKEN> 替换为您的 API 令牌
令牌错误
令牌会在接口执行前校验,因此任何 v2 请求都可能返回这些错误。
HTTP 401缺少 Authorization 请求头或格式错误,或令牌已过期。
{"status":"error","code":401,"message":"invalid or missing JWT"}HTTP 401令牌已在 API Access Tokens 页面被撤销。
{"status":"error","code":401,"message":"token revoked or unknown"}HTTP 403令牌所属的服务未激活。
{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}HTTP 403发送的 svc-id 或 service-id 参数与令牌的服务 id 不同。
{"status":"error","code":403,"message":"svc-id does not match token's service"}v2 接口
这些 API 现已在 v2 中提供。SparkTG 的其余 API 也将很快迁移到 v2。
发起呼叫(v2)
发起外呼或预约呼叫
点击呼叫(v2)
经 OTP 验证的回拨请求
删除预约呼叫(v2)
取消已预约的呼叫
批量创建预约呼叫(v2)
一次请求最多预约 500 个呼叫
发送 WhatsApp 消息(v2)
从您的服务发送消息
批量获取通话详情(v2)
某一时间段内的通话记录
登录 / 登出报告(v2)
坐席的登录和登出时间
列出坐席(v2)
令牌所属服务的全部坐席
更新坐席(v2)
登录、登出、休息和资料修改
获取有效休息状态 (v2)
坐席可用的休息状态,可选针对单个坐席
CDR 报表 (v2)
指定时间窗口内的通话详单
坐席绩效报表 (v2)
每位坐席的通话数量,以及通话、处理、保持和接起时长
登录 / 登出原始报表 (v2)
登录和休息时间线,每个状态段一行
登录 / 登出汇总报表 (v2)
每位坐席的空闲、通话、休息和登出时长
列出服务(v2)
令牌所属的服务
LeadSquared DID 列表(v2)
用于 LeadSquared 集成的 DID
