SignalWire Integration
Summary: Connect your agents to phone numbers through SignalWire. This chapter covers account setup, phone number configuration, and testing your voice agents.
What You'll Learn
This chapter covers SignalWire integration:
- Account Setup - Create and configure your SignalWire account
- Phone Numbers - Purchase and manage phone numbers
- Mapping Numbers - Connect phone numbers to your agents
- Testing - Test your agents before going live
- Troubleshooting - Common issues and solutions
Integration Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ SignalWire Integration │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Caller │ → │ SignalWire │ → │ Your Server │ → │ Agent │ │
│ │ Phone │ │ Network │ │ (SWML) │ │ Logic │ │
│ └─────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ 1. Caller dials your phone number │
│ 2. SignalWire receives the call │
│ 3. SignalWire requests SWML from your server │
│ 4. Your agent handles the conversation │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Prerequisites
Before connecting to SignalWire:
- Working agent (tested locally)
- Publicly accessible server
- SignalWire account
Chapter Contents
| Section | Description |
|---|---|
| Account Setup | Create SignalWire account and project |
| Phone Numbers | Purchase and manage numbers |
| Mapping Numbers | Connect numbers to agents |
| Testing | Test calls and debugging |
| Troubleshooting | Common issues and fixes |
Quick Integration Steps
Step 1: Account Setup
- Create SignalWire account
- Create a project
- Note your Space Name
Step 2: Phone Number
- Purchase a phone number
- Or use a SIP endpoint
Step 3: Deploy Agent
- Deploy agent to public URL
- Verify HTTPS is working
- Test SWML endpoint responds
Step 4: Connect
- Point phone number to agent URL
- Make test call
- Verify agent responds
Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ Call Flow Architecture │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ SignalWire Cloud │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Inbound Call SWML Processor │ │ │
│ │ │ → │ │ │
│ │ │ • Fetches SWML from your server │ │ │
│ │ │ • Executes AI verbs │ │ │
│ │ │ • Handles speech │ │ │
│ │ │ • Calls SWAIG funcs │ │ │
│ │ │ │ │ │ │
│ │ └──────────────────────────────┼──────────────────────────────────┘ │ │
│ └─────────────────────────────────┼─────────────────────────────────────┘ │
│ │ │
│ ▼ HTTPS │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Your Server │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Agent (SWML) │ │ │
│ │ │ │ │ │
│ │ │ • Returns SWML doc │ │ │
│ │ │ • Handles functions │ │ │
│ │ │ • Business logic │ │ │
│ │ │ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Required URLs
Your agent needs to be accessible at these endpoints:
| Endpoint | Method | Purpose |
|---|---|---|
/ | POST | Main SWML document |
/swaig | POST | SWAIG function calls |
Security Considerations
- Always use HTTPS for production
- Enable basic auth for SWML endpoints
- Use secure tokens for SWAIG functions
- Don't expose sensitive data in prompts
- Monitor for unusual call patterns
Let's start with setting up your SignalWire account.
Create Account
- Go to signalwire.com
- Click Sign Up or Login
- Complete registration with email and password
- Verify your email address
Note: If you have problems verifying your account, email support@signalwire.com
Create a Project
After logging in:
- Navigate to Projects in the dashboard
- Click "Create New Project"
- Enter a project name (e.g., "Voice Agents")
- Select your use case
Space Name
Your Space Name is your unique SignalWire identifier.
URL Format: https://YOUR-SPACE-NAME.signalwire.com
Example: https://mycompany.signalwire.com
You'll need this for:
- API authentication
- Dashboard access
- SWML webhook configuration
API Credentials
Get your API credentials from the project:
- Go to API Credentials
- Note your Project ID
- Create an API Token if needed
| Credential | Format |
|---|---|
| Project ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| API Token | PTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| Space Name | your-space |
Keep these secure - don't commit to version control!
Environment Variables
Set these for your agent:
export SIGNALWIRE_PROJECT_ID="your-project-id"
export SIGNALWIRE_API_TOKEN="your-api-token"
export SIGNALWIRE_SPACE_NAME="your-space"
Dashboard Overview
| Section | Purpose |
|---|---|
| Phone Numbers | Purchase and manage phone numbers |
| SWML | Configure SWML scripts and webhooks |
| Logs | View call history and debugging info |
| API Credentials | Credentials and API explorer |
| Billing | Account balance and usage |
Add Credit
Before making calls:
- Go to Billing
- Add payment method
- Add credit to your account
Trial accounts may have limited credit for testing.
Account Verification
Some features require account verification:
- Phone number purchases
- Outbound calling
- Certain number types
Complete verification in Account Settings if prompted.
Next Steps
With your account ready:
- Purchase a phone number
- Deploy your agent
- Connect the number to your agent