Telnyx Inbound AI Gather - n8n Workflow

Complete n8n workflow for handling Telnyx inbound calls with AI-powered data collection.

🎯 What This Workflow Does

1. Receives inbound call webhooks from Telnyx
2. Answers the call automatically
3. Gathers email address using Telnyx AI (conversational STT + validation)
4. Validates the captured email format
5. Confirms back to the caller
6. Saves to Google Sheets (optional)
7. Hangs up gracefully

---

📋 Prerequisites

1. Telnyx Account Setup

• Create a Telnyx Call Control Application
• Configure webhook URL: https://your-n8n-instance.com/webhook/telnyx-inbound
• Assign your DID (phone number) to this application
• Copy your Telnyx API Key

2. n8n Setup

• n8n instance running (cloud or self-hosted)
• Import telnyx-inbound-ai-gather.json into n8n
• Configure credentials (see below)

---

⚙️ Configuration Steps

Step 1: Create Telnyx API Credential in n8n

1. Go to Settings → Credentials
2. Click Add Credential
3. Select Header Auth
4. Configure:
   • Name: Telnyx API Key
   • Credential for: HTTP Request
   • Name (header): Authorization
   • Value: Bearer YOUR_TELNYX_API_KEY_HERE

Step 2: Activate the Webhook

1. Open the workflow in n8n
2. Click the Telnyx Webhook node
3. Click Listen for Test Event or Execute Workflow
4. Copy the webhook URL (e.g., https://your-n8n.com/webhook/telnyx-inbound)
5. Paste this URL into your Telnyx Call Control Application settings

Step 3: Configure Google Sheets (Optional)

If you want to save captured emails to Google Sheets:

1. Create a Google Sheet with these columns:

   • timestamp
   • from_number
   • to_number
   • email
   • email_valid
   • transcript
   • call_session_id

2. In n8n, configure Google Sheets credential:

   • Go to Settings → Credentials
   • Add Google Sheets OAuth2 API
   • Connect your Google account

3. Update the Save to Google Sheets node with your Sheet ID

---

🔄 Workflow Flow Diagram

Inbound Call
    ↓
[Telnyx Webhook] → [Parse Data] → [Route by Event]
                                         ↓
                    ┌────────────────────┼────────────────────┐
                    ↓                    ↓                    ↓
            [call.initiated]    [call.answered]    [call.ai_gather.ended]
                    ↓                    ↓                    ↓
            [Answer Call]      [Gather Using AI]    [Process Results]
                    ↓                    ↓                    ↓
            [Respond 200]        [Respond 200]      [Validate Email]
                                                            ↓
                                        ┌───────────────────┴───────────────────┐
                                        ↓                                       ↓
                                  [Email Valid]                         [Email Invalid]
                                        ↓                                       ↓
                            [Confirm + Save to Sheets]              [Apologize Message]
                                        ↓                                       ↓
                                  [Hangup Success]                       [Hangup Failed]
                                        ↓                                       ↓
                                  [Respond 200]                          [Respond 200]

---

🎤 Customizing the AI Gather

Edit the Gather Using AI node to capture different data. Here are examples:

Example 1: Capture Email + Name

{
  "greeting": "Hi! Please tell me your full name and email address.",
  "parameters": {
    "type": "object",
    "properties": {
      "first_name": {
        "type": "string",
        "description": "Caller's first name"
      },
      "last_name": {
        "type": "string",
        "description": "Caller's last name"
      },
      "email": {
        "type": "string",
        "format": "email",
        "description": "Caller's email address"
      }
    },
    "required": ["first_name", "last_name", "email"]
  },
  "voice": "Polly.Joanna",
  "language": "en-US"
}

Example 2: Capture Phone Number

{
  "greeting": "Please tell me your callback phone number.",
  "parameters": {
    "type": "object",
    "properties": {
      "phone": {
        "type": "string",
        "pattern": "^\\+?[1-9]\\d{1,14}$",
        "description": "Phone number in E.164 format"
      }
    },
    "required": ["phone"]
  },
  "voice": "Polly.Matthew",
  "language": "en-US"
}

Example 3: Capture Address

{
  "greeting": "Please provide your full mailing address including street, city, state, and zip code.",
  "parameters": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "state": { "type": "string" },
      "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" }
    },
    "required": ["street", "city", "state", "zip"]
  },
  "voice": "Polly.Joanna",
  "language": "en-US"
}

