Skip to content
BranchesTags

Repository files navigation

Respondly

The All-in-One AI-Powered CRM & Customer Support Platform

PHP MySQL Redis AI License Code Size

Respondly is a production-ready, multi-tenant SaaS platform that unifies AI chatbots, customer relationship management, order handling, appointment booking, social-media automation, and payments — wrapped in a fast, framework-free PHP core with a bilingual (AR/EN) interface.

Table of Contents

Key Features

Area Capabilities
AI & Automation OpenRouter-powered AI chat (dashboard, website widget, live chat), custom AI agents, per-business AI models, typing indicators & SSE streaming
CRM Businesses with multi-tenancy, leads, customer lists, interventions, comments, knowledge base, import/export
Commerce Products & orders, order lifecycle with automated confirmations, appointment booking, discount & coupon flows
Payments Subscriptions, one-time invoices, 6 payment providers (see below), hosted checkout, Vodafone Cash request approval
Social & Messaging WhatsApp (Meta), Messenger, Instagram, TikTok automation webhooks, live chat inbox
SaaS Admin Super-admin control panel: businesses, users, subscriptions, AI key management, monitoring, cron console, backups, file manager
Marketing & SEO Blog with news/image/video sitemaps, landing features, use cases, FAQ, glossary, knowledge hub, robots.txt, llms.txt
Internationalization Full Arabic (RTL) and English interfaces
Scalability Optional Redis for caching & distributed locks, PDO prepared statements, queue worker

Payment Gateways

Plug-and-play global and MENA payment infrastructure with an admin panel to configure keys, toggle providers on/off, and run live connectivity tests — no code changes required.

Provider Region Webhook Endpoint Signature Verification
Stripe Global (USD, EUR, GBP...) POST /api/webhook/stripe Stripe-Signature (Ed25519/Webhook secret)
PayPal Global (USD...) POST /api/webhook/paypal Webhook ID + OAuth token verification
Adyen Global (USD, EUR, AED...) POST /api/webhook/adyen HMAC SHA-256
Paymob MENA / Egypt (EGP, SAR, AED...) POST /api/webhook/paymob HMAC (Paymob hmac)
Fawaterk Egypt (EGP) POST /api/webhook/fawaterk Signed payload secret
Cash on Delivery Local — Admin-approved requests

Every webhook payload is signature-verified, matched to an invoice, marked paid, and logged in payment_transactions with full audit trail. Invalid signatures are rejected with 403.

Architecture

                    ┌─────────────────────────────────────────────┐
                    │              Web Browser (RTL/EN)           │
                    │   Admin  ·  Business  ·  Customer  ·  Blog  │
                    └──────────────────────┬──────────────────────┘
                                           │
                    ┌──────────────────────▼──────────────────────┐
                    │                Front Controller              │
                    │              public/index.php                │
                    │   Router → Middleware → Controller → View    │
                    └───────┬──────────────┬──────────────┬────────┘
                            │              │              │
              ┌─────────────▼───┐  ┌───────▼───────┐  ┌───▼──────────────┐
              │   App Services  │  │  Payment Hub  │  │  Social Hub      │
              │  AI · CRM ·     │  │ Stripe · PayPal│  │ WhatsApp · Meta  │
              │  Messaging ·    │  │ Adyen · Paymob │  │ TikTok · FB      │
              │  Backup · Cron  │  │ Fawaterk · COD │  │ Webhook intake   │
              └─────────┬───────┘  └───────┬────────┘  └──────────────────┘
                        │                  │
              ┌─────────▼───────┐  ┌───────▼────────┐      ┌──────────────┐
              │     MySQL       │  │   OpenRouter   │      │ Redis (opt.) │
              │    8.0          │  │   LLM APIs     │      │ cache/locks  │
              └─────────────────┘  └────────────────┘      └──────────────┘

