Ping Dart API Documentation

Message APIs

Send, forward, and manage messages

POST /chat/send-message Auth Required

Send a message to chat or group

Request Body

{
  "chat_id": "uuid",
  "message": "Hello, this is a message",
  "message_type": "text", // text, image, video, audio, document, location
  "media_url": "url-if-media",
  "reply_to": "message_id" // optional
}
        

Response (200 OK)

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "message_id": "uuid",
    "chat_id": "uuid",
    "message": "Hello, this is a message",
    "created_at": "2025-01-15T10:30:00Z"
  }
}
        

POST /chat/forward-message Auth Required

Forward message to other chats

Request Body

{
  "message_id": "uuid",
  "chat_ids": ["chat_id_1", "chat_id_2"]
}
        

POST /chat/star-unstar-message Auth Required

Star or unstar a message

Request Body

{
  "message_id": "uuid",
  "is_starred": true
}
        

POST /chat/pin-unpin-message Auth Required

Pin or unpin a message

Request Body

{
  "message_id": "uuid",
  "is_pinned": true
}
        

POST /chat/vote-poll Auth Required

Vote on a poll message

Request Body

{
  "message_id": "uuid",
  "poll_option": "option_1"
}
        

POST /chat/starred-messages Auth Required

Get all starred messages

Response (200 OK)

