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.

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

Clone the repository and navigate into it.

Create a virtual environment and install dependencies:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

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

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

4.7 KiB Raw Blame History