# API Documentation

**Service**: mkt-facebook-service-net  
**Base URL**: `http://localhost/api/v1/mkt-facebook`  
**API Version**: v1.0

## Authentication

All REST API endpoints (except webhooks) require JWT Bearer token.

```http
Authorization: Bearer {jwt_token}
```

## Webhooks API

### Verify Facebook Webhook

Facebook uses this endpoint to verify webhook ownership during setup.

```http
GET /api/v1/webhooks/facebook
```

**Query Parameters**:
| Parameter | Type | Description |
|-----------|------|-------------|
| `hub.mode` | string | Must be "subscribe" |
| `hub.verify_token` | string | Token configured in Facebook App |
| `hub.challenge` | string | Random string from Facebook |

**Response** (200 OK):
```
{hub.challenge}
```

**Example**:
```bash
curl "http://localhost/api/v1/webhooks/facebook?hub.mode=subscribe&hub.verify_token=my_verify_token&hub.challenge=1234567890"
```

---

### Receive Facebook Messenger Events

Receives messages, postbacks, and other events from Facebook Messenger Platform.

```http
POST /api/v1/webhooks/facebook
```

**Headers**:
```
X-Hub-Signature-256: sha256={signature}
Content-Type: application/json
```

**Request Body** (Message Event):
```json
{
  "object": "page",
  "entry": [{
    "id": "PAGE_ID",
    "time": 1234567890,
    "messaging": [{
      "sender": { "id": "USER_ID" },
      "recipient": { "id": "PAGE_ID" },
      "timestamp": 1234567890,
      "message": {
        "mid": "MESSAGE_ID",
        "text": "Hello chatbot!",
        "quick_reply": {
          "payload": "QUICK_REPLY_PAYLOAD"
        }
      }
    }]
  }]
}
```

**Response** (200 OK):
```json
{
  "success": true
}
```

---

## Conversations API

### List Conversations

Retrieve a paginated list of conversations.

```http
GET /api/v1/conversations
```

**Query Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `shopId` | guid | Yes | - | Shop/Business ID |
| `status` | string | No | - | Filter by status (Active, Closed) |
| `skip` | int | No | 0 | Number of records to skip |
| `take` | int | No | 20 | Number of records to return |

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "customerId": "650e8400-e29b-41d4-a716-446655440001",
        "customerName": "John Doe",
        "pageId": "123456789",
        "status": "Active",
        "channel": "FacebookMessenger",
        "lastMessageText": "Thank you!",
        "lastMessageAt": "2026-01-18T10:30:00Z",
        "createdAt": "2026-01-18T09:00:00Z"
      }
    ],
    "totalCount": 150
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

---

### Get Conversation by ID

Retrieve a specific conversation with full message history.

```http
GET /api/v1/conversations/{id}
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "650e8400-e29b-41d4-a716-446655440001",
    "customer": {
      "id": "650e8400-e29b-41d4-a716-446655440001",
      "name": "John Doe",
      "facebookUserId": "1234567890",
      "profilePicUrl": "https://...",
      "tags": ["VIP", "Returning Customer"]
    },
    "messages": [
      {
        "id": "msg-001",
        "senderId": "1234567890",
        "content": "Hello, I need help",
        "messageType": "Text",
        "direction": "Incoming",
        "sentAt": "2026-01-18T09:00:00Z"
      },
      {
        "id": "msg-002",
        "senderId": "PAGE_ID",
        "content": "Hi! How can I help you today?",
        "messageType": "Text",
        "direction": "Outgoing",
        "sentAt": "2026-01-18T09:00:05Z"
      }
    ]
  }
}
```

---

### Send Message in Conversation

Send a message to a customer in an active conversation.

```http
POST /api/v1/conversations/{id}/messages
```

**Request Body**:
```json
{
  "messageText": "Thank you for contacting us!",
  "quickReplies": [
    {
      "contentType": "text",
      "title": "Yes",
      "payload": "YES"
    },
    {
      "contentType": "text",
      "title": "No",
      "payload": "NO"
    }
  ]
}
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "messageId": "msg-003",
    "sentAt": "2026-01-18T10:35:00Z"
  }
}
```

---

## Customers API

### List Customers

Retrieve a paginated list of customers.

```http
GET /api/v1/customers
```