{
  "success": true,
  "data": {
    "messages": [
      {
        "message_id": "uuid",
        "message": "Starred message text",
        "chat_id": "uuid",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ]
  }
}
        

Story APIs

Manage user stories and status updates

POST /story/upload-story Auth Required

Upload a new story

Request Body

{
  "media_type": "image", // image, video
  "media_url": "base64-or-url",
  "caption": "Story caption"
}
        

Response (200 OK)

{
  "success": true,
  "message": "Story uploaded successfully",
  "data": {
    "story_id": "uuid",
    "media_url": "url",
    "expires_at": "2025-01-16T10:30:00Z"
  }
}
        

DELETE /story/remove-story Auth Required

Remove a story

Request Body

{
  "story_id": "uuid"
}
        

POST /story/get-story Auth Required

Get a specific story

Request Body

{
  "story_id": "uuid"
}
        

GET /story/get-stories Auth Required

Get all stories from contacts

Response (200 OK)

{
  "success": true,
  "data": {
    "stories": [
      {
        "story_id": "uuid",
        "user_id": "uuid",
        "media_url": "url",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ]
  }
}
        

PUT /story/view-story Auth Required

Mark story as viewed

Request Body

{
  "story_id": "uuid"
}
        

Call APIs

Manage voice and video calls

POST /call/make-call Auth Required

Initiate a voice or video call

Request Body

{
  "chat_id": "uuid",
  "call_type": "voice", // voice, video
  "participants": ["user_id_1", "user_id_2"]
}
        

Response (200 OK)

{
  "success": true,
  "message": "Call initiated",
  "data": {
    "call_id": "uuid",
    "call_type": "voice",
    "status": "ringing"
  }
}
        

Dynamic Query APIs

Powerful database APIs supporting PostgreSQL, MySQL, MongoDB, and JSON DB

GET /dynamicQuery

Get all available dynamic query endpoints

Response (200 OK)

{
  "success": true,
  "message": "Dynamic Query API - Available Endpoints",
  "endpoints": {
    "CRUD Operations": [...],
    "Table Management": [...],
    "Database Management": [...]
  }
}
        

POST /dynamicQuery/dynamicRead

Advanced dynamic read API with support for conditions, search, margedata (joins), location filtering, pagination, and ordering. Supports MySQL, PostgreSQL, MongoDB, and JSON DB.

Base Request Structure

Request Body

{
  "tableName": "users",
  "databaseid": "db-123",
  "conditions": {},
  "search": {},
  "pagination": {},
  "orderBy": "",
  "margedata": [],
  "range": {}
}
        

Required Parameters:

tableName (string) - Name of the table to query
databaseid (string) - Database ID (empty string "" for default database)

Optional Parameters:

conditions (object) - Filter conditions
search (object) - Search across multiple fields
pagination (object) - Pagination settings
orderBy (string) - SQL ORDER BY clause
margedata (array) - Merge/join related tables
range (object) - Location-based filtering

1. Conditions

Filter records using various operators and data types.

Basic Conditions

{
  "tableName": "users",
  "databaseid": "db-123",
  "conditions": {
    "status": "active",
    "age": 25
  }
}
        

SQL: WHERE status = 'active' AND age = 25

NOT EQUAL Condition

{
  "conditions": {
    "status": "!inactive"
  }
}
        

SQL: WHERE status != 'inactive'

IN Condition (Array Values)

{
  "conditions": {
    "status": ["active", "pending", "approved"],
    "category_id": [1, 2, 3, 5]
  }
}
        

SQL: WHERE status IN ('active', 'pending', 'approved') AND category_id IN (1, 2, 3, 5)

BETWEEN Condition

{
  "conditions": {
    "age": {
      "start": 18,
      "end": 65
    },
    "price": {
      "min": 100,
      "max": 1000
    },
    "created_at": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    }
  }
}
        

SQL: WHERE age BETWEEN 18 AND 65 AND price BETWEEN 100 AND 1000

2. Search Functionality

Perform LIKE queries across multiple fields simultaneously. Search uses OR logic between fields.

Basic Search

{
  "search": {
    "name": "john",
    "email": "gmail"
  }
}
        

SQL: WHERE (name LIKE '%john%' OR email LIKE '%gmail%')

Note: PostgreSQL uses ILIKE (case-insensitive), MySQL uses LIKE (case-sensitive)

Search with Arrays (IN Condition)

{
  "search": {
    "status": ["active", "pending"],
    "category": [1, 2, 3]
  }
}
        

SQL: WHERE (status IN ('active', 'pending') OR category IN (1, 2, 3))

3. Margedata (Join/Merge)

Merge/join related tables and fetch related data efficiently using batch queries.

Basic Margedata Structure

{
  "target_table": "related_table_name",
  "target_column": "foreign_key_column",
  "target_value": "parent_table_id_column",
  "target_label": "property_name_in_response",
  "search_fields": [],
  "margedata": []
}
        

Example: Simple One-to-Many Join

Request

{
  "tableName": "users",
  "databaseid": "db-123",
  "margedata": [
    {
      "target_table": "orders",
      "target_column": "user_id",
      "target_value": "id",
      "target_label": "orders"
    }
  ]
}
        

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "orders": [
        { "id": 101, "user_id": 1, "total": 100 },
        { "id": 102, "user_id": 1, "total": 200 }
      ]
    }
  ]
}
        

Example: Nested Margedata (Multi-level Joins)

{
  "tableName": "users",
  "databaseid": "db-123",
  "margedata": [
    {
      "target_table": "orders",
      "target_column": "user_id",
      "target_value": "id",
      "target_label": "orders",
      "margedata": [
        {
          "target_table": "order_items",
          "target_column": "order_id",
          "target_value": "id",
          "target_label": "items"
        }
      ]
    }
  ]
}
        

4. Range (Location Filtering)

Filter records based on geographic location using latitude and longitude.

Location Filter Example

{
  "tableName": "users",
  "databaseid": "db-123",
  "range": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "radius": 10,
    "target_latitude": "latitude",
    "target_longitude": "longitude"
  }
}
        

Range Parameters:

latitude (number) - Center point latitude
longitude (number) - Center point longitude
radius (number) - Radius in kilometers
target_latitude (string) - Column name for latitude
target_longitude (string) - Column name for longitude

Note: Only supports MySQL and PostgreSQL. Valid column names: lat, latitude, user_lat, location_lat, lng, longitude, user_lon, location_lon

5. Pagination

{
  "tableName": "users",
  "databaseid": "db-123",
  "pagination": {
    "page": 1,
    "limit": 20
  }
}
        

