Large model application management

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.

API overview

After an intelligent voice AI call successfully initiates a transfer-to-manual-agent request, the system immediately pushes the complete conversation history between the AI and the user to the callback URL that the customer configured in advance by using HTTP POST. This lets the agent understand the conversation context before taking over the call. The agent might not yet be ringing or have answered the call.

Trigger conditions

The push is triggered only when both of the following conditions are met:

1. The transfer request is successfully initiated, rather than the agent having answered the call.

2. The callback address in the transfer configuration is not empty.

Request description

Request headers

Request body

conversationHistory array elements

Request body example

{
  "callId": "1693456789012^1693454989012",
  "outId": "biz-order-20260831001",
  "caller": "18612345678",
  "callee": "4006007006",
  "conversationHistory": [
    {
      "role": "assistant",
      "content": "Hello, how can I help you?"
    },
    {
      "role": "user",
      "content": "I want to check the status of my order."
    },
    {
      "role": "assistant",
      "content": "Sure. Please provide your order number."
    },
    {
      "role": "user",
      "content": "I want to speak to a manual agent."
    },
    {
      "role": "assistant",
      "content": "Sure. I am transferring you to a manual agent. Please wait."
    }
  ]
}
          

Request body example without outId

{
  "callId": "1693456789012^1693454989012",
  "caller": "18612345678",
  "callee": "4006007006",
  "conversationHistory": []
}
          

Response description

Response example (recommended format)

{
  "code": 0,
  "msg": "success"
}
          

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 )
          

Concatenate the three parameters directly without separators, then calculate the MD5 hash and output a 32-character lowercase hexadecimal string.

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);
}
          

curl examples

Complete request that includes the conversation history

curl -X POST 'https://your-server.com/dialog-push' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'timestamp: 1725091200000' \
  -H 'auth: a3f5b8c2d1e4f6a7b9c0d2e3f5a6b8c9' \
  -d '{
    "callId": "1693456789012^1693454989012",
    "outId": "biz-order-20260831001",
    "caller": "18612345678",
    "callee": "4006007006",
    "conversationHistory": [
      {
        "role": "assistant",
        "content": "Hello, how can I help you?"
      },
      {
        "role": "user",
        "content": "I want to check my order status."
      },
      {
        "role": "assistant",
        "content": "Sure. Please provide your order number."
      },
      {
        "role": "user",
        "content": "I want to speak to a manual agent."
      },
      {
        "role": "assistant",
        "content": "Sure. I am transferring you to a manual agent. Please wait."
      }
    ]
  }'
          

Request without a conversation history

curl -X POST 'https://your-server.com/dialog-push' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'timestamp: 1725091200000' \
  -H 'auth: e7d2a1b3c5f8e0d4a6b9c2f1e3d5a7b0' \
  -d '{
    "callId": "1693456789012^1693454989012",
    "caller": "18612345678",
    "callee": "4006007006",
    "conversationHistory": []
  }'
          

Expected response (HTTP 200)

{
  "code": 0,
  "msg": "success"
}
          

Retries and exception handling

Retry policy

Failure scenarios

Notes

1. Push timing: The push occurs after the transfer request is successfully initiated. The agent might not yet be ringing or have answered the call. If the agent ultimately does not answer because of a timeout or rejection, the conversation record is still pushed.

2. Response time: We recommend that you return HTTP 200 within 500 ms. A timeout triggers a retry.

3. Status code only: The system checks only whether the HTTP status code is 200 and does not parse the response body. You can return any content.

4. Reduced conversation record: The pushed conversation record contains only the role and content fields.

5. outId value: The pushed outId is the original value that the customer passed when calling the API.

6. Asynchronous push: The push is performed asynchronously and does not block the transfer process.

7. Callback URL: The URL must be a publicly accessible HTTPS address.

8. Signature algorithm: This interface uses the same MD5(aliyunUid + callId + timestamp) signature algorithm as the transfer variable callback interface.