112 lines
4.7 KiB
Markdown
112 lines
4.7 KiB
Markdown
# EAMCO VoIP.ms Controller
|
|
|
|
The **EAMCO VoIP.ms Controller** is a simple but powerful microservice for dynamically managing call routing for a business phone line hosted with VoIP.ms. It provides a clean, secure API to change where incoming calls are directed, allowing for easy switching between an office phone system and on-call cell phones.
|
|
|
|
This service abstracts away the complexities of the VoIP.ms API, providing a task-oriented interface for day-to-day phone management.
|
|
|
|
[](https://www.python.org/)
|
|
[](https://fastapi.tiangolo.com/)
|
|
[](https://voip.ms/)
|
|
|
|
---
|
|
|
|
## Use Case
|
|
|
|
This service is designed to solve a common business problem: "Where should our main phone number ring?"
|
|
|
|
- **During business hours**, calls should go to the main office SIP account (the VoIP phones on desks).
|
|
- **After hours or on weekends**, calls should be forwarded to an on-call employee's cell phone.
|
|
- **If the primary on-call person is unavailable**, calls should be routed to a secondary backup number.
|
|
|
|
This API allows for these changes to be made with a single, simple API call, which can be triggered from a script, a web dashboard, or even a physical button (like an IoT dash button).
|
|
|
|
## Core Features
|
|
|
|
- **Dynamic Call Routing**: Instantly change the routing for a configured DID (phone number).
|
|
- **VoIP.ms API Abstraction**: Provides a simple interface over the powerful but complex VoIP.ms API. All communication with VoIP.ms is handled by the `voipms_client.py`.
|
|
- **Pre-configured Destinations**: Easily switch between routing to:
|
|
- A main SIP/IAX account.
|
|
- A primary cell phone number.
|
|
- A secondary cell phone number.
|
|
- **Routing History**: Logs every successful routing change to a PostgreSQL database for auditing purposes.
|
|
- **Secure and Simple**: Built with FastAPI, providing automatic interactive documentation and a robust server.
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
All routing endpoints are `POST` requests.
|
|
|
|
- `POST /route/main`
|
|
- **Description**: Routes the main business line to the primary office SIP account. Use this to direct calls to the office phones.
|
|
|
|
- `POST /route/cellphone1`
|
|
- **Description**: Forwards the main business line to the pre-configured primary cell phone.
|
|
|
|
- `POST /route/cellphone2`
|
|
- **Description**: Forwards the main business line to the pre-configured secondary (backup) cell phone.
|
|
|
|
- `GET /test/forwardings` & `GET /test/did`
|
|
- **Description**: Helper endpoints for testing the connection to the VoIP.ms API and retrieving diagnostic information.
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.10+
|
|
- A running PostgreSQL database.
|
|
- A VoIP.ms account with API access enabled.
|
|
- At least one DID (phone number) configured in your VoIP.ms account.
|
|
- Call Forwarding entries set up in the VoIP.ms portal for the cell phones you want to use.
|
|
|
|
### Installation
|
|
|
|
1. **Clone the repository and navigate into it.**
|
|
|
|
2. **Create a virtual environment and install dependencies:**
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Configure your environment:**
|
|
The application's configuration is managed by environment variables set in `settings_local.py`, `settings_dev.py`, or `settings_prod.py`. The `MODE` environment variable determines which configuration to use.
|
|
|
|
You **must** fill in the following values in your chosen settings file:
|
|
- `voipms_api_username`
|
|
- `voipms_api_password`
|
|
- `target_did`: The main phone number you want to control.
|
|
- `target_sip_account`: The SIP account for your office phones.
|
|
- `target_cellphone_1`: The primary cell phone number for forwarding.
|
|
- `target_cellphone_2`: The secondary cell phone number.
|
|
|
|
### Running the Service
|
|
|
|
```bash
|
|
export MODE=DEVELOPMENT
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port <your_port>
|
|
```
|
|
|
|
The API will be available at `http://localhost:<your_port>`, with interactive docs at `http://localhost:<your_port>/docs`.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
eamco_voipms/
|
|
├── app/
|
|
│ ├── __init__.py
|
|
│ ├── database.py # SQLAlchemy engine and session setup
|
|
│ ├── main.py # FastAPI application, endpoints, and logic
|
|
│ ├── models.py # SQLAlchemy model for the call log
|
|
│ └── voipms_client.py # Client for communicating with the VoIP.ms API
|
|
├── config.py # Logic for loading environment-specific settings
|
|
├── settings_dev.py # Development-specific settings
|
|
├── requirements.txt # Python dependencies
|
|
└── README.md # This file
|
|
```
|