6. Order By

{
  "tableName": "users",
  "databaseid": "db-123",
  "orderBy": "created_at DESC, name ASC"
}
        

Complete Example: Complex Query with All Features

Request

{
  "tableName": "users",
  "databaseid": "db-123",
  "conditions": {
    "status": "active",
    "age": {
      "start": 18,
      "end": 65
    },
    "city": ["New York", "Los Angeles"],
    "is_verified": "!false"
  },
  "search": {
    "name": "john",
    "email": "gmail"
  },
  "range": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "radius": 10,
    "target_latitude": "latitude",
    "target_longitude": "longitude"
  },
  "pagination": {
    "page": 1,
    "limit": 20
  },
  "orderBy": "created_at DESC",
  "margedata": [
    {
      "target_table": "orders",
      "target_column": "user_id",
      "target_value": "id",
      "target_label": "orders",
      "margedata": [
        {
          "target_table": "order_items",
          "target_column": "order_id",
          "target_value": "id",
          "target_label": "items"
        }
      ]
    },
    {
      "target_table": "addresses",
      "target_column": "user_id",
      "target_value": "id",
      "target_label": "addresses"
    }
  ]
}
        

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "orders": [
        {
          "id": 101,
          "user_id": 1,
          "total": 100,
          "items": [
            { "id": 1, "order_id": 101, "product": "Widget" }
          ]
        }
      ],
      "addresses": [
        { "id": 1, "user_id": 1, "street": "123 Main St" }
      ]
    }
  ],
  "totalCount": 150,
  "totalPages": 8,
  "_performance": {
    "executionTime": "45ms",
    "recordsReturned": 20,
    "totalRecords": 150
  }
}
        

Error Responses

Missing Table Name

{
  "success": false,
  "error": "Missing tableName or tableSchema"
}
        

Table Not Found

{
  "success": false,
  "error": "Table 'users' not found"
}
        

Database Type Support

Feature	MySQL	PostgreSQL	MongoDB	JSON
Conditions	✅	✅	✅	✅
Search	✅	✅	✅	✅
Margedata	✅	✅	✅	✅
Range	✅	✅	❌	❌
Pagination	✅	✅	✅	✅
Order By	✅	✅	✅	✅

POST /dynamicQuery/dynamicCreate

Create records in database. Supports all database types.

Request Body

{
  "tableName": "users",
  "databaseid": "db_uuid",
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "status": "active"
  },
  "conditions": {
    "email": "john@example.com"
  }
}
        

Response (200 OK)

{
  "success": true,
  "message": "Record created successfully",
  "insertedData": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}
        

POST /dynamicQuery/dynamicUpdate

Update records in database. Supports all database types.

Request Body

