API reference for transfer variable callbacks

1. API overview

When the variable assignment mode of the transfer configuration is callback mode (CALLBACK), the system initiates an HTTP POST request to the customer-configured callbackUrl before the transfer to retrieve transfer variables, such as the called number and skill group ID. Implement the callback service as described in this document.

2. Request description

2.1 Request headers

2.2 Request body

Request body example:

{
  "callId": "100025530001^105980150002",
  "outId": "biz-order-20260831001",
  "caller": "18612345678",
  "callee": "4006007006"
}
          

Request body example without outId:

{
  "callId": "100025530001^105980150002",
  "caller": "18612345678",
  "callee": "4006007006"
}
          

3. Response description

3.1 Response requirements

• The HTTP status code must be 200.

• The response body must not be empty and must be in JSON format.

3.2 Response body

3.3 Variable value constraints

3.4 Response examples

Allow transfer:

{
  "canTransfer": true,
  "calledNumber": "057188889999",
  "transferType": "SKILL_GROUP",
  "transferBizId": "9000",
  "customerId": "C20260831"
}
          

In this response, calledNumber, transferType, transferBizId, and customerId are injected as transfer variables. You can reference them in SIP Headers or a called-number template by using ${calledNumber}, ${transferType}, and similar placeholders.

Reject transfer:

{
  "canTransfer": false
}
          

4. Authentication signature

The system passes timestamp and auth in HTTP headers. Use the following algorithm to verify that the request source is valid.

Signature algorithm:

auth = MD5Hex( aliyunUid + callId + timestamp )
          

Java verification example:

import org.apache.commons.codec.digest.DigestUtils;

public boolean verifyAuth(String auth, Long aliyunUid, String callId, String timestamp) {
    String expected = DigestUtils.md5Hex(String.valueOf(aliyunUid) + callId + timestamp);
    return expected.equals(auth);
}
          

5. curl examples

5.1 Request that includes outId

curl -X POST 'https://your-callback-server.com/transfer/variables' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'timestamp: 1725091200000' \
  -H 'auth: a3f5b8c2d1e4f6a7b9c0d2e3f5a6b8c9' \
  -d '{
    "callId": "100025530001^105980150002",
    "outId": "biz-order-20260831001",
    "caller": "18612345678",
    "callee": "4006007006"
  }'
          

5.2 Request that does not include outId

curl -X POST 'https://your-callback-server.com/transfer/variables' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'timestamp: 1725091200000' \
  -H 'auth: e7d2a1b3c5f8e0d4a6b9c2f1e3d5a7b0' \
  -d '{
    "callId": "100025530001^105980150002",
    "caller": "18612345678",
    "callee": "4006007006"
  }'
          

5.3 Expected responses

Allow transfer (HTTP 200):

{
  "canTransfer": true,
  "calledNumber": "057188889999",
  "transferType": "SKILL_GROUP",
  "transferBizId": "9000"
}
          

Reject transfer (HTTP 200):

{
  "canTransfer": false
}
          

6. Exception handling

The system treats the following conditions as callback failures and rejects the transfer. The AI continues the conversation with the customer.

7. Notes

1. Response time: Return from the callback service within 500 ms whenever possible. A timeout causes the transfer to fail.

2. Idempotence: The same call can trigger multiple callbacks because of retries or other reasons. We recommend that the server implement idempotence.

3. canTransfer type: This field must be a native JSON Boolean (true or false). String values are not accepted.

4. Variable names: Variable names must match the ${variable} placeholders in the SIP Headers and called-number templates of the transfer configuration.

5. Network Security: The callback URL cannot point to an internal network address unless the address is included in a whitelist. Otherwise, SSRF protection blocks the request.