admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
644751be7bcbc2befb22eb6b50d2bfdd035dd37f
pos-system/services/mkt-facebook-service-net/docs/en/API.md

9.4 KiB
Raw Blame History

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.

Authorization: Bearer {jwt_token}

Webhooks API

Verify Facebook Webhook

Facebook uses this endpoint to verify webhook ownership during setup.

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:

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.

POST /api/v1/webhooks/facebook

Headers:

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

Request Body (Message Event):

{
  "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):

{
  "success": true
}

Conversations API

List Conversations

Retrieve a paginated list of conversations.

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):

{
  "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.

GET /api/v1/conversations/{id}

Response (200 OK):

{
  "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.

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

Request Body:

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

Response (200 OK):

{
  "success": true,
  "data": {
    "messageId": "msg-003",
    "sentAt": "2026-01-18T10:35:00Z"
  }
}

Customers API

List Customers

Retrieve a paginated list of customers.

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):

{
  "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.

PUT /api/v1/customers/{id}

Request Body:

{
  "tags": ["VIP", "Returning", "HighValue"],
  "customFields": {
    "preferredLanguage": "English",
    "membershipTier": "Platinum"
  }
}

Response (200 OK):

{
  "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.

GET /api/v1/chatbots/flows

Response (200 OK):

{
  "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.

POST /api/v1/chatbots/flows

Request Body:

{
  "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):

{
  "success": true,
  "data": {
    "flowId": "flow-003",
    "createdAt": "2026-01-18T12:00:00Z"
  }
}

Get AI Chatbot Config

Retrieve AI chatbot configuration for a shop.

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

Response (200 OK):

{
  "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.

PUT /api/v1/chatbots/ai-config

Request Body:

{
  "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):

{
  "success": true,
  "data": {
    "configId": "ai-config-001",
    "updatedAt": "2026-01-18T12:30:00Z"
  }
}

Error Responses

Standard Error Format

{
  "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

Reference in New Issue View Git Blame Copy Permalink