Skip to main content

Before you start

Use a server-side API key with calls:read to retrieve summaries and transcripts:read to retrieve transcripts. Grant both scopes only when the integration needs both resources. Existing keys do not gain transcript access automatically.

Complete history and structured results

GET /call-history covers retained dashboard, inbound, manual, batch, Automation and Public API calls in the organization, including archived calls. Use calls:read and follow next_cursor through every page. Technical number checks and rows without a start or creation timestamp are excluded. source accepts ai or human and selects a storage family. The human family can include AI inbound calls; it does not identify who answered. created_after is inclusive and created_before exclusive. Both filter the call start time, falling back to creation time. Each history entry has a separate id for GET /call-history/{history_id}. Its nullable call_id links to an executable Public API resource when one exists. History IDs cannot cancel calls. The existing GET /calls continues to list executable API call resources. The embedded history result and GET /calls/{call_id}/result share the same structured result contract: Poll according to poll_after_seconds only while classification_status is processing. unavailable means no current classification and can change after later analysis. Missing historical detection and message reports remain unknown. A human correction preserves the corrected outcome and suppresses the original AI classification with reason manually_corrected. The corresponding MCP tools are brightalk_list_call_history, brightalk_get_call_history and brightalk_get_call_result, with the same permissions as REST.

Poll the summary

Call GET /calls/{call_id}/summary. A normal unfinished result is HTTP 200 with status: "processing" and poll_after_seconds: 5. Stop polling when the status is ready, unavailable, or failed.

Poll the transcript

Call GET /calls/{call_id}/transcript?limit=100. Summary and transcript readiness are independent, so do not infer one from the other.

Follow the cursor

When next_cursor is non-null, send it unchanged on the next request. The cursor pins the transcript revision. A later reconciliation can publish a new revision without changing pages already in progress. A page can contain fewer turns than limit to stay within the response byte budget, so only a null next_cursor means pagination is complete.

Detect content changes

Store call_id, endpoint name, and revision. A higher revision means the sanitized endpoint content changed. Repeating a projection with identical content does not increment the revision.

Handle terminal states

unavailable means the call cannot produce that result; inspect its stable reason. failed with processing_failed means safe processing was exhausted. Neither is an HTTP error.