tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
实时音视频
    文档
    Download PDF

    REST API 简介

    最后更新时间：2024-04-18 16:34:40
    下载PDF
      REST API 是音视频通话 Call （TUICallKit）的后台 HTTP 管理接口，可以为开发者提供一套简单的管理入口。目前音视频通话 Call（TUICallKit）支持的 REST API 请参见 REST API 接口列表。
      为了安全性，REST API 仅提供 HTTPS 接口。

      使用条件

      REST API 目前处于内测期，内测期间开通了音视频通话 Call（TUICallKit）群组通话版的应用（SDKAppId）可以使用 REST API，您也可以开通体验版免费试用，版本说明及开通指引参见 音视频通话能力版本。
      目前各平台仅在特定版本的 TUICallKit 可使用 REST API，详见下表：
      平台/框架
      版本号
      Android/iOS/Flutter/uni-app（客户端）
      ≥ 1.7.1
      Web
      ≥ 1.4.6
      微信小程序
      ≥ 1.5.1
      注意：
      参与通话的所有平台/框架升级到上述新的版本后，才可在控制台上查看到对应的通话信息。
      内测期 REST API 支持查询近7天数据。

      REST API 接口列表

      功能说明
      接口
      通过 callId 获取记录
      通过条件获取记录

      调用方法

      请求 URL

      REST API 的 URL 格式如下：
      https://xxxxxx/$version/$kind/$command?sdkappid=$SDKAppID&identifier=$identifier&usersig=$usersig&random=99999999&contenttype=json
      其中各个参数的含义以及取值如下（参数名称及其取值均区分大小写）：
      参数
      含义
      取值
      https
      请求协议
      请求协议为 HTTPS，请求方式为 POST
      xxxxxx
      专属域名
      中国 callkit.trtc.tencent-cloud.com
      version
      协议版本号
      固定为 v1
      kind
      管理分类
      示列：
      v1/records/get_record_by_callId，其中 records 为 kind
      command
      命令字，与 kind 组合用来表示具体的业务功能
      示列： v1/records/get_record_by_callId，其中 get_record_by_callId 为 command
      sdkappid
      在控制台获取的应用标识
      在申请接入时获得
      identifier
      用户名，调用 REST API 时必须为 App 管理员账号
      使用 IM 的管理员账号
      usersig
      用户名对应的密码
      参见 生成 UserSig
      random
      标识当前请求的随机数参数
      32位无符号整数随机数，取值范围 0 - 4294967295
      contenttype
      请求格式
      固定值为 json
      注意：
      领取或购买套餐包后会在 IM 账号系统中创建 administrator 管理员账号，在请求中的identifier参数中请使用 administrator，如果您在 IM 账号管理 中取消或删除管理员，请正确指定管理员账号以及对应的 userSig。
      App 可以在每次调用 REST API 时都生成管理员账号的 UserSig，亦可生成一个固定的 UserSig 重复使用，但需特别注意 UserSig 的有效期。
      在创建房间以及进入房间等操作时，系统会在 IM 系统中自动导入 IM 账号，敬请知悉。

      HTTP 请求包体格式

      REST API 仅支持 POST 方法，其请求包体为 JSON 格式，具体的包体格式参见每个 API 的详细描述。
      注意：
      POST 包体不能为空，即使某条协议包体中不用携带任何信息，也必须要携带一个空的 JSON 对象，即{}。

      HTTP 返回码

      除非发生网络错误（例如502错误），否则 REST API 的调用结果均为200，实际 API 调用的错误码与错误信息在 HTTP 应答包体中返回。

      HTTP 应答包体格式

      REST API 的应答包体也是 JSON 格式，其格式符合如下特征：
      {
          "errorCode": 0, 
          "errorMessage": "Success",
          "requestId": "1c8960ac38d61be38b6fb219db0182d1", 
          "data": {} 
      }
      应答包体中必然包含 errorCode、errorMessage、requestId 这三个属性，其含义如下：
      字段
      类型
      说明
      errorCode
      String
      错误码，0为成功，其余为失败
      errorMessage
      String
      错误信息
      requestId
      Integer
      请求唯一标识符

      调用示例

      以下为通过 REST API 获取指定 callId 的通话记录示例。
      HTTPS 请求：
      POST /records/get_record_by_callId?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json HTTP/2
      Host: callkit.trtc.tencent-cloud.com
      Content-Length: 36
      {
          "callId": "2ae7d549-c441-4a9b-87c0-61810fe19582"
      }
      HTTPS 应答：
      HTTP/2 200 OK
      Date: Fri, 21 Apr 2023 06:06:16 GMT
      Content-Length: 112
      Connection: keep-alive
      
      {
          "errorCode": 0,
          "errorMessage": "Success",
          "requestId": "9f01db503f2006ad10c45f4f4609e38d",
          "data": {
              "callId": "2ae7d549-c441-4a9b-87c0-61810fe19582",
              "sdkAppId": 88888888,
              "mediaType": "video",
              "roomId": "123456",
              "startCallTs": 1688705638,
              "acceptTs": 1688705641,
              "endTs": 1688705668,
              "caller": "alice",
              "totalUserNumber": 2,
              "callType": "single", 
              "callResult": "normal_end", 
              "callees": [
                  "bob1",
                  "bob2"
              ]
          }
      }

      REST API 公共错误码

      错误码
      含义说明
      0
      请求成功
      50001
      当前应用需要购买 TUICallKit 群组通话版套餐包方可使用
      70001
      请求参数无效，请检查必填参数是否缺失或填错
      70002
      UserSig 无效
      70003
      UserSig 过期
      70004
      请求用户非超级管理员
      70005
      请求被限频
      70009
      解析请求 body 出错，请检查请求参数类型是否正确
      未知错误码
      系统内部错误，请 提交工单 联系技术人员

      常见问题

      REST API 请求有概率超时，收不到任何响应？

      您可以从以下几个方面确认：
      1. 后台 REST 接口设置的超时时间是 3s，调用方设置的超时时间应该长于 3s。
      2. telnet callkit.trtc.tencent-cloud.com 443 确认能否连接服务端口。
      3. 使用 curl -I https://callkit.trtc.tencent-cloud.com 简单测试看状态码是否为200。
      4. 确认机器的 dns server 配置是内网 dns server，还是公共 dns server。如果是内网 dns server，请确保 dns server 网络出口和本机器网络出口 IP 所在地域运营商一致。
      5. 建议业务调用方使用长连接+连接池模式。
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款