telnyx-api

# Telnyx API - Comprehensive Communication Platform ## When to Use This Skill Use this skill when working with Telnyx's communication APIs for: - **SMS/MMS Messaging** - Send and receive text messages programmatically - **Voice Communication** - Build voice calling applications with Call Control API - **Phone Number Management** - Search, purchase, and configure phone numbers - **Messaging Profiles** - Configure messaging settings and webhooks - **Webhook Integration** - Handle real-time events and delivery notifications - **Two-Way SMS Conversations** - Build interactive SMS experiences - **Bulk SMS Sending** - Send messages to multiple recipients with rate limiting - **Message Scheduling** - Schedule messages for future delivery - **Production Deployment** - Deploy messaging features with error handling and monitoring This skill applies to building communication features in applications, setting up SMS notification systems, creating voice IVR systems, or integrating telephony capabilities. ## Quick Reference ### 1. Send Simple SMS ```javascript const axios = require('axios'); async function sendSMS(to, from, text) { const response = await axios.post( 'https://api.telnyx.com/v2/messages', { from, to, text }, { headers: { 'Authorization': `Bearer ${process.env.TELNYX_API_KEY}`, 'Content-Type': 'application/json' } } ); return response.data; } // Usage sendSMS('+14155552671', '+14155559999', 'Hello from Telnyx!'); ``` ### 2. Send MMS with Media ```javascript async function sendMMS(to, from, text, mediaUrls) { const response = await axios.post( 'https://api.telnyx.com/v2/messages', { from, to, text, media_urls: mediaUrls, type: 'MMS' }, { headers: { 'Authorization': `Bearer ${process.env.TELNYX_API_KEY}`, 'Content-Type': 'application/json' } } ); return response.data; } // Usage sendMMS('+14155552671', '+14155559999', 'Check this out!', ['https://example.com/image.jpg']); ``` ### 3. Handle Incoming Messages (Webhook) ```javascript const express = require('express'); const app = express(); app.use(express.json()); app.post('/webhooks/telnyx', (req, res) => { const event = req.body.data; if (event.event_type === 'message.received') { const from = event.payload.from.phone_number; const text = event.payload.text; const to = event.payload.to[0].phone_number; console.log(`Received: "${text}" from ${from}`); // Auto-reply sendSMS(from, to, 'Thanks for your message!'); } res.status(200).send('OK'); }); ``` ### 4. Validate Phone Numbers ```javascript function validateE164(phoneNumber) { const e164Regex = /^\+[1-9]\d{1,14}$/; if (!e164Regex.test(phoneNumber)) { return { valid: false, error: 'Phone number must be in E.164 format (e.g., +14155552671)' }; } return { valid: true }; } // Usage const validation = validateE164('+14155552671'); if (!validation.valid) { throw new Error(validation.error); } ``` ### 5. Send with Error Handling ```javascript async function sendWithRetry(to, from, text, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await sendSMS(to, from, text); } catch (error) { if (error.response?.status === 500 && attempt < maxRetries) { const delayMs = Math.pow(2, attempt) * 1000; console.log(`Retry in ${delayMs}ms...`); await new Promise(resolve => setTimeout(resolve, delayMs)); } else { throw error; } } } } ``` ### 6. Bulk Sending with Rate Limiting ```javascript async function sendBulkSMS(recipients, from, text) { const delayMs = 100; // 10 messages/second const results = []; for (const recipient of recipients) { try { const result = await sendSMS(recipient, from, text); results.push({ success: true, to: recipient, id: result.data.id }); } catch (error) { results.push({ success: false, to: recipient, error: error.message }); } await new Promise(resolve => setTimeout(resolve, delayMs)); } return results; } ``` ### 7. Verify Webhook Signatures ```javascript const crypto = require('crypto'); function verifyWebhook(body, signature, timestamp, publicKey) { // Check timestamp freshness (prevent replay attacks) const timestampMs = parseInt(timestamp); const now = Date.now(); if (Math.abs(now - timestampMs) > 5 * 60 * 1000) { return false; // Reject if older than 5 minutes } // Verify signature const payload = `${timestamp}.${JSON.stringify(body)}`; const hmac = crypto.createHmac('sha256', publicKey); const digest = hmac.update(payload).digest('hex'); return signature === digest; } // Usage app.post('/webhooks/telnyx', (req, res) => { const signature = req.headers['telnyx-signature-ed25519']; const timestamp = req.headers['telnyx-timestamp']; if (!verifyWebhook(req.body, signature, timestamp, process.env.TELNYX_PUBLIC_KEY)) { return res.status(401).send('Invalid signature'); } // Process webhook... res.status(200).send('OK'); }); ``` ### 8. Schedule Message for Later ```javascript async function scheduleMessage(to, from, text, sendAt) { const response = await axios.post( 'https://api.telnyx.com/v2/messages', { from, to, text, send_at: sendAt // ISO 8601: "2025-10-25T14:30:00Z" }, { headers: { 'Authorization': `Bearer ${process.env.TELNYX_API_KEY}`, 'Content-Type': 'application/json' } } ); return response.data; } // Schedule for 1 hour from now const futureTime = new Date(Date.now() + 3600000).toISOString(); scheduleMessage('+14155552671', '+14155559999', 'Reminder!', futureTime); ``` ### 9. Two-Way Conversation Flow ```javascript const conversations = new Map(); app.post('/webhooks/telnyx', async (req, res) => { const event = req.body.data; if (event.event_type === 'message.received') { const from = event.payload.from.phone_number; const to = event.payload.to[0].phone_number; const text = event.payload.text.toLowerCase(); let state = conversations.get(from) || 'start'; let reply; switch (state) { case 'start': reply = "Welcome! What's your name?"; conversations.set(from, 'asked_name'); break; case 'asked_name': reply = `Nice to meet you, ${text}! How can I help?`; conversations.set(from, 'helping'); break; case 'helping': reply = 'Thanks! A human will respond shortly.'; conversations.delete(from); break; } await sendSMS(from, to, reply); } res.status(200).send('OK'); }); ``` ### 10. Python Example ```python import requests import os def send_sms(to, from_number, text): url = 'https://api.telnyx.com/v2/messages' headers = { 'Authorization': f"Bearer {os.environ['TELNYX_API_KEY']}", 'Content-Type': 'application/json' } payload = { 'from': from_number, 'to': to, 'text': text } response = requests.post(url, json=payload, headers=headers) response.raise_for_status() return response.json() # Usage result = send_sms('+14155552671', '+14155559999', 'Hello from Python!') print(f"Message ID: {result['data']['id']}") ``` ## Key Concepts ### 1. E.164 Phone Number Format International phone number format: `+[country code][number]` - US Example: `+14155552671` - UK Example: `+442071234567` - Always include the `+` prefix ### 2. Messaging Profile A configuration container that groups numbers and defines webhook settings. Benefits: - Centralized webhook management - Number pools for load distribution - Alphanumeric sender IDs - Easy number management ### 3. Message Encoding - **GSM-7**: 160 chars/segment for standard ASCII (cheaper) - **UCS-2**: 70 chars/segment for emoji/unicode (more expensive) - Long messages split into segments (max 10) - Multi-part messages: GSM-7 = 153 chars/segment, UCS-2 = 67 chars/segment ### 4. Webhook Events Real-time notifications about message status: - `message.sent` - Sent to carrier - `message.delivered` - Delivered to recipient - `message.failed` - Delivery failed - `message.received` - Inbound message received - `message.finalized` - Reached final state ### 5. Authentication All API requests require Bearer token authentication: ``` Authorization: Bearer YOUR_API_KEY ``` Store API keys in environment variables, never hardcode. ## Reference Files The `references/` directory contains detailed documentation: ### authentication.md Complete guide to API key management and security: - Creating and managing API keys - Environment variable setup (Node.js, Python, Docker, Kubernetes) - Best practices for key rotation and security - IP whitelisting configuration - Webhook signature verification - Common authentication errors and solutions ### messaging-api.md Full Messaging API reference: - Complete endpoint documentation (`/v2/messages`) - All request/response parameters - Message status values and lifecycle - Character encoding details (GSM-7 vs UCS-2) - Message segmentation rules - MMS limitations and supported formats - Pagination and filtering options ### webhooks.md Comprehensive webhook reference: - All webhook event types with payload examples - Signature verification (HMAC-SHA256) - Webhook configuration (global, profile, per-message) - Best practices (idempotency, async processing, retries) - Testing webhooks locally with ngrok - Complete webhook handler example - Troubleshooting guide ### error-codes.md Complete error reference and handling: - All HTTP status codes and meanings - Common error codes with solutions - Validation errors (10001-10007) - Rate limiting errors (429) - Server errors (500, 502, 503) - Webhook-specific delivery errors - Comprehensive error handler implementation - Retry strategies with backoff ### best-practices.md Production deployment patterns: - Using messaging profiles in production - Robust error handling patterns - Exponential backoff retry logic - Rate limiting for bulk sending - Message tracking and status monitoring - Phone number validation and formatting - Message content optimization - Character limit handling - Webhook async processing with queues - Idempotency implementation - Structured logging and monitoring - Cost optimization strategies - Testing patterns - Production deployment checklist ### number-management.md Phone number operations: - Searching available numbers - Purchasing phone numbers - Configuring number settings - Porting existing numbers - Number pool management ### 10dlc.md 10DLC (10-Digit Long Code) registration and compliance: - Campaign approval stages (TCR_ACCEPTED → MNO_PENDING → MNO_PROVISIONED) - Brand and campaign registration process - Use case selection (Customer Care, Marketing, 2FA, etc.) - TCPA and CTIA compliance requirements - Required message elements (opt-in, opt-out, HELP) - Monitoring campaign status via API - Phone number association (portal-only, not via API) - Cost structure and timeline expectations - Common issues and troubleshooting - Production checklist ## Working with This Skill ### For Beginners **Start Here:** 1. Use **Quick Reference Example #1** (Send Simple SMS) 2. Set up environment variables for API key 3. Test sending to your own phone number 4. Set up **Quick Reference Example #3** (Handle Incoming Messages) 5. Test two-way messaging **Key Concepts to Learn:** - E.164 phone number format - Bearer token authentication - Basic webhook handling **Reference Files:** - Start with `authentication.md` for setup - Check `messaging-api.md` for basic API usage - Review `error-codes.md` when errors occur ### For Intermediate Users **Focus Areas:** 1. Implement **Quick Reference Example #7** (Verify Webhook Signatures) 2. Use **Quick Reference Example #5** (Error Handling with Retry) 3. Build conversation flows with **Quick Reference Example #9** 4. Create a messaging profile in `best-practices.md` **Key Concepts to Master:** - Messaging profiles - Webhook security - Error handling patterns - Message segmentation **Reference Files:** - Study `webhooks.md` for event types and security - Review `best-practices.md` for production patterns - Use `error-codes.md` for comprehensive error handling ### For Advanced Users **Advanced Patterns:** 1. Implement bulk messaging from `best-practices.md` with queue system 2. Build IVR systems with Call Control API