**Query Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `shopId` | guid | Yes | - | Shop/Business ID |
| `tags` | string[] | No | - | Filter by tags (comma-separated) |
| `search` | string | No | - | Search by name or email |
| `skip` | int | No | 0 | Pagination offset |
| `take` | int | No | 20 | Page size |

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "650e8400-e29b-41d4-a716-446655440001",
        "facebookUserId": "1234567890",
        "name": "John Doe",
        "email": "john@example.com",
        "profilePicUrl": "https://...",
        "tags": ["VIP", "Returning"],
        "firstSeenAt": "2026-01-15T08:00:00Z",
        "lastInteractionAt": "2026-01-18T10:30:00Z"
      }
    ],
    "totalCount": 450
  }
}
```

---

### Update Customer

Update customer tags and custom fields.

```http
PUT /api/v1/customers/{id}
```

**Request Body**:
```json
{
  "tags": ["VIP", "Returning", "HighValue"],
  "customFields": {
    "preferredLanguage": "English",
    "membershipTier": "Platinum"
  }
}
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "customerId": "650e8400-e29b-41d4-a716-446655440001",
    "updatedAt": "2026-01-18T11:00:00Z"
  }
}
```

---

## Chatbots API

### List Automation Flows

Retrieve all chatbot automation flows for a shop.

```http
GET /api/v1/chatbots/flows
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": [
    {
      "id": "flow-001",
      "name": "Welcome Flow",
      "shopId": "shop-123",
      "triggerType": "GetStarted",
      "triggerValue": "GET_STARTED",
      "isActive": true,
      "nodeCount": 8,
      "createdAt": "2026-01-10T00:00:00Z"
    }
  ]
}
```

---

### Create Chatbot Flow

Create a new automation chatbot flow.

```http
POST /api/v1/chatbots/flows
```

**Request Body**:
```json
{
  "shopId": "shop-123",
  "name": "Product Inquiry Flow",
  "triggerType": "Keyword",
  "triggerValue": "product|price|buy",
  "nodes": [
    {
      "type": "Start",
      "content": null,
      "config": {},
      "nextNodeIds": ["node-002"]
    },
    {
      "type": "Message",
      "content": "Welcome! I can help you find products.",
      "config": {},
      "nextNodeIds": ["node-003"]
    }
  ]
}
```

**Response** (201 Created):
```json
{
  "success": true,
  "data": {
    "flowId": "flow-003",
    "createdAt": "2026-01-18T12:00:00Z"
  }
}
```

---

### Get AI Chatbot Config

Retrieve AI chatbot configuration for a shop.

```http
GET /api/v1/chatbots/ai-config?shopId={shopId}
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "id": "ai-config-001",
    "shopId": "shop-123",
    "provider": "OpenAI",
    "model": "gpt-4-turbo",
    "systemPrompt": "You are a helpful customer service assistant...",
    "temperature": 0.7,
    "maxTokens": 500,
    "isEnabled": true,
    "updatedAt": "2026-01-17T10:00:00Z"
  }
}
```

---

### Update AI Chatbot Config

Update AI chatbot configuration.

```http
PUT /api/v1/chatbots/ai-config
```

**Request Body**:
```json
{
  "shopId": "shop-123",
  "provider": "OpenAI",
  "model": "gpt-4-turbo",
  "systemPrompt": "You are a helpful and friendly customer service assistant...",
  "temperature": 0.8,
  "maxTokens": 500,
  "isEnabled": true
}
```

**Response** (200 OK):
```json
{
  "success": true,
  "data": {
    "configId": "ai-config-001",
    "updatedAt": "2026-01-18T12:30:00Z"
  }
}
```

---

## Error Responses

### Standard Error Format

```json
{
  "success": false,
  "error": "Error message in English",
  "errorCode": "ERROR_CODE",
  "details": {
    "field": "Field-specific error"
  }
}
```

### Common Error Codes

| Status Code | Error Code | Description |
|-------------|------------|-------------|
| 400 | `INVALID_REQUEST` | Invalid request parameters |
| 400 | `VALIDATION_ERROR` | Validation failed |
| 401 | `UNAUTHORIZED` | Missing or invalid token |
| 403 | `FORBIDDEN` | No permission |
| 403 | `INVALID_SIGNATURE` | Facebook webhook signature invalid |
| 404 | `NOT_FOUND` | Resource not found |
| 409 | `CONFLICT` | Duplicate resource |
| 429 | `RATE_LIMIT_EXCEEDED` | Too many requests |
| 500 | `INTERNAL_ERROR` | Server error |
| 503 | `SERVICE_UNAVAILABLE` | External service unavailable |

---

## Rate Limiting

API rate limits per API key:
- **100 requests/minute** for read operations (GET)
- **20 requests/minute** for write operations (POST, PUT, DELETE)

**Rate Limit Headers**:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890
```

---

## Webhooks Best Practices

1. **Always return 200 immediately**
2. **Process asynchronously**
3. **Verify signature**
4. **Handle retries** (Facebook will retry if no 200 received)
5. **Use HTTPS**

## Resources

- [Facebook Messenger Platform Webhooks](https://developers.facebook.com/docs/messenger-platform/webhooks)
- [Facebook Send API Reference](https://developers.facebook.com/docs/messenger-platform/send-messages)
- [Architecture Documentation](./ARCHITECTURE.md)
- [Facebook Setup Guide](./FACEBOOK_SETUP.md)