1. Overview

The Spiro Dashboard is a WhatsApp solution designed to automate and enhance customer interactions. It provides real-time metrics, user input tracking, and geographic targeting to streamline engagement and data management.

Figure 1: Spiro Dashboard interface showing key metrics and controls

Key Features:

24/7 AI-driven customer support via WhatsApp
Real-time lead and conversation tracking
Customizable user inputs for detailed profiling
Consent management for data privacy compliance
Geographic focus on East African markets

Powered by: Ged-I engine

2. Dashboard Components

2.1 Metrics Overview

The dashboard displays real-time KPIs in a clean, glanceable format:

Leads Today

New leads captured in current day
Example: 0

Total Leads

Cumulative leads over time
Example: 0

Conversations

Active customer interactions
Example: 0

Shared to Atlas

Data synced with Atlas system
Example: 0

2.2 Geographic Targeting

Users can filter and analyze data by region:

Kenya
Tanzania
Uganda
Awards (special category)

The checkbox interface allows for multi-select filtering of customer data.

2.3 User Input Tracking

The system captures 57 distinct data fields including:

Demographics (Gender, Salutation)
Identity (National ID, Account Name)
Financial (KDA Account Number)

3. Leads Import Module

Key Functionality

Date-Stamped Imports: Track processing timeline with import date selection
Data Source Identification: Categorize imports by source (e.g., WA Business)
User Management:
- Create new accounts for unrecognized leads
- Update existing user records
WhatsApp Integration: Instant activation of bot interactions for imported leads
CSV File Processing: Bulk upload capability for lead data

Collaboration Features

The system enables seamless coordination between Kings and Atlas Spiro for:

Lead Management: Automated workflow routing between teams
Support Tickets: Integrated resolution system with performance tracking

4. Profile Management

User Profile Components

Section	Description
Profile Header	Displays name, affiliation badges (Spiro/Kings Atlas), and location
Photo Upload	Supports 150×150px JPG/PNG images
Personal Info	Structured fields including contact, availability status, and demographic data

Example Profile Data

Name: Lawrence Isabirye
Contact: 254700715792
Affiliation: Active in Kenya/Nairobi region

5. Customer Type Configuration

Type Classification

Type	Category
Boda Rider	B2C
Corporate Partner	B2B
Government Account	B2G

Status Management

Active/Inactive toggle for each type
Search functionality for quick filtering
Detailed descriptions of privileges

Business Logic

The system distinguishes between:

Regular Customers: Basic purchase privileges
Premium Accounts: Enhanced benefits and offers
Strategic Partners: Custom workflows for B2B/G relationships

6. Bot Input Configuration

Field Management

Attribute	Configuration Options
Latitude (Example Field)	Required: No Sensitivity: Non-sensitive Status: Paused
Unique ID	System-generated identifier
Shareability	Granular control over data sharing permissions

Operational States

Fields can be set to:

Paused: Temporarily inactive
Running: Actively collecting data
Sensitive: Additional security protocols

Spiro WhatsApp BoT API Documentation v1.2.0

This comprehensive documentation provides technical details for integrating with the Spiro WhatsApp conversational platform. The API enables dynamic form handling, multi-step workflows, and intelligent response generation through WhatsApp.

Note: This documentation covers the current production version. Always verify you're working with the latest specifications before implementation.

System Architecture

The Spiro WhatsApp BoT employs a modular, event-driven architecture designed for high availability and scalability:

┌───────────────────────────────────────────────────────────────────────────────┐
│                                WhatsApp Message                               │
└───────────────────────────────┬───────────────────────────────────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                                 API Endpoint                                  │
│                       (Request Validation & Routing)                          │
└───────────────────────────────┬───────────────────────────────────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                                State Manager                                  │
│ (Determines current conversation context and next required actions)           │
└───────────────────────────────┬───────────────┬───────────────────────────────┘
                                │               │
                                ▼               ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────────┐
│  Conversation Init    │ │  Form Processor       │ │  Command Handler          │
│ (New interactions)    │ │ (Field validation &   │ │ (Special functions)       │
│                       │ │  data collection)     │ │                           │
└───────────┬───────────┘ └───────────┬───────────┘ └───────────┬───────────────┘
            │                         │                         │
            └─────────────┬───────────┴─────────────────────────┘
                          │
                          ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                                Response Engine                                │
│ (Generates context-aware responses based on business logic)                   │
└───────────────────────────────┬───────────────────────────────────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────────────────────┐
│                              WhatsApp Integration                             │
│ (Message delivery with read receipts and status tracking)                     │
└───────────────────────────────────────────────────────────────────────────────┘

Core Components

State Management

Maintains conversation context and tracks progress through multi-step workflows with configurable timeouts.

Dynamic Forms

Supports conditional fields, branching logic, and dynamic validation rules based on previous responses.

Validation Engine

Implements comprehensive input sanitization and validation with customizable error messages.

Response Builder

Generates context-aware responses with smart formatting for optimal WhatsApp display.

Integration Layer

Handles all WhatsApp Business API communications with automatic retry logic.

Analytics

Tracks conversation metrics, completion rates, and drop-off points for optimization.

API Endpoints

The system provides a single unified endpoint for all WhatsApp interactions:

POST /api/v1/messages - Primary webhook for inbound and outbound WhatsApp messages

Request Specifications

{
    "api_key": "your_api_key_here",
    "timestamp": "2023-06-15T14:30:00Z",
    "messages": [
        {
            "message_id": "wamid.ABGSV...9JKL=",
            "from": "254700715792",
            "timestamp": "2023-06-15T14:29:58Z",
            "type": "text",
            "content": "Spiro help",
            "context": {
                "replied_to": null,
                "forwarded": false
            },
            "profile": {
                "name": "John Doe",
                "language": "en"
            }
        }
    ]
}

Response Specifications

{
    "status": "success",
    "timestamp": "2023-06-15T14:30:02Z",
    "request_id": "req_7a3b9c8d5e6f",
    "data": {
        "messages": [
            {
                "to": "254700715792",
                "type": "text",
                "content": "Hi John! How may I help you today?",
                "options": [
                    {"id": 1, "text": "Account Support"},
                    {"id": 2, "text": "Product Inquiry"},
                    {"id": 3, "text": "Technical Help"}
                ],
                "metadata": {
                    "session_id": "sess_abc123",
                    "step": "main_menu"
                }
            }
        ]
    }
}

Endpoint Behavior Matrix

User Input	System Action	Response Pattern	State Transition
"Spiro" or "Hi Spiro"	Initializes new session, clears previous state	Main menu with available options	initial → menu
Menu option (1-9)	Loads corresponding workflow	First question in selected flow	menu → form
Valid form input	Stores response, progresses to next field	Next question or confirmation	form → form (or complete)
"0" (back command)	Returns to previous question	Repeats previous question	form → form (previous)
Invalid input	Maintains current position	Error message with requirements	form → form (same)

Pro Tip: The system automatically handles session timeouts after 30 minutes of inactivity, prompting users to restart their conversation.

Authentication

Secure API access is enforced through JWT (JSON Web Tokens) with the following requirements:

Authentication: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Authentication Flow

1. Client requests API key from admin portal
2. System generates JWT with:
   - API key identifier
   - Issued timestamp
   - Expiration (default 90 days)
3. Client includes token in Authorization header
4. Server validates:
   - Signature
   - Expiration
   - API key permissions
5. Access granted or denied with appropriate status code

Security Notice: API keys should be rotated quarterly and immediately revoked if compromised. Never embed keys in client-side code or public repositories.

Data Storage

The system employs a structured approach to data persistence with multiple storage tiers:

Data Lifecycle Management

┌───────────────────────┐   ┌───────────────────────┐   ┌───────────────────────┐
│                       │   │                       │   │                       │
│    Active Sessions    │ → │   Completed Forms     │ → │     Archived Data     │
│   (Real-time access)  │   │  (30-day retention)   │   │  (1-year retention)   │
│                       │   │                       │   │                       │
└───────────────────────┘   └───────────────────────┘   └───────────────────────┘

Data Structure Specifications

Component	Fields	Description	Encryption
User Profile	phone, name, locale, preferences	Basic user information	AES-256
Session State	current_flow, step, last_activity	Conversation progress	None
Form Data	responses, timestamps, metadata	User-provided information	AES-256
Message Logs	content, direction, status	Communication audit trail	None

Compliance: All personal data is encrypted at rest using industry-standard AES-256 encryption. The system supports GDPR right-to-erasure requests through the admin portal.

Input Validation

The validation engine supports multiple validation types with customizable rules and error messages:

Validation Type Matrix

Type	Description	Parameters	Error Example
`text`	General text input	min_len, max_len, regex	"Name must be 2-100 characters"
`numeric`	Number validation	min, max, decimal	"Please enter a number between 1-100"
`email`	Email format	domain_whitelist	"Enter a valid email address"
`phone`	Phone number	country_code	"Include country code (e.g. 254...)"
`selection`	Predefined options	options[], multi_select	"Choose from available options"

Validation Process Flow

┌───────────────────────┐   ┌───────────────────────┐   ┌───────────────────────┐
│                       │   │                       │   │                       │
│   Receive User Input  │ → │  Apply Sanitization   │ → │  Validate Against     │
│                       │   │      Rules            │   │     Criteria          │
└───────────┬───────────┘   └───────────┬───────────┘   └───────────┬───────────┘
            │                           │                           │
            ▼                           ▼                           ▼
┌───────────────────────┐   ┌───────────────────────┐   ┌───────────────────────┐
│                       │   │                       │   │                       │
│   Store Raw Input     │   │  Transform Cleaned    │   │  Return Validation    │
│   for Audit           │   │    Value              │   │     Result            │
│                       │   │                       │   │                       │
└───────────────────────┘   └───────────────────────┘   └───────────────────────┘

Message Flow Handling

The conversation engine manages complex workflows with configurable rules:

State Transition Diagram

┌───────────────┐   "start"   ┌─────────────────┐   select   ┌─────────────────┐
│               │─────────────▶│                 │───────────▶│                 │
│   Initial     │             │    Main Menu    │            │  Form Flow      │
│               │◁─────────────│                 │◁───────────│                 │
└───────────────┘   "reset"   └────────┬────────┘   "back"   └────────┬────────┘
                                       │                              │
                                       │ complete                     │
                                       ▼                              │
                            ┌─────────────────┐              invalid │
                            │                 │◁──────────────────────┘
                            │  Completion    │
                            │                 │
                            └─────────────────┘

Flow Control Features

Conditional Branching

Show different questions based on previous answers using if-then-else logic.

Dynamic Field Order

Rearrange question sequence based on real-time responses.

Multi-Page Forms

Split long forms across multiple messages with progress tracking.

Session Recovery

Resume interrupted conversations from last completed step.

Implementation Examples

Basic Integration

// Example: Handling incoming message
function handleMessage(message) {
    // Verify authentication
    if (!validateAuth(message.api_key)) {
        return errorResponse(401, "Invalid API key");
    }
    
    // Process each message
    message.messages.forEach(msg => {
        // Get current conversation state
        const state = getConversationState(msg.from);
        
        // Route to appropriate handler
        switch(state.step) {
            case 'initial':
                showMainMenu(msg.from);
                break;
            case 'menu':
                handleMenuSelection(msg.from, msg.content);
                break;
            case 'form':
                processFormInput(msg.from, msg.content, state);
                break;
        }
    });
    
    return successResponse();
}

Form Processing Logic

