Callback Agen - Intelligent Media Services - Alibaba Cloud Documentation Center

Gunakan callback agen untuk secara otomatis memicu aksi atau respons yang telah ditentukan dalam aplikasi Anda ketika event tertentu terjadi.

Ikhtisar

Ketika agen AI memicu event tertentu selama waktu proses, Alibaba Cloud mengirim permintaan callback ke server Anda. Anda kemudian dapat menambahkan logika bisnis untuk memproses permintaan tersebut.

Konfigurasi callback agen

Masuk ke Konsol Intelligent Media Service. Pilih agen yang ingin Anda konfigurasi, lalu klik Manage di kolom Actions.
Pada tab Callback Configuration, aktifkan callback agen, pilih jenis callback, lalu masukkan Callback URL dan Authentication Token opsional.

Catatan
Token ini dikirim dalam bidang Authorization pada header permintaan. Server Anda harus memverifikasi token ini untuk memastikan keamanan permintaan.

Jenis callback yang tersedia meliputi: Agent status callbacks, Workflow status callbacks, Real-time chat history callbacks, Hang-up intent detection callbacks, Outbound call status callbacks, Inbound call status callbacks, Custom client message callbacks, dan Instruction callbacks. Jika Callback URL Anda mendukung HTTP dan HTTPS, disarankan menggunakan HTTPS demi keamanan yang lebih baik.
Klik OK untuk menyelesaikan konfigurasi callback.

Bidang muatan callback

Parameter	Tipe	Wajib	Deskripsi	Contoh
aiAgentId	String	Ya	ID agen.	xxxxx
instanceId	String	Ya	ID unik instans agen.	39f8e0bc005e4f309379701645f4****
event	String	Ya	Jenis event. Status callback agen: agent_start: Dipicu saat tugas agen dimulai. session_start: Dipicu saat sesi panggilan terbentuk. agent_stop: Dipicu saat tugas agen berhenti. error: Dipicu saat terjadi error. Callback status alur kerja: intent_detected: Dipicu saat agen mulai mendeteksi maksud pengguna. intent_recognized: Dipicu saat agen mengenali maksud pengguna yang lebih lengkap. llm_data_received: Dipicu saat data respons diterima dari model bahasa besar (LLM). Untuk respons berupa aliran, event ini dipicu saat menerima paket data pertama. tts_data_received: Dipicu saat data respons diterima dari layanan Text-to-Speech (TTS). Untuk respons berupa aliran, event ini dipicu saat menerima paket data pertama. Callback catatan percakapan real-time: chat_record: Menyediakan transkrip percakapan secara real-time. Callback rekaman audio: audio_record: Audio pengguna (role="user"): Dipicu saat agen mengenali maksud pengguna yang lebih lengkap. Muatan berisi data audio pengguna dan hasil speech-to-text (STT) yang sesuai. Audio agen (role="agent"): Dipicu saat agen selesai memutar audio atau saat pengguna menginterupsi. Muatan berisi data audio agen dan teks yang sesuai. full_audio_record: Dipicu setelah panggilan berakhir jika perekaman panggilan lengkap diaktifkan. Muatan berisi tautan ke file audio lengkap dengan saluran campuran. Callback status panggilan: outbound_call: Dipicu untuk perubahan status atau event hang-up pada panggilan arah keluar. inbound_call: Dipicu untuk perubahan status atau event hang-up pada panggilan arah masuk. Callback untuk pesan kustom dari klien: client_defined_data: Callback untuk pesan kustom yang dikirim oleh klien. Disarankan untuk menyertakan identifikasi guna membedakan awal dan akhir pesan. Callback instruksi aksi agen: instruction: Berisi instruksi aksi untuk dieksekusi oleh agen.	agent_start
data	Json	Tidak	Muatan data. Struktur bidang ini bergantung pada jenis event.	chat_record Catatan percakapan pesan teks: { 'requestId': 'abcd', 'code': 'Success', 'message': 'Success', 'dialogues': [ { 'roundId': 'xxxxxxx', 'producer': 'agent', 'text': '1+1=2', 'reasoningText': 'The user is asking what 1+1 is. It seems simple, but I need to think carefully.', 'time': 1739445458025, 'source': 'chat', 'dialogueId': 'xxxxxxxxxx', 'type': 'normal' }, { 'roundId': 'xxxxxxxxxxx', 'producer': 'user', 'text': 'Just answer, what is 1+1?', 'time': 1739445436218, 'source': 'chat', 'dialogueId': 'xxxxxxxxxxx', 'type': 'normal' } ] } `{ 'role': 'user', 'type': 'normal', 'text': 'Tell me a long story.', 'sentence_id': 1 }` audio_record `{ 'role': 'user', 'sentence_id': 1, 'start_timestamp': 1743151532.33012, 'text': 'Tell me a long story.', 'audio_url': '<file oss address>' }` full_audio_record `{ 'audio_url': '<file oss address>', 'start_timestamp': '2025-11-06T09:33:48.776253+00:00', 'end_timestamp': '2025-11-06T09:34:34.550809+00:00' }`
code	String	Ya	Kode status event callback.	1001
message	String	Ya	Pesan callback.	User has been kicked from the room
timestamp	String	Ya	Waktu terjadinya event, diformat sebagai string ISO 8601 (UTC).	2023-10-01T12:00:00Z
userData	String	Tidak	Informasi yang ditentukan pengguna.
extendData	Json	Tidak	Data ekstensi kustom.

