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.

Related MCP server: voxaphone-mcp

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:

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

2. Copy the example environment file and edit credentials:

   cp .env.example .env  # edit credentials

3. Start the FastAPI server:

   uvicorn app.main:app --reload

Expose port 8000 via ngrok for Twilio testing:

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

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:

git push heroku Head:main

Heroku provides DB_URL automatically.

Triggering an outbound call via Twilio REST API

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)

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.