Webhook sự kiện cuộc gọi

1. Thiết lập Webhook

Đối tác cần cung cấp cho Alohub các thông tin sau:

Thông tin	Mô tả
Webhook URL	URL nhận webhook (khuyến nghị HTTPS). Ví dụ: https://your-server.com/api/alohub/webhook
Method	POST
Authorization Key	Key xác thực — Alohub sẽ gửi trong header Authorization mỗi request
Content-Type	application/json

Cách đăng ký: Liên hệ đội ngũ kỹ thuật Alohub, cung cấp URL nhận webhook và key xác thực. Alohub sẽ cấu hình gửi sự kiện đến URL của bạn.

2. Payload mẫu

Mỗi khi cuộc gọi kết thúc, Alohub gửi POST request với body JSON sau:

{
  "call_id": "20240113150030xxxxxx",
  "call_status": "answered",
  "direction": "outbound",
  "caller_number": "03899xxx",
  "destination_number": "888",
  "starttime": "2024-01-13 15:00:30",
  "answertime": "2024-01-13 15:00:35",
  "endtime": "2024-01-13 15:05:30",
  "hangup_by": "customer",
  "hotline": "",
  "total_duration": "300",
  "holding_duration": "0",
  "recording_url": "https://domain:port/IPCCMedia/MP3Export.do?url=file.mp3&source=ipcc",
  "objectId": 1,
  "transactionID": "TRANSID_1111",
  "userName": "adminxxx",
  "eventType": "call"
}

3. Chi tiết các trường dữ liệu

Trường	Kiểu	Mô tả
call_id	string	Mã định danh duy nhất của cuộc gọi
call_status	string	Trạng thái cuộc gọi (xem bảng mã trạng thái bên dưới)
direction	string	Hướng cuộc gọi: inbound (gọi vào) / outbound (gọi ra)
caller_number	string	Số điện thoại bên gọi (khách hàng)
destination_number	string	Số extension tư vấn viên tiếp nhận
starttime	string	Thời điểm bắt đầu cuộc gọi (YYYY-MM-DD HH:mm:ss)
answertime	string	Thời điểm cuộc gọi được trả lời
endtime	string	Thời điểm kết thúc cuộc gọi
hangup_by	string	Bên ngắt máy: customer (khách hàng), agent (tổng đài viên), system (hệ thống)
hotline	string	Số hotline (đầu số tổng đài), rỗng nếu không có
total_duration	string	Tổng thời lượng cuộc gọi (giây)
holding_duration	string	Thời gian giữ máy — hold (giây)
recording_url	string	URL file ghi âm cuộc gọi (dùng để tải hoặc phát lại)
objectId	number	ID đối tượng liên quan (mặc định: 1)
transactionID	string	ID giao dịch (truyền khi gọi makeCall hoặc addCampaignCustomer)
userName	string	Tên tài khoản agent xử lý cuộc gọi
eventType	string	Loại sự kiện, mặc định "call"

4. Mã trạng thái cuộc gọi

Giá trị call_status trong payload webhook:

Mã trạng thái	Mô tả	Ghi chú
answered	Cuộc gọi đã được trả lời	Cuộc gọi thành công, có kết nối giữa 2 bên
noanswer	Không trả lời	Đổ chuông nhưng bên nhận không nhấc máy
busy	Máy bận	Bên nhận đang trong cuộc gọi khác hoặc từ chối
failed	Cuộc gọi thất bại	Lỗi kỹ thuật: số không tồn tại, lỗi mạng, hết tài nguyên
cancel	Cuộc gọi bị hủy	Agent hoặc hệ thống hủy trước khi kết nối

5. Xử lý Webhook phía đối tác

Respond nhanh: Endpoint nhận webhook nên trả về HTTP 200 trong vòng 5 giây. Nếu timeout hoặc lỗi, Alohub sẽ retry tối đa 3 lần với khoảng cách tăng dần.

Code mẫu xử lý webhook

const express = require('express')
const app = express()
app.use(express.json())

app.post('/api/alohub/webhook', (req, res) => {
  const { call_id, call_status, caller_number, direction, recording_url } = req.body

  console.log(`Cuộc gọi ${call_id}: ${call_status}`)
  console.log(`Hướng: ${direction}, SĐT: ${caller_number}`)

  if (recording_url) {
    console.log(`Ghi âm: ${recording_url}`)
  }

  // Xử lý logic nghiệp vụ tại đây
  // VD: cập nhật CRM, gửi notification, lưu DB...

  // Quan trọng: respond 200 ngay lập tức
  res.status(200).json({ received: true })
})

app.listen(3000)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/alohub/webhook', methods=['POST'])
def webhook():
    data = request.json

    call_id = data.get('call_id')
    call_status = data.get('call_status')
    caller_number = data.get('caller_number')
    recording_url = data.get('recording_url')

    print(f"Cuộc gọi {call_id}: {call_status}, SĐT: {caller_number}")

    if recording_url:
        print(f"Ghi âm: {recording_url}")

    # Xử lý logic nghiệp vụ tại đây

    return jsonify({"received": True}), 200

if __name__ == '__main__':
    app.run(port=3000)

6. Lưu ý quan trọng

Idempotency: Có thể nhận cùng 1 sự kiện nhiều lần (do retry). Dùng call_id làm key để kiểm tra trùng lặp trước khi xử lý.

Bảo mật: Verify header Authorization trong request webhook khớp với key bạn đã cung cấp cho Alohub. Reject request không hợp lệ.

Best practice: Nhận webhook → respond 200 ngay → đẩy vào queue (Redis, RabbitMQ...) → xử lý async. Tránh xử lý nặng trong handler webhook.