Design principles

  • Framework-free core — a lightweight custom MVC (Router, Request, Response, Database, Security, Logger) with zero runtime dependencies; vendor/ is dev-only (PHPUnit).
  • PSR-4 autoloading — App\ maps to src/.
  • Layered security — global middleware stack, role-based route guards, CSRF tokens, AES-256-CBC encryption for credentials, Argon2id password hashing, strict webhook verification.
  • Scheduled jobs — standalone cron scripts (log rotation, order confirmations, queue worker) orchestrated from the admin console.

Technology Stack

Layer Technology
Language PHP 8.3+
Database MySQL 8.0 (utf8mb4, PDO prepared statements)
Cache Redis (optional, for cache & locks)
AI OpenRouter (model-agnostic LLM routing)
Payments Stripe, PayPal, Adyen, Paymob, Fawaterk, Cash on Delivery
Auth Email/password, Google OAuth, 2FA, email verification
Frontend Vanilla JS + CSS (no build step)
Dev tooling PHPUnit 11, Composer

Getting Started

Requirements

  • PHP 8.3+ with extensions: pdo_mysql, openssl, curl, json, mbstring, fileinfo, zip
  • MySQL 8.0+
  • Composer (dev only)
  • Redis (optional)

1. Install

git clone https://github.com/jczoz/Respondly.git
cd Respondly

# Dev dependencies (tests only — runtime needs nothing)
composer install

2. Configure environment

cp .env.example .env

Generate an encryption key and fill in your database, SMTP and API credentials (see Environment Configuration).

3. Set up the database

Option A — Fresh install (recommended): import the complete schema with seed data:

mysql -u root -p respondly < database.sql

Option B — Automated: visit /install.php in your browser after configuring .env. Existing databases are migrated automatically on first request (schema upgrades run in-place — e.g. new payment gateway rows are seeded transparently).

4. Serve the application

# Development
php -S 127.0.0.1:8000 -t public public/index.php

# Production (Apache/Nginx)
# Document root must point to /public — e.g. Nginx:
#   root /var/www/Respondly/public;
#   location / { try_files $uri $uri/ /index.php?$query_string; }

5. Payment gateways

Log in to the admin panel, open Payments, pick any of the 5 global gateways, paste your API keys, click Save & Activate, then use the Test Connection button to verify connectivity before going live.

6. Background jobs

Add these to your crontab (paths adjusted to your installation):

* * * * *  php /var/www/Respondly/cron_queue_worker.php >/dev/null 2>&1
*/15 * * * * php /var/www/Respondly/cron_order_confirmation.php >/dev/null 2>&1
0 * * * *   php /var/www/Respondly/cron_cleanup_logs.php >/dev/null 2>&1

Environment Configuration

Variable Description
APP_URL Public base URL of the app (used to build webhook URLs)
APP_ENV production / development
APP_DEBUG false in production
DB_* MySQL connection (host, name, user, pass, charset)
ENCRYPTION_KEY openssl rand -hex 32 — encrypts stored payment credentials
HTTPS true when served over TLS
REDIS_ENABLED true to enable Redis cache & locks
OPENROUTER_API_KEY LLM routing key for AI features
SMTP_* Outbound transactional mail (password reset, invoices, confirmations)
GOOGLE_CLIENT_ID/SECRET Google OAuth login
META_APP_SECRET Meta (WhatsApp/Facebook) webhook verification
TIKTOK_CLIENT_SECRET TikTok automation webhook verification

Webhooks & API Endpoints

Payment webhooks (signature-verified)

Method Endpoint Notes
POST /api/webhook/stripe Stripe signature verification
POST /api/webhook/paypal PayPal webhook ID verification
POST /api/webhook/adyen HMAC SHA-256 verification
POST /api/webhook/paymob Paymob HMAC verification
POST /api/webhook/fawaterk Fawaterk legacy webhook

Social platform webhooks

Method Endpoint Notes
GET /api/webhook/{platform}/{slug} Platform verification handshake
POST /api/webhook/{platform}/{slug} Inbound message events (WhatsApp, Messenger, Instagram, TikTok)