Contoh callback

Status panggilan arah keluar

Ketika event bernilai outbound_call, callback ini melaporkan status panggilan arah keluar. Tabel berikut menjelaskan bidang dalam objek extendData untuk event ini.

Parameter	Tipe	Deskripsi
aiAgentId	String	ID agen AI.
channelId	String	ID saluran.
instanceId	String	ID unik instans agen AI.
callerNumber	String	Nomor telepon pemanggil (agen AI).
calleeNumber	String	Nomor telepon penerima panggilan.
failReason	Int	Alasan kegagalan. Bidang ini hanya dikembalikan jika panggilan arah keluar gagal.
status	Int	Status panggilan saat ini dari agen AI. Nilai yang mungkin adalah: `2`: Panggilan arah keluar atau transfer panggilan gagal. `3`: Panggilan arah keluar atau transfer panggilan berhasil tersambung. `4`: Panggilan diakhiri (hang up).
callStartTime	String	Waktu panggilan tersambung. Bidang ini hanya dikembalikan saat hang up.
callEndTime	String	Waktu panggilan diakhiri. Bidang ini hanya dikembalikan saat hang up.
hangupRole	Int	Pihak yang mengakhiri panggilan. Bidang ini hanya dikembalikan saat hang up. Nilai yang mungkin adalah: `0`: Pemanggil (agen AI). `1`: Penerima panggilan. `2`: Pihak yang menerima panggilan yang ditransfer.
forwardInfo	JSON	Informasi tentang transfer panggilan. Bidang ini hanya dikembalikan untuk callback terkait transfer panggilan. Berisi sub-bidang berikut: `callerNumber`: Nomor telepon pihak yang memulai transfer. Tipe data: String. `calleeNumber`: Nomor telepon pihak yang menerima transfer. Tipe data: String. `callStartTime`: Waktu panggilan yang ditransfer tersambung. Tipe data: String. Bidang ini hanya dikembalikan jika transfer berhasil atau terjadi hang up.

Kegagalan panggilan arah keluar

Callback ini menunjukkan bahwa panggilan arah keluar gagal karena nomor penerima tidak valid, panggilan ditolak, atau penerima tidak dapat dihubungi.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10002,
  "message":"Dial status failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": -6,
      "status": 2
  }
}

Panggilan arah keluar tersambung

