Skip to main content

Authentication and Signature

All Open API requests must be authenticated with an HMAC-SHA256 signature.

Signature Algorithm​

ItemValue
AlgorithmHMAC-SHA256
Signature Functionhash_hmac('sha256', payload, app_secret)
Signature OutputLower-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
warning

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
  • lang is 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);