Skip to main content

Getting Dialer Calls & Reports via API

Getting a list of calls via API from Brightcall Dialer

Calls and Call Stats data can be retrieved with POST requests to these endpoints: https://api.dialer.brightcall.ai/api/v3/stat/calls/list?api-key=%api-key% — for calls https://api.dialer.brightcall.ai/api/v3/stat/calls-detailed-e-chart?api-key=%api-key% — for statistics. The request body and response parameters are shown below.

Data Request parameters

  • searchString — Optional. Specify a search string to filter results.

  • dayFrom — Required. Start date for the query in YYYY-MM-DD format.

  • dayTo — Required. End date for the query in YYYY-MM-DD format.

  • timezone — Optional. Specify a timezone string.

  • dateInterval — Required. Accepted values: hour, day, week, month, year.

  • types — Optional. Array of call types (0: INBOUND, 1: OUTBOUND, 2: INTERNAL).

  • states — Optional. Array of call states (0: UNANSWERED, 1: ANSWERED, 2: FAILED).

  • categories — Optional. Array of call categories. Possible values: 'all', 'inbound', 'outbound', 'internal', 'answered', 'unanswered', 'failed', 'inbound_answered', 'inbound_unanswered', 'inbound_failed', 'outbound_answered', 'outbound_unanswered', 'outbound_failed', 'internal_answered', 'internal_unanswered', 'internal_failed'

  • agentIds — Optional. Array of agent IDs to filter by.

  • teamIds — Optional. Array of team IDs to filter by.

  • uniqueIds — Optional. Array of unique call IDs to filter by.

  • number — Optional. Filter by a specific phone number.

  • textProjects — Optional. Array of project names to filter by.

  • projectIds — Optional. Array of project IDs to filter by.

  • tags — Optional. Array of tags to filter by.

  • outcomes — Optional. Array of outcome strings to filter by.

  • outcomeTypes — Optional. Array of outcome types ('positive', 'negative', 'neutral', 'absent').

  • talkTimeFrom — Optional. Minimum talk time in seconds.

  • talkTimeTo — Optional. Maximum talk time in seconds.

  • answerTimeFrom — Optional. Minimum answer time in seconds.

  • answerTimeTo — Optional. Maximum answer time in seconds.

  • allUsers — Optional. Boolean to include all users.

  • userId — Optional. Filter by a specific user ID.

  • qualityRating — Optional. Filter by quality rating.

  • showTransfers — Optional. Boolean to show transfers.

  • showAICallsWithLog — Optional. Boolean to show AI calls with logs.

  • page — Optional. Page number for pagination (default: 1).

  • itemsPerPage — Optional. Positive integer; default: 100, maximum: 500. Values above 500 are treated as 500.

  • sortBy — Optional. Field to sort by ('timestamp', 'talkTime', 'answerTime', default: 'timestamp').

  • sortDirection — Optional. Sort direction ('ASC' or 'DESC', default: 'DESC').

Calls list response parameters

