# DEN MOBILE - Complete API Documentation

**Digital Engagement Network Mobile**  
*Smart Auto Dialer & Sales Execution Platform*

## Base URL
```
https://your-server-domain.com/
```

All endpoints require:
- `device_id` - Unique device identifier
- `device_token` - Authentication token

---

## 1. DEVICE MANAGEMENT ENDPOINTS

### 1.1 Register Device
**POST** `/api/device-register`

**Request:**
```json
{
  "device_id": "uuid-12345",
  "device_name": "Samsung Galaxy S21"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "device_id": "uuid-12345",
    "device_token": "abc123def456",
    "auto_call": false
  },
  "timestamp": "2026-04-25T10:30:00Z"
}
```

---

### 1.2 Get Device Status
**GET** `/api/device-status?device_id=uuid-12345&device_token=abc123def456`

**Response:**
```json
{
  "success": true,
  "data": {
    "device_id": "uuid-12345",
    "device_name": "Samsung Galaxy S21",
    "auto_call": true,
    "status": "active",
    "is_online": true,
    "last_heartbeat": "2026-04-25T10:29:55Z"
  },
  "timestamp": "2026-04-25T10:30:00Z"
}
```

---

### 1.3 Toggle Auto Call
**POST** `/api/toggle-auto-call`

**Request:**
```json
{
  "device_id": "uuid-12345",
  "device_token": "abc123def456",
  "auto_call": true
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "device_id": "uuid-12345",
    "auto_call": true
  },
  "message": "Auto call enabled",
  "timestamp": "2026-04-25T10:30:00Z"
}
```

---

## 2. TASK POLLING ENDPOINTS (Core System)

### 2.1 Get Next Task (Polling)
**GET** `/api/get-task?device_id=uuid-12345&device_token=abc123def456`

Called every 3-5 seconds by Android device.

**Response (when task available):**
```json
{
  "success": true,
  "data": {
    "task": {
      "task_id": 1001,
      "queue_id": 1001,
      "customer": {
        "id": 50,
        "name": "John Doe",
        "phone_number": "+1234567890",
        "current_pack": "Premium",
        "current_speed": "100 Mbps",
        "status": "active"
      }
    }
  },
  "message": "Task assigned",
  "timestamp": "2026-04-25T10:30:00Z"
}
```

**Response (when no task available):**
```json
{
  "success": true,
  "data": null,
  "message": "No pending tasks",
  "timestamp": "2026-04-25T10:30:00Z"
}
```

---

### 2.2 Update Call Status
**POST** `/api/update-call-status`

**Request:**
```json
{
  "device_id": "uuid-12345",
  "device_token": "abc123def456",
  "queue_id": 1001,
  "call_status": "calling",
  "call_duration": 0
}
```

Allowed `call_status`: `calling`, `completed`, `failed`

**Response:**
```json
{
  "success": true,
  "message": "Status updated",
  "timestamp": "2026-04-25T10:30:30Z"
}
```

---

### 2.3 Complete Task
**POST** `/api/complete-task`

**Request:**
```json
{
  "device_id": "uuid-12345",
  "device_token": "abc123def456",
  "queue_id": 1001,
  "call_duration": 45,
  "call_outcome": "completed"
}
```

Allowed `call_outcome`: `completed`, `failed`, `no_answer`, `rejected`

**Response:**
```json
{
  "success": true,
  "message": "Task completed",
  "timestamp": "2026-04-25T10:31:00Z"
}
```

---

## 3. TAGGING ENDPOINTS

### 3.1 Get Available Tags
**GET** `/api/get-tags?category=REJECTION`

**Response:**
```json
{
  "success": true,
  "data": {
    "category": "REJECTION",
    "tags": [
      "Ineffective Rejection",
      "Not In Service",
      "Wrong Number",
      "Reject"
    ]
  },
  "timestamp": "2026-04-25T10:31:15Z"
}
```

---

### 3.2 Submit Tag
**POST** `/api/submit-tag`

**Request:**
```json
{
  "device_id": "uuid-12345",
  "device_token": "abc123def456",
  "queue_id": 1001,
  "customer_id": 50,
  "tag_category": "REJECTION",
  "tag_value": "Not In Service",
  "notes": "Customer said number is no longer in use"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "tag_id": 5001,
    "customer_id": 50,
    "tag_category": "REJECTION",
    "tag_value": "Not In Service"
  },
  "message": "Tag submitted successfully",
  "timestamp": "2026-04-25T10:31:30Z"
}
```

---

## 4. WHATSAPP ENDPOINTS

### 4.1 Generate WhatsApp Message
**POST** `/api/generate-whatsapp-message`

**Request:**
```json
{
  "device_id": "uuid-12345",
  "device_token": "abc123def456",
  "customer_id": 50,
  "template": "default"
}
```

Templates: `default`, `followup`, `offer`

**Response:**
```json
{
  "success": true,
  "data": {
    "whatsapp_id": 100,
    "phone_number": "+1234567890",
    "message": "Hi John, I'm Samsung Galaxy S21 who called you just now. Let me know if you have any questions!",
    "template": "default"
  },
  "timestamp": "2026-04-25T10:32:00Z"
}
```

---

### 4.2 Mark WhatsApp Sent
**POST** `/api/mark-whatsapp-sent`

**Request:**
```json
{
  "device_id": "uuid-12345",
  "device_token": "abc123def456",
  "whatsapp_id": 100
}
```

**Response:**
```json
{
  "success": true,
  "message": "Message marked as sent",
  "timestamp": "2026-04-25T10:33:00Z"
}
```

---

### 4.3 Get Pending WhatsApp Messages
**GET** `/api/pending-whatsapp-messages?device_id=uuid-12345&device_token=abc123def456`

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "whatsapp_id": 100,
      "customer_name": "John Doe",
      "phone_number": "+1234567890",
      "message": "Hi John...",
      "created_at": "2026-04-25T10:32:00Z"
    }
  ],
  "timestamp": "2026-04-25T10:33:30Z"
}
```

---

## Error Responses

All failed requests return:

```json
{
  "success": false,
  "error": "Error description",
  "timestamp": "2026-04-25T10:30:00Z"
}
```

HTTP Status Codes:
- `200` - Success
- `400` - Bad request (validation error)
- `401` - Unauthorized (invalid device credentials)
- `404` - Not found
- `500` - Server error

---

## Rate Limiting

- **Max 10 requests per device per 10 seconds**
- Excess requests will receive HTTP 429 (Too Many Requests)

---

## Request/Response Timing

- **Polling interval:** 3-5 seconds (configurable)
- **Request timeout:** 30 seconds
- **Connection timeout:** 10 seconds

---

## Example Flow

1. Device registers: `POST /device-register`
2. Device enables auto-call: `POST /toggle-auto-call`
3. Device polls for task (every 3-5s): `GET /get-task`
4. Task received: Call customer
5. During call: `POST /update-call-status` (call_status: "calling")
6. After call: `POST /complete-task` (with duration)
7. Tag call: `POST /submit-tag`
8. Generate message: `POST /generate-whatsapp-message`
9. Mark sent: `POST /mark-whatsapp-sent`
10. Repeat from step 3