Skip to main content

API Reference

Complete REST API documentation for the PocketPing bridge server.

Base URL​

  • SaaS: https://api.pocketping.io/v1
  • Self-hosted: http://localhost:3001 (or your bridge URL)

Authentication​

Include your API key in the header:

Authorization: Bearer your_api_key

Endpoints​

Sessions​

List Sessions​

GET /sessions

Response:

{
  "sessions": [
    {
      "id": "sess_abc123",
      "visitorId": "vis_xyz789",
      "projectId": "proj_def456",
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastActivity": "2024-01-15T10:35:00Z",
      "metadata": {
        "pageUrl": "https://example.com/pricing",
        "userAgent": "Mozilla/5.0..."
      }
    }
  ]
}

Get Session​

GET /sessions/:sessionId

Close Session​

POST /sessions/:sessionId/close

Messages​

List Messages​

GET /sessions/:sessionId/messages

Response:

{
  "messages": [
    {
      "id": "msg_001",
      "sessionId": "sess_abc123",
      "content": "Hello, I have a question",
      "type": "visitor",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "msg_002",
      "sessionId": "sess_abc123",
      "content": "Hi! How can I help?",
      "type": "operator",
      "createdAt": "2024-01-15T10:31:00Z"
    }
  ]
}

Send Message​

POST /sessions/:sessionId/messages

Request:

{
  "content": "Thanks for reaching out!",
  "type": "operator"
}

Visitor Identification​

Identify Visitor​

POST /sessions/:sessionId/identify

Request:

{
  "email": "user@example.com",
  "name": "John Doe",
  "customerId": "cust_123",
  "metadata": {
    "plan": "pro",
    "company": "Acme Inc"
  }
}

AI Control​

Toggle AI​

POST /sessions/:sessionId/ai

Request:

{
  "enabled": false
}

WebSocket​

Connect to receive real-time updates:

const ws = new WebSocket('wss://api.pocketping.io/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    apiKey: 'your_api_key'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'session.created':
      console.log('New session:', data.session);
      break;
    case 'message.created':
      console.log('New message:', data.message);
      break;
    case 'session.closed':
      console.log('Session closed:', data.sessionId);
      break;
  }
};

Message Types​

TypeDescription
visitorMessage from website visitor
operatorMessage from human operator
aiMessage from AI fallback
systemSystem message (e.g., "Session closed")

Error Responses​

{
  "error": "Not found",
  "message": "Session not found",
  "code": "SESSION_NOT_FOUND"
}
StatusDescription
400Bad request (invalid parameters)
401Unauthorized (missing or invalid API key)
404Not found
429Rate limited
500Internal server error

Rate Limits​

  • SaaS Free: 100 requests/minute
  • SaaS Pro: 1000 requests/minute
  • SaaS Team: 10000 requests/minute
  • Self-hosted: No limits

Webhooks​

Configure webhooks to receive events:

POST /webhooks

Request:

{
  "url": "https://yoursite.com/webhook",
  "events": ["session.created", "message.created", "session.closed"]
}

Webhook payload:

{
  "event": "message.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "sessionId": "sess_abc123",
    "message": {
      "id": "msg_001",
      "content": "Hello!",
      "type": "visitor"
    }
  }
}

SDKs​

For easier integration, use our official SDKs: