Polling for changes

Use the REST API to keep external systems in step with activity in oHallo. This page covers recommended polling patterns for conversations, knowledge base entries, and attention items.

Polling patterns

Poll for new or updated conversations

GET /api/conversations is cursor-paginated: the response is { "data": [...], "nextCursor": "..." }, and nextCursor is omitted once you reach the end. Track the newest conversation you have already seen so you only act on genuinely new activity. To page through a large result set, pass the cursor value back on the next call.

const API_BASE = "https://api.ohallo.eu";
const API_KEY = "sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx";
const WORKSPACE_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

const seen = new Set<string>();

async function pollConversations(): Promise<void> {
  const response = await fetch(
    `${API_BASE}/api/conversations?workspaceId=${WORKSPACE_ID}&limit=50`,
    {
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
      },
    }
  );

  if (!response.ok) {
    console.error(`Poll failed: ${response.status}`);
    return;
  }

  const data = await response.json();

  for (const conversation of data.data) {
    if (seen.has(conversation.id)) continue;
    seen.add(conversation.id);
    // Process each new or updated conversation
    console.log(`Conversation ${conversation.id}: ${conversation.status}`);
  }

  // `data.nextCursor` is present only when more pages remain. Pass it back as
  // `&cursor=<value>` to continue paging; omit it to start from the top again.
}

// Poll every 30 seconds
setInterval(pollConversations, 30_000);

Poll for pending KB entries

async function pollPendingKBEntries(): Promise<void> {
  const response = await fetch(
    `${API_BASE}/api/workspaces/${WORKSPACE_ID}/kb-entries/pending`,
    {
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
      },
    }
  );

  if (!response.ok) return;

  // The pending endpoint returns a bare JSON array of entries.
  const entries = await response.json();

  for (const entry of entries) {
    // Review and auto-approve entries with high confidence
    if (entry.confidence && entry.confidence >= 0.9) {
      await fetch(`${API_BASE}/api/kb-entries/${entry.id}/approve`, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${API_KEY}`,
        },
      });
      console.log(`Auto-approved KB entry: ${entry.question}`);
    }
  }
}

// Poll every 5 minutes
setInterval(pollPendingKBEntries, 300_000);

Polling guidelines

• Conversations: Poll every 15 to 30 seconds for near-real-time updates. The list is ordered by recent activity, so the first page surfaces the latest changes; track ids you have already processed to avoid acting on the same conversation twice.
• KB and policy entries: Poll every 5 to 15 minutes. Pending entries do not require immediate action.
• Attention items: Poll every 1 to 5 minutes depending on urgency requirements.
• Rate limits: The API allows 600 requests per minute per client IP in production. A typical integration polling conversations (every 30s), KB entries (every 5min), and attention items (every 2min) uses only a few requests per minute, well within budget.