跳至主要内容

鉴权与签名

所有开放 API 请求需通过 HMAC-SHA256 签名进行身份验证。

签名算法​

项目说明
算法HMAC-SHA256
签名函数hash_hmac('sha256', payload, app_secret)
签名结果Hex 编码(小写)

Payload 规范​

  • payload 为原始 JSON 字符串
  • JSON 不进行排序
  • 不进行格式化(不 pretty print)
  • 不进行 urlencode
  • 推荐使用压缩后的单行 JSON
重要

JSON 字段顺序、空格、换行必须与签名时完全一致。签名放在请求头 x-chat-signature 中。

响应语言​

所有 /openapi/* 接口统一使用可选请求头 lang 控制面向调用方的响应文案和错误提示;create_gd / create_robot 也使用该语言生成欢迎语。由接口触发的内部 WebSocket 通知沿用同一语言。

语言只从 lang 请求头读取。JSON body 中的 lang 不属于接口契约,也不会改变响应文案或欢迎语。OpenAPI 响应语言独立于客服端界面语言和工作区默认语言,无需与客服端当前语言一致。

支持的标准值与小组件 JavaScript API 的语言配置一致,见语言配置。OpenAPI 仅接受标准值,不沿用 JSAPI 的浏览器语言探测和地区变体归一化逻辑。

  • 未传或传入非法值时默认:zh-cn
  • lang 不参与 HMAC 计算,签名仍基于未修改的原始 JSON body

代码示例​

PHP​

<?php
$payload =
'{"appid":"1b621280becdb0fa3d3e041ff69e1e1f","sbs":"1001","timestamp":1767772879,"ranstr":"4ad0faec14a58112","kefu_id":"10078","ip":""}';
$appSecret = 'YOUR_APP_SECRET';
$sign = hash_hmac('sha256', $payload, $appSecret);
echo $sign;

Python 3​

import hmac
import hashlib

payload = '{"appid":"1b621280becdb0fa3d3e041ff69e1e1f","sbs":"1001","timestamp":1767772879,"ranstr":"4ad0faec14a58112","kefu_id":"10078","ip":""}'
app_secret = 'YOUR_APP_SECRET'

sign = hmac.new(
app_secret.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()

print(sign)

Go​

package main

import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
)

func main() {
payload := `{"appid":"1b621280becdb0fa3d3e041ff69e1e1f","sbs":"1001","timestamp":1767772879,"ranstr":"4ad0faec14a58112","kefu_id":"10078","ip":""}`
appSecret := "YOUR_APP_SECRET"

mac := hmac.New(sha256.New, []byte(appSecret))
mac.Write([]byte(payload))
sign := hex.EncodeToString(mac.Sum(nil))

fmt.Println(sign)
}

Java (JDK 8+)​

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class SignExample {
public static void main(String[] args) throws Exception {
String payload = "{\"appid\":\"1b621280becdb0fa3d3e041ff69e1e1f\",\"sbs\":\"1001\",\"timestamp\":1767772879,\"ranstr\":\"4ad0faec14a58112\",\"kefu_id\":\"10078\",\"ip\":\"\"}";
String appSecret = "YOUR_APP_SECRET";

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(appSecret.getBytes("UTF-8"), "HmacSHA256"));
byte[] hash = mac.doFinal(payload.getBytes("UTF-8"));

StringBuilder sb = new StringBuilder();
for (byte b : hash) {
sb.append(String.format("%02x", b));
}
System.out.println(sb.toString());
}
}

Node.js​

const crypto = require('crypto')

const payload = '{"appid":"1b621280becdb0fa3d3e041ff69e1e1f","sbs":"1001","timestamp":1767772879,"ranstr":"4ad0faec14a58112","kefu_id":"10078","ip":""}'
const appSecret = 'YOUR_APP_SECRET'

const sign = crypto
.createHmac('sha256', appSecret)
.update(payload)
.digest('hex')

console.log(sign)