Frequently Asked Questions and Basic API (FAQ)

Common Troubleshooting Guide

Q: After the service starts, the admin console prompts that it cannot connect to the backend?

A: This is usually caused by incorrect configuration of Cross-Origin Resource Sharing (CORS) for frontend-backend communication or the WebSocket address. Please follow these steps to troubleshoot:

1. Check if the port mappings (default 5173 / 3000) assigned to the Admin UI and AppServer in docker-compose.community.yml are running normally.
2. Ensure that the backend address URL in the configuration file .env is an externally resolvable IP, not a virtual domain name, e.g., VITE_API_BASE_URL=http://<Your_IP>:3000/api/v1.
3. Refer to the "Connection Troubleshooting Chapter" and try again.

Q: Why don't I see real-time call cards popping up on the management interface?

A:

• First, confirm whether the "Master Console Connection Status (WebSocket)" in the lower left corner is steadily green.
• Check if the underlying collection engine (IE container) has received SIP/HEP signaling sent from the source PBX (like Asterisk / FreeSWITCH). Run the following command to see if there are parsing logs rolling:

  docker-compose logs -f ie

• If there are no logs, please investigate whether the upstream switch has routed packets to the specific ports of the IE server (default UDP 9060 / UDP 5060).

Q: Is it supported to deploy the system from a Windows host machine?

A: Technically, we support running this system through WSL2 and Docker Desktop. However, we strongly recommend avoiding deploying production environments on Windows, especially for software involving high-frequency, multi-channel UDP/RTP communications. The Linux (Rocky / Ubuntu) kernel network stack can provide exponentially superior performance and stability guarantees.

---

Open Basic API Reference

The system provides a set of basic RESTful APIs for integration developers (This system is in a state of continuous evolution, and detailed input parameters and callback models may vary slightly depending on the version). To use the API, please include your administrator or API Token in the request header: Authorization: Bearer <Token>.

1. Liveness Probe and Health Check

GET /api/v1/health

• Purpose: Returns the heartbeat survival metrics of the system's basic microservice set and the latency of dependent libraries.

2. Get Real-time Active Call Set

GET /api/v1/calls/active

• Purpose: Obtains a JSON data table and summary information of calls currently in an active state (establishing/ringing/in-call) across the entire system.

3. Get Agent Metrics Dashboard Card Statistics (Example)

GET /api/v1/metrics/agents

• Purpose: Queries macro agent metrics for today, such as those currently queuing, being answered, or experiencing alarm events.