# Converzo Platform Architecture & Full Technical Documentation > Converzo is an Enterprise WhatsApp Business messaging platform and AI CRM engine. This document provides complete technical specifications, architecture overview, API protocols, webhook event schema, parse modes, and security standards for AI models and developers. - Public Website: https://getconverzo.in - Application HQ: https://app.getconverzo.in - API Base URL: https://app.getconverzo.in/converzo/api --- ## 1. System Overview & Product Architecture Converzo connects to Meta's official WhatsApp Business Cloud API. It provides a multi-tenant environment with tenant isolation, workspace RBAC, rate limiting, and database-backed asynchronous message queuing via Celery & Redis. ### Architectural Modules: 1. **Engine Core**: Webhook ingestion, incoming message parsing, template management, and automated status handling (sent, delivered, read, failed). 2. **AI Brain (RAG)**: Knowledge vector stores, context retrievability, prompt templates, fallback routing to human desk, and session management. 3. **Smart Router**: Rule engine matching incoming webhook triggers or API calls to pre-approved WhatsApp templates. 4. **Flows Authoring**: Drag-and-drop builder for native WhatsApp interactive screens, JSON submission handlers, and field validation. 5. **Drip Engine**: Automated sequence scheduler executing multi-step messaging workflows based on delay rules and user engagement triggers. 6. **Commerce Suite**: Native webhook listeners for Shopify & WooCommerce catalog sync, checkout events, and automated notification triggers. 7. **Multi-Agent Desk**: Real-time WebSocket live chat inbox with internal chat, agent assignment, team tagging, and macro responses. --- ## 2. Trigger API Reference The Trigger API allows external CRMs, e-commerce platforms, payment gateways, and backend systems to fire WhatsApp messages via keywords. ### Base Configuration - Base URL: `https://app.getconverzo.in/converzo/api` - Authentication Header: `Authorization: Bearer ` - Alternate Authentication: `?token=` or `?api_key=` --- ### Endpoint: GET /converzo/api/rules Returns all configured keyword rules, approved template placeholders, parse modes, and required variable counts for the authenticated account. #### Curl Request: ```bash curl -X GET https://app.getconverzo.in/converzo/api/rules \ -H "Authorization: Bearer cvz_live_xxxx" ``` #### Example JSON Response: ```json { "rules": [ { "keyword": "order_update", "keywords": ["order_update"], "template_name": "order_status_update", "template_language": "en_US", "template_approved": true, "parse_mode": "split_comma", "parse_mode_help": "Values are comma-separated after the keyword, in template order.", "variable_count": 3, "placeholders": ["{{1}}", "{{2}}", "{{3}}"], "variables": [ {"label": "{{1}}", "kind": "numbered", "token": "{{1}}", "hint": "Hi {{1}}, order {{2}} is now {{3}}."} ], "body": "Hi {{1}}, order {{2}} is now {{3}}.", "example": "order_update, value1, value2, value3", "example_request": { "number": "919876543210", "message": "order_update, value1, value2, value3" }, "warnings": [] } ], "templates": [ { "name": "payment_receipt", "language": "en_US", "category": "UTILITY", "body": "Receipt {{1}} for {{2}}.", "variable_count": 2, "placeholders": ["{{1}}", "{{2}}"], "routed_by": [] } ], "parse_modes": { "split_comma": "Values separated by comma.", "split_pipe": "Values separated by pipe (|).", "auth_digits": "Digits extracted automatically (OTP).", "full_text": "Entire text after keyword becomes one variable." }, "send_endpoint": "/converzo/api/send" } ``` --- ### Endpoint: POST /converzo/api/send Sends a message via keyword rule matching. #### Parameters: - `number` (string, required): Phone number with country code, no leading `+` (e.g. `919876543210`). - `message` (string, required): Trigger message string starting with matched keyword, followed by delimited variables. - `token` (string, optional): API key if header omitted. #### Request Example (JSON): ```bash curl -X POST https://app.getconverzo.in/converzo/api/send \ -H "Authorization: Bearer cvz_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "number": "919876543210", "message": "order_update, Rahul, ORD-2026-001, Shipped" }' ``` #### Success Response: ```json { "status": "success", "queued_for": "919876543210", "source": "smart_router", "logic": "split_comma" } ``` #### Ignored Keyword Response: ```json { "status": "ignored", "message": "No matching keyword found" } ``` --- ## 3. Parse Modes & Variable Extraction | Parse Mode | Description | Example Message Input | Extracted Variables | |---|---|---|---| | `split_comma` | Segments separated by commas `,` | `order_update, Rahul, ORD-99` | `Var1: Rahul`, `Var2: ORD-99` | | `split_pipe` | Segments separated by pipe `\|` | `invoice\|Rahul\|https://x.in/a.pdf` | `Var1: Rahul`, `Attachment: PDF URL` | | `auth_digits` | Extracts numerical OTP codes | `otp 482913` | `Var1: 482913` | | `full_text` | Treats remainder as single text | `welcome Welcome to our platform!` | `Var1: Welcome to our platform!` | --- ## 4. Outbound Webhooks & Security Verification Converzo pushes real-time event notifications to customer-configured webhook URLs (`/app/settings/webhooks`). ### Event Catalog: - `message.received`: Incoming customer WhatsApp message. - `message.sent`: Message dispatched to WhatsApp API. - `message.delivered`: Message delivered to recipient phone. - `message.read`: Recipient read receipt. - `message.failed`: Delivery failure with error code. - `contact.opted_out`: Customer sent STOP / unsubscribe keyword. - `campaign.auto_paused`: Campaign safety threshold reached. ### Headers Sent With Webhook Delivery: - `X-Converzo-Event`: Event name (e.g. `message.delivered`) - `X-Converzo-Timestamp`: Epoch timestamp in seconds. - `X-Converzo-Signature`: HMAC-SHA256 signature calculated over `{timestamp}.{raw_body}` using your webhook secret. ### Verification Code (Python): ```python import hmac import hashlib def verify_converzo_webhook(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool: payload = f"{timestamp}.".encode('utf-8') + raw_body expected_sig = hmac.new(secret.encode('utf-8'), payload, hashlib.sha256).hexdigest() return hmac.compare_digest(expected_sig, signature) ``` --- ## 5. Error Code Matrix | Status Code | Reason | Resolution | |---|---|---| | 200 `status:success` | Message queued successfully | Message will be dispatched within seconds | | 200 `status:ignored` | No keyword matched in message | Verify active keywords via `GET /rules` | | 400 Bad Request | Missing number or variable count mismatch | Check phone number formatting and parse mode | | 401 Unauthorized | Missing or invalid API key | Generate valid key at `/app/api-keys` | | 403 Forbidden | Plan gate restricted | Upgrade plan to enable API access | | 429 Too Many Requests | Rate limit exceeded (30 req/min) | Implement exponential backoff | | 500 Server Error | Internal processing error | Retry with backoff | --- ## 6. Target Use Cases & Industry Solutions - **E-Commerce & D2C**: Abandoned cart recovery, order dispatch alerts, COD verification, interactive product catalog sharing. - **Healthcare & Clinics**: Automated appointment booking, lab report delivery, visit reminders, post-care follow-ups. - **Education & EdTech**: Student lead qualification via WhatsApp Flows, instant brochure delivery, fee payment reminders, class schedules. - **Real Estate**: Instant lead response, site visit booking, automated brochure delivery, drip property nurturing. - **Restaurants & Food**: QR-code table opt-ins, promotional broadcast offers, reservation & order status updates. - **Finance & Insurance**: Payment & EMI due reminders, document collection workflows, utility OTP verification. - **Travel & Hospitality**: Instant booking confirmations, itinerary distribution, check-in & tour reminders. - **Salons, Spas & Beauty**: Appointment scheduling, visit reminders, post-service feedback collection. - **Fitness & Gyms**: Membership renewal reminders, class slot booking, workout plan delivery. - **Automotive & Dealerships**: Test drive booking, service due reminders, vehicle status updates. - **Logistics & Delivery**: Real-time package tracking updates, dispatch notifications, delivery slot confirmations. - **SaaS & B2B Agencies**: Instant lead response, API OTP delivery, multi-agent support desk escalation. - **ISP & Broadband**: Plan-expiry and due-date reminders with one-tap payment links, area-wide outage notices, complaint/ticket intake, technician-visit scheduling, speed-upgrade upsells. Covers regional broadband and fibre ISPs, local cable operators (LCOs), cable TV and DTH. - **Subscriptions & Home Utilities**: Service-due, refill and renewal reminders with payment links; delivery slot confirmations. Covers water purifier/RO and AMC services, LPG and gas agencies, dairy, milk and water-can delivery, laundry subscriptions, housing societies and RWAs. - **Immigration & Study Abroad**: Document checklists, counselling-slot booking, application status updates, intake-deadline broadcasts. - **Recruitment & Staffing**: Candidate outreach and screening, interview reminders, onboarding document collection, job-opening broadcasts. - **Agriculture & Agri-Input**: Season-timed offer broadcasts, dealer order and dispatch updates, crop-cycle advisory drips. - **NGOs, Trusts & Communities**: Donation appeals with payment links and receipts, event and camp notices, volunteer shift reminders. - **Events, Weddings & Photography**: Enquiry capture bots, quote follow-ups, shoot and delivery milestone updates. - **Manufacturing, Export & Freight**: Quote and proforma follow-ups, shipment milestone updates, document chase, distributor broadcasts. Covers MSME exporters, freight forwarders and customs brokers. - **Local Services & Repair**: Job-status and ready-for-pickup alerts, technician scheduling, AMC and contract renewals. Covers repair and authorised service centres, facility management and security, driving schools, taxi fleets and car rental, printing and packaging, IT/MSP. --- ## 7. Official Contact & Links - Main Platform: https://app.getconverzo.in - Public Website: https://getconverzo.in - Demo Booking: https://app.getconverzo.in/demo - Growth Consultation: https://app.getconverzo.in/growth-plan - Support Email: support@getconverzo.in