# Twilio Call Service (FastAPI)

This microservice replicates Axiom's Swift/Vapor IVR functionality using Python 3.11.9 and FastAPI.

## Features
- Interactive Voice Response (IVR) system powered by Twilio.
- REST API endpoints for managing call sessions and handling Twilio webhooks.
- Proxy integration with PEAK API for user authentication.
- **FastMCP Integration**: Enables AI-driven tools and streaming capabilities for enhanced functionality.
- Supports deployment to Heroku with PostgreSQL.

## Local Development

### Prerequisites
- Python 3.11.9
- Twilio account credentials
- PostgreSQL (optional, SQLite is supported for local testing)

### Setup
1. Create a virtual environment and install dependencies:
   ```bash
   python -m venv env && source env/bin/activate
   pip install -r requirements.txt
   ```
2. Copy the example environment file and edit credentials:
   ```bash
   cp .env.example .env  # edit credentials
   ```
3. Start the FastAPI server:
   ```bash
   uvicorn app.main:app --reload
   ```

Expose port 8000 via **ngrok** for Twilio testing:
```bash
ngrok http 8000
```
Set your Twilio Voice webhooks:
- Incoming: `https://<ngrok>/twilio/voice/incoming` (POST)
- Outbound (when creating calls): `https://<ngrok>/twilio/call`

## Deploy to Heroku
```bash
heroku create my-twilio-call-svc
heroku addons:create heroku-postgresql:hobby-dev
heroku config:set TWILIO_ACCOUNT_SID=... TWILIO_AUTH_TOKEN=... TWILIO_PHONE_NUMBER=...
```
Push the code:
```bash
git push heroku Head:main
```
Heroku provides `DB_URL` automatically.

## Triggering an outbound call via Twilio REST API
```python
from twilio.rest import Client
from dotenv import load_dotenv
import os

load_dotenv()
client = Client(os.getenv("TWILIO_ACCOUNT_SID"), os.getenv("TWILIO_AUTH_TOKEN"))
call = client.calls.create(
    to="<patient_phone>",
    from_=os.getenv("TWILIO_PHONE_NUMBER"),
    url="https://<app_url>/twilio/call?name=John&referrer=Dr.%20Smith"
)
print(call.sid)
```

```Manual
Invoke-RestMethod -Method Post "https://dev-qa-axiom-cms-server-03e5df5ab8f3.herokuapp.com/test-call?to=+12345678900" 
```

## FastMCP Integration
This project uses `FastMCP` to provide AI-driven tools and streaming capabilities. Key features include:
- **Tooling**: Custom tools like `list_history` and `make_call` are exposed via the MCP server.
- **Streaming**: Supports Server-Sent Events (SSE) for real-time communication.
- **OpenAPI Compatibility**: Automatically generates OpenAPI documentation for MCP endpoints.

FastMCP is mounted at `/mcp`, and its streaming endpoint is available at `/sse`.

### Example Usage
You can interact with the MCP server using HTTP requests or AI tools. For example:
- **List Call History**: Use the `list_history` tool to retrieve call session data.
- **Make a Call**: Use the `make_call` tool to initiate a Twilio call.

For more details, refer to the `FastMCP` documentation: [FastMCP Documentation](https://fastmcp.readthedocs.io/).