{
  "tableName": "users",
  "databaseid": "db_uuid",
  "data": {
    "status": "inactive",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "conditions": {
    "id": 1
  }
}
        

Response (200 OK)

{
  "success": true,
  "message": "Record updated successfully",
  "affectedRows": 1
}
        

POST /dynamicQuery/dynamicDelete

Delete records from database. Supports all database types.

Request Body

{
  "tableName": "users",
  "databaseid": "db_uuid",
  "conditions": {
    "id": 1
  }
}
        

Response (200 OK)

{
  "success": true,
  "message": "Record deleted successfully",
  "affectedRows": 1
}
        

POST /dynamicQuery/dynamicCount

Count records in database

Request Body

{
  "tableName": "users",
  "databaseid": "db_uuid",
  "conditions": {
    "status": "active"
  }
}
        

Response (200 OK)

{
  "count": 50
}
        

POST /dynamicQuery/dynamicTableCreate

Create table dynamically. Supports PostgreSQL, MySQL, MongoDB, and JSON DB.

Request Body

{
  "tableName": "products",
  "databaseid": "db_uuid",
  "columns": {
    "id": "SERIAL PRIMARY KEY",
    "name": "VARCHAR(255)",
    "price": "DECIMAL(10,2)",
    "created_at": "TIMESTAMP DEFAULT CURRENT_TIMESTAMP"
  }
}
        

Response (200 OK)

{
  "success": true,
  "message": "Table created successfully",
  "tableName": "products"
}
        

POST /dynamicQuery/createDatabase

Create a new database. Supports PostgreSQL, MySQL, MongoDB, and JSON DB.

Request Body

{
  "db_name": "my_database",
  "db_type": "postgres",
  "server": "localhost",
  "db_port": 5432
}
        

Response (200 OK)

{
  "success": true,
  "message": "Database created successfully",
  "databaseid": "db-uuid-here"
}
        

POST /dynamicQuery/deleteDatabase

Delete a database. Supports PostgreSQL, MySQL, MongoDB, and JSON DB.

Request Body

{
  "databaseid": "db_uuid"
}
        

Response (200 OK)

{
  "success": true,
  "message": "Database deleted successfully"
}
        

POST /dynamicQuery/createDatabaseUser

Create a database user

Request Body

{
  "db_username": "dbuser",
  "password": "secure_password",
  "db_type": "postgres"
}
        

POST /dynamicQuery/changeDatabaseUserPassword

Change database user password

Request Body

{
  "user_id": "user_uuid",
  "new_password": "new_secure_password"
}
        

POST /dynamicQuery/connectUserToDatabase

Connect user to database with privileges

Request Body

{
  "user_id": "user_uuid",
  "database_id": "db_uuid",
  "privileges": ["SELECT", "INSERT", "UPDATE"]
}
        

POST /dynamicQuery/deleteUser

Delete a database user

Request Body

{
  "user_id": "user_uuid"
}
        

POST /dynamicQuery/getAllTables

Get all tables in database. Supports PostgreSQL, MySQL, MongoDB, and JSON DB.

Request Body

{
  "databaseid": "db_uuid"
}
        

Response (200 OK)

{
  "success": true,
  "tables": [
    "users",
    "orders",
    "products"
  ]
}
        

POST /dynamicQuery/getTableColumns

Get table columns information. Supports PostgreSQL, MySQL, MongoDB, and JSON DB.

Request Body

{
  "tableName": "users",
  "databaseid": "db_uuid"
}
        

Response (200 OK)

{
  "success": true,
  "columns": [
    {
      "name": "id",
      "type": "INTEGER",
      "nullable": false,
      "primaryKey": true
    },
    {
      "name": "name",
      "type": "VARCHAR(255)",
      "nullable": true
    },
    {
      "name": "email",
      "type": "VARCHAR(255)",
      "nullable": false
    }
  ]
}
        

POST /dynamicQuery/executeSql

Execute raw SQL query. Supports PostgreSQL and MySQL only.

Request Body

{
  "databaseid": "db_uuid",
  "sql": "SELECT * FROM users WHERE status = 'active'"
}
        

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "status": "active"
    }
  ]
}
        

Database Connection APIs

Test database connections and manage database records. Supports MySQL, PostgreSQL, MongoDB, and JSON database types.

POST /test-connection

Test database connection and optionally update database records. Supports both legacy format (MySQL only) and new format (all database types).

Request Body - Format 1: New Format (Recommended - All Database Types)

Request Body

{
  "dbName": "mydatabase",
  "dbUsername": "username",
  "password": "password123",
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "databaseid": "optional-existing-db-id"
}
        

Required Fields:

dbName (string) - Database name
dbUsername (string) - Database username
password (string) - Database password
dbType (string) - Database type: mysql, postgres, mongodb, json
host (string) - Database host/IP address
port (number) - Database port number

Optional Fields:

databaseid (string) - If provided, updates existing database record

Request Body - Format 2: Legacy Format (MySQL Only - Backward Compatible)

Request Body

{
  "ip": "localhost",
  "username": "root",
  "password": "password123",
  "dbName": "mydatabase",
  "databaseid": "optional-existing-db-id"
}
        

Required Fields:

ip (string) - Database host/IP address
username (string) - Database username
dbName (string) - Database name