Callback ini dikirim saat penerima menjawab panggilan arah keluar.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10003,
  "message":"Dial status connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3
  }
}

Penerima mengakhiri panggilan

Callback ini dikirim saat penerima mengakhiri panggilan setelah panggilan arah keluar tersambung.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 1
  }
}

Agen mengakhiri panggilan

Callback ini dikirim saat agen AI mengakhiri panggilan setelah panggilan arah keluar tersambung.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 0
  }
}

Transfer panggilan berhasil

Callback ini dikirim saat transfer panggilan berhasil tersambung.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10006,
  "message":"Forward call connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

Transfer panggilan gagal

Callback ini dikirim saat transfer panggilan gagal.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10005,
  "message":"Forward call failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": 480,
      "status": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX"
      }
  }
}

Mengakhiri panggilan setelah transfer

Callback ini dikirim saat pihak yang menerima transfer mengakhiri panggilan.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

Status panggilan arah masuk

Ketika event bernilai inbound_call, callback ini melaporkan status panggilan arah masuk. Tabel berikut menjelaskan bidang dalam objek extendData untuk event ini.

Parameter	Tipe	Deskripsi
aiAgentId	String	Nilai ini sama dengan bidang `aiAgentId` tingkat atas dalam callback.
channelId	String	ID saluran.
instanceId	String	Nilai ini sama dengan bidang `instanceId` tingkat atas dalam callback.
callerNumber	String	Nomor telepon pemanggil (pihak yang melakukan panggilan arah masuk).
calleeNumber	String	Nomor telepon penerima (agen AI).
failReason	Int	Alasan kegagalan. Bidang ini hanya dikembalikan jika panggilan arah masuk gagal.
status	Int	Status panggilan saat ini dari agen AI. Nilai yang mungkin adalah: `2`: Panggilan arah masuk atau transfer panggilan gagal. `3`: Panggilan arah masuk atau transfer panggilan berhasil tersambung. `4`: Panggilan diakhiri (hang up).
callStartTime	String	Waktu panggilan tersambung. Bidang ini hanya dikembalikan saat hang up.
callEndTime	String	Waktu panggilan diakhiri. Bidang ini hanya dikembalikan saat hang up.
hangupRole	Int	Pihak yang mengakhiri panggilan. Bidang ini hanya dikembalikan saat hang up. Nilai yang mungkin adalah: `0`: Penerima (agen AI). `1`: Pemanggil (pihak yang melakukan panggilan arah masuk). `2`: Pihak yang menerima panggilan yang ditransfer.
forwardInfo	JSON	Informasi tentang transfer panggilan. Bidang ini hanya dikembalikan untuk callback terkait transfer panggilan. Berisi sub-bidang berikut: `callerNumber`: Nomor telepon pihak yang memulai transfer. Tipe data: String. `calleeNumber`: Nomor telepon pihak yang menerima transfer. Tipe data: String. `callStartTime`: Waktu panggilan yang ditransfer tersambung. Tipe data: String. Bidang ini hanya dikembalikan jika transfer berhasil atau terjadi hang up.

Panggilan arah masuk tersambung

Callback ini dikirim saat agen AI berhasil menjawab panggilan arah masuk.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10003,
  "message":"Dial status connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3
  }
}

Panggilan arah masuk gagal

Callback ini dikirim saat agen AI gagal menjawab panggilan arah masuk.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10002,
  "message":"Dial status failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": -6,
      "status": 2
  }
}

Mengakhiri panggilan arah masuk

Callback ini dikirim saat agen AI mengakhiri panggilan setelah panggilan arah masuk tersambung.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 0
  }
}

Transfer panggilan berhasil

Callback ini dikirim saat transfer panggilan dari panggilan arah masuk berhasil tersambung.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10006,
  "message":"Forward call connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

Transfer panggilan gagal

Callback ini dikirim saat transfer panggilan dari panggilan arah masuk gagal.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10005,
  "message":"Forward call failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": 480,
      "status": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX"
      }
  }
}

