Skip to main content

Getting Started

Complete setup guide for D&D Adventure with DM Aiden. Follow these steps in order to get your application running with SignalWire integration.

Prerequisites​

  • Python 3.8+ installed on your computer
  • Git for cloning the repository
  • Modern web browser with microphone access
  • SignalWire account (free tier available)
  • ngrok account (free tier available)

1. Clone Repository​

# Clone the repository
git clone <(https://github.com/Manny-r31/dnd-signalwire-project)>
cd NewProjectSW

# Optional: Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install Dependencies​

# Install Python dependencies
pip install -r requirements.txt

Required packages include:

  • fastapi - Web framework
  • uvicorn - ASGI server
  • signalwire - SignalWire Python SDK
  • python-multipart - File upload support

3. ngrok Tunnel Setup​

Install ngrok​

  1. Create account at ngrok.com
  2. Download ngrok for your operating system
  3. Install and authenticate:
# Install your authtoken (found in ngrok dashboard)
ngrok authtoken YOUR_AUTHTOKEN

Start ngrok Tunnel​

# Create tunnel in terminal
ngrok http 8000

You'll see output like:

Forwarding    https://abc123.ngrok.io -> http://localhost:8000

Save this URL - you'll need it for SignalWire configuration.

4. SignalWire Configuration Setup​

Create SignalWire Account​

  1. Sign up at signalwire.com
  2. Create a new project in your dashboard
  3. Get your credentials:
    • Project ID (located on yourspace.signalwire.com/dashboard)
    • API Token:
      1. Navigate to yourspace.signalwire.com/credentials
      2. Create new token utilizing the "+ new" button
      3. Give token name, make no changes to base permissions, then click "save"
      4. When redirected back to api credentials page, click the "show" option under the "Token" column for API Token
    • Space URL (e.g., yourspace.signalwire.com)

Configure Environment Variables​

Create a .env file in your project root:

# SignalWire Configuration
SIGNALWIRE_PROJECT_ID=your_project_id_here
SIGNALWIRE_API_TOKEN=your_api_token_here
SIGNALWIRE_SPACE_URL=yourspace.signalwire.com

# Application Settings
DND_USERNAME=dnd_user
DND_PASSWORD=dnd_pass123

5. SignalWire Resource Creation (SWML Webhook)​

Create SWML Webhook​

  1. Navigate to yourspace.signalwire.com/resources

  2. Click the "+ Add" button to add a resource, then click "new script"

  3. Click on the "SWML Script" option in the new menu that appears

  4. Give it a name, then change "Handling Calls Using" field to the "External URL" option

  5. For the primary script URL, use your ngrok URL:

    https://dnd_user:dnd_pass123@abc123.ngrok.io/dnd

    Then click "create"

    Important:

    • Replace abc123.ngrok.io with your actual ngrok URL
    • Include the custom username:password if using custom credentials, otherwise keep dnd_user:dnd_pass123

6. Environment Configuration​

Update Application URLs​

In dnd_app.js, update the destination and token (if needed):

// Update with your SignalWire project details
const DESTINATION = 'your-signalwire-destination';
const STATIC_TOKEN = 'your-client-token'; // From SignalWire dashboard

Get Specific SignalWire Credentials​

Get the Destination​

  1. From yourspace.signalwire.com/resources, click on your newly created SWML webhook's name
  2. Select the "Addresses & Phone Numbers" tab, then copy the "/public/" destination below the webhook name
  3. Paste this into the 'your-signalwire-destination' field

Get the Static Token​

  1. Navigate to developer.signalwire.com/rest/signalwire-rest/endpoints/fabric/guest-tokens-create
  2. On the far righthand side, ensure that python is the selected language
  3. In the "request" section, fill in the required information, this should include:
    • Your space name
    • Your project ID
    • Your API token
    • Your allowed address (shown by clicking on the name of your SWML webhook while in the "Addresses & Phone Numbers" tab)
    • A set "expire at" time
  4. Click "Send API request" button after information has been filled out and copy down the first key listed
  5. Paste this key into the 'your-client-token' field

7. Test Your Setup​

Start the Application​

# Make sure ngrok is running in one terminal
ngrok http 8000

# Start the application in another terminal
python dnd_gamemaster.py --port 8000

Troubleshooting​

Common Issues​

"Cannot connect to DM Aiden"

  • Check that ngrok tunnel is running
  • Verify SignalWire webhook URL is correct
  • Ensure application is running on port 8000

"Character creation not working"

  • Verify SignalWire API credentials are correct
  • Check that webhook URL includes /dnd endpoint
  • Ensure ngrok URL is publicly accessible

Check Logs​

Monitor your application logs for errors:

# Application logs show webhook calls and errors
python dnd_gamemaster.py --port 8000

# Check ngrok connection logs
ngrok http 8000 --log=stdout

Next Steps​