Push API (Transcript Hook)

Once Push API has been enabled for your account, Focus can send a webhook payload to your endpoint when transcript processing completes.

Overview

The Push API is a webhook-style integration for low-volume use cases where your system should react immediately to completed transcripts, without polling.

Low-volume integration only

Push API is designed for low-volume customers only.

Recommended limit: 10 requests per hour to your receiving endpoint.

If your expected throughput is higher, use Cursor synchronization API or Native Focus REST API as your primary extraction path.

When it fires

A Push API request is sent for each transcript completion event. In implementation terms, Focus builds a payload from completed transcription results and posts it to your configured transcript hook URL.

Payload shape

The webhook body is a JSON array. Each item represents one completed interaction:

[
  {
    "clientId": 123456,
    "interactionId": 9876543,
    "tags": ["callCategory.categoryNames.Sales", "conversationPhases.categoryNames.Closing"]
  }
]

Authentication options

Push API supports the same auth modes as the transcript hook implementation:

• JWT bearer token
• Basic auth
• Bearer token
• None

For JWT mode, Focus signs a short-lived token and sends it as an Authorization bearer header.

Example workflow

A common pattern is: Push for trigger, REST for full data.

Minimal receiver example (Node.js/Express)

app.post('/focus/transcript-complete', express.json(), async (req, res) => {
  const items = Array.isArray(req.body) ? req.body : [];

  for (const item of items) {
    if (!item?.interactionId) continue;

    // Queue async processing so webhook response stays fast.
    await queue.publish({
      clientId: item.clientId,
      interactionId: item.interactionId,
      tags: item.tags || []
    });
  }

  res.status(200).json({ accepted: items.length });
});

Best practices

• Keep webhook handlers fast: acknowledge quickly, then process asynchronously.
• Make processing idempotent using interactionId as your dedupe key.
• Retry safely in your own queue if downstream dependencies are unavailable.
• Monitor webhook failures and alert on repeated non-2xx responses.
• If event volume grows, move to Cursor API polling for durable bulk synchronization.

Choosing Push vs Cursor vs REST

• Push API: event-driven trigger when transcripts complete (best for low volume).
• Cursor API: resilient incremental sync for medium/high volume pipelines.
• REST API: flexible on-demand retrieval and detailed querying.