Mengakhiri panggilan setelah transfer

Callback ini dikirim saat pihak yang menerima transfer mengakhiri panggilan setelah transfer dari panggilan arah masuk.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

Status alur kerja

Untuk event status alur kerja, objek extendData berisi bidang-bidang berikut:

Parameter	Tipe	Deskripsi
channelId	String	ID saluran.
sentenceId	Int	ID unik untuk satu giliran percakapan. Catatan Respons agen AI terhadap satu kueri pengguna memiliki `sentenceId` yang sama.
requestTimestamp	String	Untuk event llm_data_received, ini adalah timestamp saat permintaan dikirim ke LLM. Untuk event tts_data_received, ini adalah timestamp saat permintaan dikirim ke layanan TTS. Untuk event intent_recognized, ini adalah timestamp saat agen AI mendeteksi akhir ucapan pengguna. Jika agen belum menentukan akhir ucapan, nilai ini adalah `None`.
responseTimestamp	String	Untuk event llm_data_received, ini adalah timestamp respons pertama dari LLM. Untuk event tts_data_received, ini adalah timestamp respons pertama dari layanan TTS. Untuk event intent_recognized, ini adalah timestamp saat hasil ASR dikembalikan setelah pengguna selesai berbicara.

Callback instruksi

Ketika jenis event adalah instruction, callback ini menunjukkan bahwa tag instruksi aksi tertentu telah dipicu. Callback instruksi yang didukung meliputi:

Callback instruksi transfer panggilan

Callback ini dikirim saat agen AI memicu tag aksi transfer panggilan.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"instruction",
  "code":11001,
  "message":"Forward call triggered",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "triggerTime": "2023-10-01T12:00:00Z"
  }
}

Contoh server

Python

from aiohttp import web
import json
from loguru import logger
async def handle_post(request):
    """
    Handle POST requests and log the received data.
    """
    # Get the Authorization header from the request.
    authorization_header = request.headers.get('Authorization')
    if authorization_header is None or not authorization_header.startswith('Bearer fixed-token'):
        logger.error("Unauthorized request")
        return web.Response(status=401, text='Unauthorized')
    try:
        # Parse the request body as JSON.
        callback_data = await request.json()
        logger.info("Parsed JSON data:")
        logger.info(json.dumps(callback_data, indent=4))
        return web.Response(text='Callback received successfully', status=200)
    except json.JSONDecodeError:
        # Return an error if JSON parsing fails.
        return web.Response(text='Invalid JSON', status=400)
app = web.Application()
app.add_routes([web.post('/', handle_post)])
if __name__ == '__main__':
    web.run_app(app, host='localhost', port=8081)

Kode status event callback

Kode status	Callback event	Deskripsi
1001	Agent starts	Agen dimulai.
1002	Agent stops	Agen dihentikan.
1003	Session starts	Sesi dimulai.
4001	Concurrent agent routes exhausted	Jumlah maksimum entri rute agen konkuren telah tercapai.
4002	Agent kicked from channel	Sistem mengeluarkan agen dari saluran.
4003	Invalid agent token	Token agen tidak valid.
4004	Agent stream subscription failed	Agen gagal berlangganan ke aliran.
4005	Third-party ASR failed	Layanan ASR pihak ketiga gagal.
4006	Avatar service unavailable	Layanan avatar tidak tersedia.
8001	Intent recognized	Maksud dikenali.
8002	LLM data received	Data LLM diterima.
8003	TTS data received	Data TTS diterima.
10002	Dial status failed	Panggilan gagal tersambung.
10003	Dial status connected	Panggilan berhasil tersambung.
10004	Hangup	Panggilan diakhiri.
10005	Forward call failed	Upaya penerusan panggilan gagal.
10006	Forward call connected	Panggilan yang diteruskan berhasil tersambung.
11001	Forward call triggered	Sistem memicu penerusan panggilan.