Skip to main content
GET
/
api
/
check-updates.php
Check Updates
curl --request GET \
  --url https://api.example.com/api/check-updates.php
{
  "success": true,
  "has_update": true,
  "has_updates": true,
  "conversation_id": "<string>",
  "updated_conversations": [
    {
      "id": "<string>",
      "last_message_at": "<string>",
      "status": "<string>"
    }
  ],
  "server_time": "<string>",
  "status": "<string>",
  "can_enable_ai": true
}

Overview

The updates checking system provides three endpoints for polling real-time changes:
  1. check-updates.php: Check for new messages in conversations
  2. check-conversation-updates.php: Check for conversation metadata changes
  3. check-openai-status.php: Monitor OpenAI service status

Check Message Updates

Poll for new messages in a specific conversation or across all conversations.

Endpoint

GET /api/check-updates.php

Query Parameters

last_check
string
required
Timestamp of the last check in Y-m-d H:i:s format
conversation_id
string
Specific conversation ID to check. If omitted, checks all conversations.

Response

success
boolean
required
Indicates if the request was successful
has_update
boolean
Present when checking a specific conversation. True if new messages exist.
has_updates
boolean
Present when checking all conversations. True if any conversation has updates.
conversation_id
string
Echoed conversation ID (when checking specific conversation)
updated_conversations
array
Array of conversation IDs with new messages (when checking all conversations)
server_time
string
required
Current server timestamp in Y-m-d H:i:s format

Example Requests

curl "https://yourdomain.com/api/check-updates.php?last_check=2024-03-06%2010:30:00&conversation_id=123"

Example Responses

{
  "success": true,
  "has_update": false,
  "conversation_id": "123",
  "server_time": "2024-03-06 10:35:00"
}

Check Conversation Updates

Monitor changes to conversation metadata (status, last message timestamp).

Endpoint

GET /api/check-conversation-updates.php

Query Parameters

last_check
string
required
Timestamp of the last check in Y-m-d H:i:s format

Response

success
boolean
required
Indicates if the request was successful
has_updates
boolean
required
True if any conversations have been updated
updated_conversations
array
required
Array of conversation objects that have been updated
id
string
Conversation ID
last_message_at
string
Timestamp of the last message
status
string
Conversation status (e.g., “active”, “archived”)
server_time
string
required
Current server timestamp

Example Response

{
  "success": true,
  "has_updates": true,
  "updated_conversations": [
    {
      "id": "123",
      "last_message_at": "2024-03-06 10:34:22",
      "status": "active"
    },
    {
      "id": "456",
      "last_message_at": "2024-03-06 10:33:15",
      "status": "active"
    }
  ],
  "server_time": "2024-03-06 10:35:00"
}

Check OpenAI Status

Monitor the OpenAI service status, particularly for insufficient funds conditions.

Endpoint

GET /api/check-openai-status.php

Response

success
boolean
required
Indicates if the request was successful
status
string
required
Current OpenAI service status
  • active: Service is operational
  • insufficient_funds: Account has insufficient funds
can_enable_ai
boolean
required
Whether AI features can be enabled (false when insufficient funds)

Example Response

{
  "success": true,
  "status": "active",
  "can_enable_ai": true
}

Polling Best Practices

  • Message Updates: 2-5 seconds for active conversations
  • Conversation Updates: 5-10 seconds for conversation list
  • OpenAI Status: 30-60 seconds or on-demand

Efficient Polling Pattern

let lastCheck = new Date().toISOString().slice(0, 19).replace('T', ' ');

setInterval(async () => {
  const response = await fetch(
    `/api/check-updates.php?last_check=${encodeURIComponent(lastCheck)}`
  );
  const data = await response.json();
  
  if (data.has_updates) {
    // Fetch updated conversations
    data.updated_conversations.forEach(id => {
      fetchConversationMessages(id);
    });
  }
  
  // Update timestamp for next poll
  lastCheck = data.server_time;
}, 3000);

Error Handling

  • Always use the server_time from responses for the next last_check
  • Implement exponential backoff on errors
  • Handle missing last_check gracefully (returns no updates)

Use Cases

  • Real-time Dashboard: Auto-refresh conversation list
  • Live Chat: Display incoming messages without page refresh
  • Status Monitoring: Alert users when OpenAI service is unavailable
  • Multi-user Sync: Keep multiple browser tabs synchronized

Build docs developers (and LLMs) love