Authentication and Signature
All Open API requests must be authenticated with an HMAC-SHA256 signature.
Signature Algorithm
| Item | Value |
|---|---|
| Algorithm | HMAC-SHA256 |
| Signature Function | hash_hmac('sha256', payload, app_secret) |
| Signature Output | Lower-case hex string |
Payload Rules
- The payload is the raw JSON string
- JSON keys must not be re-sorted
- JSON must not be pretty-printed
- The payload must not be URL-encoded
- A compact one-line JSON body is recommended
JSON field order, spaces, and line breaks must match exactly between signing and the request body. Send the signature in the x-chat-signature header.
Response Language
All /openapi/* endpoints use the optional lang request header for user-facing response text and error messages. create_gd / create_robot also use this language for generated welcome content. Internal WebSocket notifications triggered by these requests use the same language.
The language is read only from the lang header. A lang field in the JSON body is not part of the contract and does not affect response text or generated welcome content. OpenAPI response language is independent of the agent console UI language and the workspace default language; it does not have to match the agent's current language.
The supported standard values are the same as the Widget JavaScript API language set. See Language Configuration. OpenAPI accepts the standard values only; it does not apply JSAPI browser-language detection or regional-variant normalization.
- Default when the header is omitted or invalid:
zh-cn langis not part of the HMAC payload; the signature is still calculated from the unchanged raw JSON body
Code Examples
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);