---

🔍 Testing

Test with cURL (Simulate Telnyx Webhook)

Call Initiated Event:

curl -X POST "https://your-n8n-instance.com/webhook/telnyx-inbound" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "event_type": "call.initiated",
      "payload": {
        "call_control_id": "test-call-123",
        "call_session_id": "test-session-456",
        "from": "+15551234567",
        "to": "+15559876543",
        "direction": "incoming",
        "state": "parked"
      }
    }
  }'

AI Gather Ended Event:

curl -X POST "https://your-n8n-instance.com/webhook/telnyx-inbound" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "event_type": "call.ai_gather.ended",
      "payload": {
        "call_control_id": "test-call-123",
        "call_session_id": "test-session-456",
        "from": "+15551234567",
        "to": "+15559876543",
        "parameters": {
          "email": "john.doe@example.com"
        },
        "transcript": "My email is john dot doe at example dot com",
        "status": "completed"
      }
    }
  }'

---

🚀 Production Tips

1. Webhook Signatures: Add signature verification in the Parse Webhook Data node:

   // Verify Telnyx signature (standard-webhooks)
   const signature = $request.headers['telnyx-signature-ed25519'];
   const timestamp = $request.headers['telnyx-timestamp'];
   const publicKey = 'your-telnyx-public-key';
   
   // Implement Ed25519 signature verification
   // See: https://developers.telnyx.com/docs/v2/development/webhooks#verify-webhooks

2. Error Handling: Add try-catch blocks and error notifications (email/Slack)

3. Rate Limiting: Monitor concurrent calls and queue if needed

4. Logging: Enable n8n execution logging for debugging

5. Retry Logic: Telnyx automatically retries non-200 responses

---

📊 Available Telnyx Events

The workflow handles these events:

Event	Description	Action
call.initiated	Inbound call received	Answer the call
call.answered	Call answered successfully	Start AI gather
call.ai_gather.ended	AI gather completed	Process results
call.ai_gather.partial_results	Streaming results	(Optional) Preview
call.hangup	Call ended	Log/cleanup

---

🎨 Voices Available

Common Polly voices for voice parameter:

• Female: Polly.Joanna, Polly.Kendra, Polly.Kimberly, Polly.Salli, Polly.Amy (British)
• Male: Polly.Matthew, Polly.Justin, Polly.Joey, Polly.Brian (British)

---

🔧 Troubleshooting

Issue: Webhook not receiving events

• ✅ Check Telnyx Call Control app webhook URL is correct
• ✅ Ensure n8n workflow is active (not paused)
• ✅ Verify DID is assigned to the Call Control application
• ✅ Check n8n webhook is publicly accessible (not localhost)

Issue: Call not answered

• ✅ Verify Telnyx API key is correct in credentials
• ✅ Check call_control_id is being extracted properly
• ✅ Review n8n execution logs for API errors

Issue: AI gather returns empty/invalid email

• ✅ Test with clearer pronunciation
• ✅ Add retry logic for failed gathers
• ✅ Enable send_partial_results to debug
• ✅ Adjust greeting for clearer instructions

Issue: 200 OK not sent fast enough

• ✅ Move heavy processing (Google Sheets, DB writes) to separate workflow
• ✅ Use n8n's "Split in Batches" or background execution

---

📚 References

• Telnyx Call Control API Docs
• Telnyx Gather Using AI
• n8n Webhook Trigger
• Standard Webhooks

---

💡 Next Steps

• Add retry logic for failed email captures
• Implement caller verification (ANI lookup)
• Add SMS confirmation after call
• Store to Redis/database instead of Sheets
• Add call recording
• Implement transfer to live agent if AI fails

---

📝 License

MIT - Use freely for your projects!

🤝 Support

For Telnyx-specific questions: Telnyx Support For n8n questions: n8n Community