Giới thiệu OnePOS API
Tài liệu tích hợp hệ thống VoIP & Call Center toàn diện
OnePOS cung cấp bộ REST API đầy đủ cho phép tích hợp hệ thống tổng đài, quản lý cuộc gọi, chiến dịch và khách hàng vào phần mềm của bạn. Tất cả API đều trả về JSON và xác thực qua Bearer Token.
REST API
JSON over HTTPS
Webhook
Real-time events
WebSDK
Browser calling
https://test.voip247.vn/api/v3
để test. Môi trường production yêu cầu HTTPS và API Key hợp lệ.
Xác thực (Authentication)
Dùng API Key để lấy Access Token. Token có hiệu lực 24 giờ.
/api/v3/auth/login
Gửi api_key để nhận
access_token dùng cho các request tiếp theo.
Request
curl -X POST \
https://test.voip247.vn/api/v3/auth/login \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY"
}'Response 200
{
"status": true,
"data": {
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 86400
}
}Authorization: Bearer {access_token} cho tất cả các request tiếp theo.
WebSDK Integration
Tích hợp nghe và gọi điện trực tiếp vào phần mềm qua trình duyệt.
domain
voip247.vn
username
ext_101
password
••••••••
// 1. Nhúng WebSDK vào trang web của bạn
<script src="https://voip247.vn/sdk/websdk.js"></script>
// 2. Khởi tạo SDK
const sdk = new VoIP247SDK({
domain: "voip247.vn",
username: "ext_101",
password: "your_password",
onCallIncoming: (call) => console.log("Cuộc gọi đến:", call),
onCallAnswered: (info) => console.log("Đã nghe máy:", info),
onCallEnded: (info) => console.log("Kết thúc:", info),
});
sdk.connect(); // Kết nối WebSocket
sdk.call("0901234567"); // Gọi ra ngoàiWebhook / Event Hook
Nhận dữ liệu cuộc gọi theo thời gian thực qua HTTP POST đến URL của bạn.
Các sự kiện hỗ trợ
call.ringing
Cuộc gọi đổ chuông
call.answered
Cuộc gọi được nghe máy
call.ended
Cuộc gọi kết thúc
call.missed
Cuộc gọi nhỡ
Payload mẫu (call.ended)
{
"event": "call.ended",
"call_id": "voip247-abc123",
"caller": "0901234567",
"callee": "ext_101",
"direction": "inbound",
"duration": 145,
"status": "answered",
"recording_url": "https://voip247.vn/rec/...",
"timestamp": "2025-03-26T14:32:00+07:00"
}Cấu hình Webhook URL
curl -X POST \
https://test.voip247.vn/api/v3/webhook/config \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/hook",
"events": ["call.ended","call.missed"],
"secret": "your_secret_key"
}'CDR – Lịch sử cuộc gọi
Lấy lịch sử chi tiết cuộc gọi theo khoảng thời gian hoặc bộ lọc.
/api/v3/cdr
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
start_date |
string | Có | Từ ngày – format: YYYY-MM-DD |
end_date |
string | Có | Đến ngày – format: YYYY-MM-DD |
direction |
string | Không | inbound | outbound | internal |
status |
string | Không | answered | missed | busy |
extension |
string | Không | Lọc theo số máy nhánh |
page |
number | Không | Trang (mặc định: 1) |
limit |
number | Không | Số bản ghi / trang (max: 100) |
Request
curl "https://test.voip247.vn/api/v3/cdr\
?start_date=2025-03-01\
&end_date=2025-03-26\
&direction=inbound\
&limit=20" \
-H "Authorization: Bearer {token}"Response 200
{
"status": true,
"total": 245,
"page": 1,
"data": [{
"call_id": "voip247-001",
"caller": "0901234567",
"callee": "ext_101",
"duration": 120,
"status": "answered",
"recording": "https://..."
}]
}Autocall API
Khởi tạo cuộc gọi tự động ra danh sách số điện thoại.
Body – POST /api/v3/autocall/create
{
"campaign_id": "camp_001",
"phones": ["0901234567", "0912345678"],
"template_id": "tpl_greet_01",
"schedule_at": "2025-03-27T09:00:00+07:00",
"retry_times": 2,
"retry_interval": 300
}Campaign API
Tạo và quản lý chiến dịch gọi điện tự động.
Lead Management
Thêm và quản lý danh sách lead trong chiến dịch.
Body – POST /api/v3/campaign/{literal}{id}{/literal}/leads/bulk
{
"leads": [
{ "phone": "0901234567", "name": "Nguyễn Văn A", "custom_1": "HCM" },
{ "phone": "0912345678", "name": "Trần Thị B", "custom_1": "HN" }
]
}User Management
Quản lý người dùng (extension) trong hệ thống tổng đài.
Group Management
Quản lý nhóm (queue / ring group) trong tổng đài.
Monitor Stats
Theo dõi trạng thái cuộc gọi và agent theo thời gian thực.
Report API
Xuất báo cáo thống kê theo khoảng thời gian và nhiều tiêu chí.
Cần hỗ trợ tích hợp?
Đội ngũ kỹ thuật OnePOS / VoIP247 sẵn sàng hỗ trợ trong giờ hành chính (8:00 – 17:30, T2 – T6).