# 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.

[![Language](https://img.shields.io/badge/Language-Python-blue)](https://www.python.org/)
[![Framework](https://img.shields.io/badge/Framework-FastAPI-green)](https://fastapi.tiangolo.com/)
[![VoIP Provider](https://img.shields.io/badge/Provider-VoIP.ms-e31d33)](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
```