Customer widget / checkout

Method Endpoint Description
GET/POST /payment/checkout/{id} Hosted invoice checkout
GET /payment/success|failed|pending Payment result pages
POST /api/home-chat Website AI chat endpoint
GET /api/webchat/config Widget configuration
POST /api/webchat/chat Widget conversation
GET /api/webchat/sse Server-Sent Events streaming
GET /api/webchat/poll Message polling (fallback)

Admin payments API

Method Endpoint Access
POST /admin/payments/configure/{code} Super-admin — save provider keys
POST /admin/payments/toggle/{id} Super-admin — enable/disable provider
POST /admin/payments/test/{id} Super-admin — live connectivity test

Background Jobs (Cron)

Script Purpose
cron_queue_worker.php Processes async job queue (email, notifications)
cron_order_confirmation.php Sends order confirmation notifications
cron_cleanup_logs.php Rotates/cleans application logs

Security

  • Credential vault — payment API keys are AES-256-CBC encrypted at rest with an HMAC-authenticated envelope (Security::encrypt/decrypt) and never echoed back in plain text.
  • Webhook integrity — every gateway payload is verified (Stripe signatures, PayPal OAuth verification, Adyen/Paymob HMAC) before any database mutation.
  • Redirect safety — absolute redirects are rebuilt and restricted to safe HTTP(S) targets; javascript:, data:, ftp: and other dangerous schemes are rejected.
  • AuthN/AuthZ — Argon2id password hashing, email verification, 2FA, CSRF tokens on every state-changing request, and role-based middleware (global → staff → super-admin).
  • SQL injection — all queries use PDO prepared statements.

Project Structure

Respondly/
├── config.php                  # Bootstrap: env, autoloader, router wiring
├── database.sql                # Complete schema + seed data
├── install.php                 # Web installer & schema migrator
├── cron_*.php                  # Background jobs
├── public/
│   ├── index.php               # Front controller & route map
│   ├── assets/  widgets/       # Frontend assets & embeddable chat widget
│   └── uploads/ -> storage/    # Uploads symlink
├── src/
│   ├── Core/                   # Router, Request, Response, Database, Security, Logger
│   ├── Controllers/            # 40+ controllers (Auth, AI, CRM, Payments, SEO, ...)
│   ├── Services/               # PaymentGatewayService, integrations, ...
│   ├── Middlewares/            # Auth, CSRF, role guards
│   └── Views/                  # Bilingual templates (admin, business, customer, public)
├── storage/                    # Logs, backups, uploads (git-ignored)
├── tests/                      # PHPUnit suite
├── composer.json               # PSR-4 autoload + dev deps
└── .env.example                # Environment template

Roadmap

  • Global & MENA payment gateways (Stripe, PayPal, Adyen, Paymob, Fawaterk)
  • Vodafone Cash manual-approval flow
  • AI chatbot + website widget with SSE streaming
  • Social platform webhooks (WhatsApp, Messenger, Instagram, TikTok)
  • Multi-currency dynamic pricing per business
  • Public REST API with API keys
  • Two-factor enforcement policy for staff
  • PWA / mobile companion

Contributing

Contributions are welcome! Please open an issue for bugs or feature requests, and submit pull requests against main with a clear description and passing tests.

composer install   # fetch dev deps
vendor/bin/phpunit # run the test suite

License

Released under the MIT License.

Respondly — Talk to your customers, automatically.

About

AI-powered multi-tenant CRM & customer support SaaS platform (PHP 8.3) — AI chatbot, WhatsApp/Messenger/Instagram/TikTok automation, and 6 payment gateways: Stripe, PayPal, Adyen, Paymob, Fawaterk + Cash on Delivery.

Topics

adyenai-chatbotcrmfawaterkmysqlpaymobpaypalphpsaasstripewebhookswhatsapp-api

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages