> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Mahalaxmi - Integrations

> WhatsApp, payments, storage, AI, and other external services

## WhatsApp — Gupshup (Primary)

The main WhatsApp integration. Most production users go through Gupshup.

* **API client:** `shared/gupshup.ts`
* **Incoming message webhook:** `POST /api/webhooks/gupshup/incoming_msg`
* **Message events webhook (delivery/read):** `POST /api/webhooks/gupshup/message-events`
* **Required env:** `GUPSHUP_WEBHOOKS_BASE_URL`
* **Update webhooks script:** `npx tsx server/scripts/update-gupshup-subscription.ts`

Supports: text, media, location, authentication, and interactive button templates.

## WhatsApp — Wasimple

Alternative WhatsApp integration.

* **API client:** `shared/wasimple.ts`
* **Webhook endpoint:** `POST /api/webhook/wasimple?user_id=X&bot_id=Y`
* **Required env:** `WASIMPLE_API_KEY`, `WASIMPLE_PHONE_ID`
* **Dev tip:** Set `WASIMPLE_AI_AGENT_RESPONSE_ALLOW_ALL=true` to skip phone number whitelisting

## WhatsApp — Facebook / Meta

* **Endpoints:**
  * `GET /api/webhook/facebook` — verification challenge
  * `POST /api/webhook/facebook` — incoming messages
  * `POST /api/facebook/auth-callback` — OAuth callback
* **Required env:** `FACEBOOK_APP_ID`, `FACEBOOK_APP_SECRET`, `FACEBOOK_WEBHOOK_VERIFY_TOKEN`, `FACEBOOK_REDIRECT_URI`

## Authentication — JWT

* Access tokens: 1 hour expiry, stored in HTTP-only cookies
* Refresh tokens: 30 days, stored in HTTP-only cookies
* Protected routes use `jwtAuth.requireAuth` middleware
* On expiry: client calls `POST /api/auth/refresh`
* **API token auth:** Users can generate an API token stored in `users.api_token`. Pass as `Authorization: Bearer <token>` or `x-api-token` header.

## Payments — Stripe

* **Webhook:** `POST /api/stripe-webhook` (requires raw body — do not parse as JSON)
* **Required env:** `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PRICE_ID`
* **Events handled:** `invoice.payment_succeeded`, `invoice.payment_failed`, `customer.subscription.updated`, `customer.subscription.deleted`
* **API version:** `2025-05-28.basil`

## Payments — Cashfree

Alternative payment gateway for Indian users.

* **Required env:** `CASHFREE_APP_ID`, `CASHFREE_SECRET_KEY`, `CASHFREE_WEBHOOK_SECRET`

## Cloud Storage — AWS S3

Used for media uploads and training files.

* **Helpers:** `server/storage.ts` — `uploadToS3`, `deleteFromS3`, `getS3Object`, `validateImageFile`
* **Required env:** `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `S3_BUCKET_NAME`

## AI / LLM

| Service                                   | Purpose                        | Env key                        |
| ----------------------------------------- | ------------------------------ | ------------------------------ |
| Google Gemini (`@langchain/google-genai`) | Text generation + embeddings   | `GOOGLE_API_KEY`               |
| OpenAI (`@langchain/openai`)              | Embeddings (fallback)          | `OPENAI_API_KEY`               |
| Qdrant                                    | Vector search (RAG)            | `QDRANT_URL`, `QDRANT_API_KEY` |
| LangChain                                 | RAG orchestration, agent flows | —                              |

**RAG pipeline:**

1. Upload PDF or URL → stored in `training_files` / `training_urls`
2. Run `processTrainingFiles.ts` or `processTrainingUrls.ts` → chunks embedded → stored in Qdrant
3. On bot message → `vectorSearch.ts` queries Qdrant → relevant chunks injected into prompt

**Init Qdrant collection:**

```bash theme={null}
npx tsx server/scripts/createQdrantCollection.ts
```

## Redis / Cache

* **Local (Docker):** `redis://localhost:6380`
* **Production (Upstash):** Set `REDIS_HOST` to Upstash HTTPS URL and `REDIS_TOKEN` to the auth token

## OAuth Providers

| Provider | Env keys                                   |
| -------- | ------------------------------------------ |
| Google   | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |
| Twitter  | `TWITTER_API_KEY`, `TWITTER_API_SECRET`    |
| Facebook | `FACEBOOK_APP_ID`, `FACEBOOK_APP_SECRET`   |

Redirect base URL is controlled by `API_URL`.

## Other Integrations

| Service               | Library          | Env key                       |
| --------------------- | ---------------- | ----------------------------- |
| Airtable              | `airtable`       | `AIRTABLE_API_KEY`            |
| Slack                 | `@slack/web-api` | via credentials table         |
| Google (Gmail, Drive) | `googleapis`     | via OAuth / credentials table |