Skip to content

README.md

Latest commit

 

History

History
264 lines (190 loc) · 9.31 KB

README.md

File metadata and controls

264 lines (190 loc) · 9.31 KB
PyTextNow Demo App Banner

🚀 PyTextNow Demo App

A modern, feature-rich messaging application built with Next.js, integrating with TextNow API for SMS, MMS, and AI-powered voice messaging.

Next.js TypeScript React Tailwind CSS

Features • Preview • Installation • Usage • API Reference • Contributing

✨ Features

💬 Messaging

  • SMS Messaging - Send and receive text messages in real-time
  • MMS Support - Share images and videos seamlessly
  • Voice Messages - Record and send audio messages
  • AI Voice Messages - Generate AI-powered voice messages using Google Gemini 2.5 Flash Preview TTS
    • 30+ preset voices to choose from
    • Customizable accent, mood, and tone
    • Natural-sounding speech synthesis

🎨 User Experience

  • Modern Dark Theme - Beautiful black and electric blue UI
  • Mobile-First Design - Optimized for all device sizes
  • Real-Time Updates - Instant message delivery and synchronization
  • Conversation Management - Organize and manage multiple conversations
  • Search Functionality - Quickly find conversations

🔐 Security & Authentication

  • Secure User Accounts - SQLite-based user management
  • Encrypted Credentials - Safe storage of TextNow API credentials
  • Session Management - Persistent login sessions

⚙️ Advanced Features

  • Media Proxy - Secure authenticated media loading
  • Contact Management - Edit and customize contact names
  • User Settings - Manage API keys and preferences
  • Error Handling - Robust error handling and user feedback

📸 Preview

Main Interface

Landing Page View Sign Up Page
Landing Page Sign Up Page

Messaging Features

Conversational Interface
Conversational Interface

Settings & Components

Start New Convo User Settings AI Voice Messaging
Start New Convo User Settings AI Voice Messaging

🛠️ Installation

Prerequisites

  • Node.js 18+ and npm/yarn
  • TextNow Account with API credentials
  • Google Gemini API Key (optional, for AI voice messages)

Step 1: Clone the Repository

git clone https://github.com/zodyking/PyTextNow-Demo-App.git
cd PyTextNow-Demo-App

Step 2: Install Dependencies

npm install

Step 3: Run the Development Server

npm run dev

The app will be available at http://localhost:3000

📖 Usage

Getting TextNow API Credentials

  1. Log in to TextNow in your browser
  2. Open Developer Tools (F12)
  3. Navigate to Application → Cookies → https://www.textnow.com
  4. Copy the following cookie values:
    • connect.sid - Session ID cookie
    • _csrf - CSRF token cookie
  5. Note your TextNow username

Setting Up Your Account

  1. Sign Up: Create a new account with your TextNow credentials
  2. Login: Access your dashboard with your credentials
  3. Configure AI Voice (Optional): Add your Google Gemini API key in User Settings for AI voice message generation

Sending Messages

  • SMS: Type your message and click send
  • MMS: Click the attachment icon and select an image or video
  • Voice Message: Click the microphone icon and record your message
  • AI Voice Message: Click the AI voice icon, type your message, select voice/accent/mood/tone, and send

🏗️ Project Structure

PyTextNow-Demo-App/
├── app/
│   ├── api/                    # API routes
│   │   ├── conversations/      # Conversation management
│   │   ├── messages/           # Message fetching
│   │   ├── send-sms/           # SMS sending
│   │   ├── send-mms/           # MMS sending
│   │   ├── send-voice/         # Voice message sending
│   │   ├── gemini-tts/         # AI voice generation
│   │   ├── media-proxy/        # Authenticated media proxy
│   │   └── users/              # User management
│   ├── dashboard/              # Main dashboard
│   ├── login/                  # Login page
│   ├── signup/                 # Signup page
│   └── layout.tsx              # Root layout
├── components/                 # React components
│   ├── ConversationList.tsx    # Conversation sidebar
│   ├── MessageView.tsx         # Message display
│   ├── SendMessageForm.tsx     # Message input form
│   ├── UserSettings.tsx        # User settings modal
│   └── ContactNameEditor.tsx   # Contact name editor
├── lib/
│   └── db.ts                   # SQLite database setup
├── types/
│   └── index.ts                # TypeScript type definitions
└── scripts/
    └── clear-db.js             # Database cleanup utility

🔌 API Reference

Internal API Routes

Endpoint Method Description
/api/users/signup POST Create a new user account
/api/users/login POST Authenticate user
/api/users/get POST Get user information
/api/users/update POST Update user settings
/api/conversations POST Fetch all conversations
/api/messages POST Get messages for a conversation
/api/send-sms POST Send SMS message
/api/send-mms POST Send MMS message (image/video)
/api/send-voice POST Send voice message
/api/gemini-tts POST Generate AI voice message
/api/media-proxy GET Proxy authenticated media requests

TextNow API Integration

This app integrates with the TextNow API following the specifications from PyTextNow_API issue #75.

MMS Flow:

  1. Get upload URL: GET /api/v3/attachment_url?message_type=2
  2. Upload file: PUT {pre-signed-url} with raw file data
  3. Send message: POST /api/v3/send_attachment with attachment URL

Voice Message Flow:

  1. Get upload URL: GET /api/v3/attachment_url?message_type=3
  2. Upload audio: PUT {pre-signed-url} with audio data
  3. Send message: POST /api/v3/send_attachment with attachment URL

🎨 Technologies

🔒 Security Notes

⚠️ Important Security Considerations:

  • This is a demo application for educational purposes
  • Credentials are stored in SQLite database (local development)
  • For production use, implement:
    • JWT token-based authentication
    • Encrypted credential storage
    • Environment variables for sensitive data
    • HTTPS-only communication
    • Rate limiting and request validation
    • Proper session management

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Made with ❤️ using Next.js and TypeScript

⭐ Star this repo if you find it helpful!