Optional Fields:

password (string) - Required for remote connections (not required for localhost)
databaseid (string) - If provided, updates existing database record

Response (200 OK) - Success

{
  "success": true,
  "message": "Connection successful",
  "data": {
    "database": {
      "db_name": "mydatabase",
      "server": "localhost",
      "db_port": 3306,
      "db_type": "mysql",
      "database_type": "mysql"
    },
    "user": {
      "db_username": "username",
      "password": "password123"
    },
    "connectionInfo": {
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "database": "mydatabase"
    }
  }
}
        

Response (400/500) - Error

{
  "success": false,
  "message": "MySQL connection failed: Access denied for user 'username'@'localhost'",
  "error": "Access denied for user 'username'@'localhost'"
}
        

Supported Database Types

1. MySQL / MariaDB

dbType: mysql or mariadb | Default Port: 3306

{
  "dbName": "mydb",
  "dbUsername": "root",
  "password": "mypassword",
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306
}
          

2. PostgreSQL

dbType: postgres or postgresql | Default Port: 5432

{
  "dbName": "mydb",
  "dbUsername": "postgres",
  "password": "mypassword",
  "dbType": "postgres",
  "host": "localhost",
  "port": 5432
}
          

3. MongoDB

dbType: mongodb or mongo | Default Port: 27017

{
  "dbName": "mydb",
  "dbUsername": "admin",
  "password": "mypassword",
  "dbType": "mongodb",
  "host": "localhost",
  "port": 27017
}
          

Note: If host contains mongodb:// or mongodb+srv://, it's used directly as connection string.

4. JSON (File-based)

dbType: json | Port: Not used (can be any value)

{
  "dbName": "mydb",
  "dbUsername": "any",
  "password": "any",
  "dbType": "json",
  "host": "local",
  "port": 0
}
          

Note: File-based database using lowdb. No actual network connection required.

Common Error Responses

Missing Parameters

{
  "success": false,
  "message": "Missing required parameters: dbName, dbUsername, password, dbType, host, and port are required"
}
          

Connection Failed

{
  "success": false,
  "message": "MySQL connection failed: Access denied for user 'username'@'localhost'",
  "error": "Access denied for user 'username'@'localhost'"
}
          

Unsupported Database Type

{
  "success": false,
  "message": "Unsupported database type: oracle. Supported types: mysql, postgres, mongodb, json",
  "error": "Unsupported database type"
}
          

MongoDB Driver Missing

{
  "success": false,
  "message": "MongoDB driver not installed. Install with: npm install mongodb",
  "error": "MongoDB driver missing"
}
          

Database Type Port Reference

Database Type	Default Port	dbType Value
MySQL	3306	`mysql` or `mariadb`
PostgreSQL	5432	`postgres` or `postgresql`
MongoDB	27017	`mongodb` or `mongo`
JSON	N/A	`json`

Ping Dart API Documentation

API Categories

Message APIs

Story APIs

Call APIs

Dynamic Query APIs

Base Request Structure

1. Conditions

Basic Conditions

NOT EQUAL Condition

IN Condition (Array Values)

BETWEEN Condition

2. Search Functionality

Basic Search

Search with Arrays (IN Condition)

3. Margedata (Join/Merge)

Basic Margedata Structure

Example: Simple One-to-Many Join

Example: Nested Margedata (Multi-level Joins)

4. Range (Location Filtering)

Location Filter Example

5. Pagination

6. Order By

Complete Example: Complex Query with All Features

Error Responses

Database Type Support

Database Connection APIs

Request Body - Format 1: New Format (Recommended - All Database Types)

Request Body - Format 2: Legacy Format (MySQL Only - Backward Compatible)

Supported Database Types

1. MySQL / MariaDB

2. PostgreSQL

3. MongoDB

4. JSON (File-based)

Common Error Responses

Missing Parameters

Connection Failed

Unsupported Database Type

MongoDB Driver Missing

Database Type Port Reference