// Example: Form input handler
function processFormInput(userId, input, state) {
    // Handle navigation commands
    if (input === '0') {
        return goBackToPreviousQuestion(userId, state);
    }
    
    // Get current field validation rules
    const field = state.current_field;
    const rules = getValidationRules(field);
    
    // Validate input
    const validation = validateInput(input, rules);
    
    if (!validation.valid) {
        return sendValidationError(userId, field, validation.message);
    }
    
    // Store valid response
    saveResponse(userId, field, validation.cleanValue);
    
    // Determine next step
    const nextStep = calculateNextStep(state);
    
    if (nextStep) {
        sendQuestion(userId, nextStep);
        updateState(userId, { current_field: nextStep });
    } else {
        completeForm(userId);
        updateState(userId, { step: 'complete' });
    }
}

Error Handling

The system provides comprehensive error handling with detailed feedback:

Error Response Structure

{
    "status": "error",
    "timestamp": "2023-06-15T14:35:12Z",
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "Invalid email format",
        "details": {
            "field": "email",
            "requirements": "Must be a valid email address",
            "provided": "user@example"
        },
        "request_id": "req_123456789"
    }
}

Common Error Codes

Code	HTTP Status	Description	Resolution
AUTH_REQUIRED	401	Missing or invalid API key	Provide valid authentication
VALIDATION_FAILED	400	Input validation error	Correct input format
RATE_LIMITED	429	Too many requests	Wait or increase quota
SESSION_EXPIRED	410	Conversation timeout	Restart conversation

Rate Limiting

The API implements tiered rate limiting to ensure fair usage:

┌───────────────────────┐   ┌───────────────────────┐   ┌───────────────────────┐
│                       │   │                       │   │                       │
│   User-Level Limits   │ → │  Application-Level   │ → │    Global Limits      │
│   (30/min per user)   │   │     (100/min)        │   │    (5,000/request)    │
│                       │   │                       │   │                       │
└───────────────────────┘   └───────────────────────┘   └───────────────────────┘

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1686844800
Retry-After: 60

Implementation Tip: Always check rate limit headers and implement exponential backoff when approaching limits to avoid service interruptions.

Security Considerations

The system incorporates multiple security layers to protect data and ensure privacy:

Security Architecture

┌───────────────────────┐   ┌───────────────────────┐   ┌───────────────────────┐
│                       │   │                       │   │                       │
│   Transport Security  │ → │   Data Encryption    │ → │  Access Control       │
│   (TLS 1.2+)          │   │   (AES-256)          │   │  (RBAC)               │
│                       │   │                       │   │                       │
└───────────┬───────────┘   └───────────┬───────────┘   └───────────┬───────────┘
            │                           │                           │
            ▼                           ▼                           ▼
┌───────────────────────┐   ┌───────────────────────┐   ┌───────────────────────┐
│                       │   │                       │   │                       │
│   Input Sanitization  │ → │   Audit Logging      │ → │  Regular Pentests     │
│                       │   │                       │   │                       │
└───────────────────────┘   └───────────────────────┘   └───────────────────────┘

Security Best Practices

Always use HTTPS - All API requests must use TLS encryption
Rotate keys quarterly - Regular key rotation limits exposure
Principle of least privilege - Grant minimum necessary permissions
Validate all inputs - Never trust client-side validation
Monitor for anomalies - Implement real-time alerting

Implementation Best Practices

Follow these guidelines for optimal integration:

Client-Side Recommendations

Exponential Backoff

Implement with jitter for rate limit handling to avoid thundering herd problems.

Connection Pooling

Maintain persistent connections to reduce latency and improve throughput.

Request Batching

Combine multiple operations in single requests where possible.

Idempotency Keys

Use for critical operations to enable safe retries.

Performance Optimization

Technique	Implementation	Benefit
Caching	Cache frequent responses with appropriate TTLs	Reduces API calls and latency
Compression	Enable gzip for large payloads	Reduces bandwidth usage
Parallelism	Process independent requests concurrently	Improves throughput
Pagination	Use cursor-based pagination for large datasets	Reduces memory pressure

Production Checklist:

Implement proper monitoring and alerting
Document your integration architecture
Establish rollback procedures
Test under load before deployment
Schedule regular security reviews

Copied to clipboard!