The API response for the calls list includes the following parameters:

  1. Success Status

    • "success": true: This indicates that the request for data was successfully processed. A value of true means the request was handled correctly and the data returned is valid.

  2. Calls Array

    • "calls": This is an array containing objects representing individual call records. Each object within the array includes several properties related to a specific call.

    • Here is a description of each parameter in the calls array:

      • answerTime: Time in seconds taken for the call to be answered.

      • callTime: In this endpoint, the same value as talkTime, in seconds. The total call duration is totalTime.

      • campaign: Name or identifier of the associated marketing campaign (nullable).

      • projectName: Name of the associated project (nullable).

      • projectId: Unique identifier for the linked project (nullable).

      • projectContactId: Unique identifier for the project contact (nullable).

      • crmInfo: Data structure containing CRM-related information (nullable).

      • favorite: Boolean indicating if the call is marked as favorite.

      • firstTimeForTree: Boolean indicating if it's the first call for the specified call tree (nullable).

      • firstTimeForUser: Boolean indicating if it's the user's first call (nullable).

      • id: Unique identifier for the call record.

      • insertOrigin: String indicating how the call record was inserted (nullable).

      • isRecordBlocked: Boolean indicating if the call recording is blocked.

      • isRecordReady: Boolean indicating if the call recording is ready for access.

      • label: Additional label or description for the call.

      • numbersInvolvedJSON: JSON string; this endpoint currently returns "{}".

      • numbersRingedJSON: JSON string; this endpoint currently returns "{}".

      • qualityRating: Numerical value for call quality rating (nullable).

      • recallDate: ISO date string for scheduled recall or follow-up (nullable).

      • recallFirstAttemptDate: ISO date string for first recall attempt (nullable).

      • recallState: Numerical value representing recall state (nullable).

      • recordName: Name or identifier of the call recording (nullable).

      • tags: Array of project tags associated with the call.

      • outcomeTag: String representing the call outcome (nullable).

      • outcomeType: Predefined type representing call outcome (nullable).

      • talkTime: Duration in seconds of actual conversation.

      • aiTalkTime: Duration in seconds of AI interaction, if applicable.

      • timestamp: ISO date string representing the call's date and time.

      • totalTime: Total call duration in seconds, including ringing and hold time.

      • treeId: Unique identifier for the associated call tree.

      • type: Call type: 0 = inbound, 1 = outbound, 2 = internal.

      • state: Call state: 0 = unanswered, 1 = answered, 2 = failed.

      • uniqueId: Unique identifier for the call session.

      • userId: Unique identifier for the user who initiated or received the call.

      • agentShortNumber: Short number or extension of the handling agent (nullable).

      • lineNumber: Phone line number used for the call.

      • clientNumber: Phone number of the associated client (nullable).

      • transfers: Array of objects representing call transfers (optional).

      • recordingExpired: Boolean indicating if the call recording has expired (optional).

      • transcripts: Object representing call transcripts (optional).

      • convoloAiRecordingSummary: AI-generated summary of the call recording (optional).

      • convoloAiRecordingTitle: Title of the AI-generated call recording summary (optional).

  3. Tags Array

    • "tags": Returned as an empty array by this endpoint. Tags attached to an individual call are in that call’s tags field.

  4. Outcomes Array

    • "outcomes": Returned as an empty array by this endpoint. A call’s result is in its outcomeTag and outcomeType fields.

  5. Projects Array

    • "projects": Returned as an empty array by this endpoint. Project information is available in each call’s projectId and projectName fields.

  6. Timezone

    • "timezone": Specifies the time zone used for the call data timestamps.

  7. Pagination

    • "page" and "pagesCount": Represent the current page number and the total number of pages available for the call data. This is useful for navigating through a large set of records.

    • "totalItems": Indicates the total number of call records available.
      ​

    • Calls list results are paginated using the page and itemsPerPage request parameters.

    • To support efficient pagination handling, Brightcall provides a dedicated endpoint to retrieve pagination metadata only, without returning call records.

      Pagination Count Endpoint

      POST https://api.dialer.brightcall.ai/api/v3/stat/calls/count

    • Description

      This endpoint accepts the same request body parameters as the calls list endpoint
      (/api/v3/stat/calls/list) and applies the same filters.

      Instead of returning call data, it responds with pagination information only.

    • Response Parameters

      • page — Current page number

      • pagesCount — Total number of pages available

      • totalItems — Total number of call records matching the provided filters

​

Filter metadata response

For tags, outcomes and duration limits, use POST /api/v3/stat/calls/data with the same authentication and JSON request body.

  • tags and outcomes: Arrays of available tag and outcome values.

  • minTalkTime and maxTalkTime: Minimum and maximum talk duration, in seconds.

  • minAnswerTime and maxAnswerTime: Minimum and maximum answer time, in seconds.

​

Call statistic response

Top-Level Fields

  • success: true when the request succeeds.

  • categories: An array of period labels for the chart.

  • data: Contains the chart’s metric arrays. Each value in a metric array corresponds to the label at the same index in categories.

data Object Fields

Metric arrays include:

  • total: Total calls per interval.

  • in_answered: Answered inbound calls per interval.

  • in_missed: Unanswered inbound calls per interval.

  • out_answered: Answered outbound calls per interval.

  • out_missed: Unanswered outbound calls per interval.

Did this answer your question?