# List calls with transcripts

Retrieve calls by a list of conversation ids and include transcripts when available.
A maximum of 20 `conversation_ids` can be provided. If none are provided or more than 20 are provided, a 400 error is returned.
Requires the `read_conversations` OAuth scope.

Endpoint: POST /calls/search
Version: Preview
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)

## Request fields (application/json):

  - `conversation_ids` (array, required)
    A list of conversation ids to fetch calls for. Maximum 20.

## Response 200 fields (application/json):

  - `type` (string)
    Example: list

  - `data` (array)

  - `data.type` (string)
    String representing the object's type. Always has the value `call`.
    Example: call

  - `data.id` (string)
    The id of the call.
    Example: 123

  - `data.conversation_id` (string)
    The id of the conversation associated with the call, if any.
    Example: 456

  - `data.admin_id` (string)
    The id of the admin associated with the call, if any.
    Example: 789

  - `data.contact_id` (string)
    The id of the contact associated with the call, if any.
    Example: 6762f0dd1bb69f9f2193bb83

  - `data.state` (string)
    The current state of the call.
    Example: ended

  - `data.initiated_at` (any)

  - `data.recording_url` (string)
    API URL to download or redirect to the call recording if available.
    Example: https://api.intercom.io/calls/123/recording

  - `data.transcription_url` (string)
    API URL to the call transcript if available.
    Example: https://api.intercom.io/calls/123/transcript

  - `data.call_type` (string)
    The type of call.
    Example: phone

  - `data.direction` (string)
    The direction of the call.
    Example: outbound

  - `data.ended_reason` (string)
    The reason for the call end, if applicable.
    Example: missed

  - `data.phone` (string)
    The phone number involved in the call, in E.164 format.
    Example: +15551234567

  - `data.fin_recording_url` (string)
    API URL to the AI Agent (Fin) call recording if available.

  - `data.fin_transcription_url` (string)
    API URL to the AI Agent (Fin) call transcript if available.

  - `data.duration` (integer)
    Total call duration in seconds from the caller's perspective. For inbound calls, measured from initiated to ended. For outbound calls, measured from answered to ended. Null until the call ends, and for outbound calls that were never answered.
    Example: 900

  - `data.talk_time` (integer)
    Total time in seconds the agent and customer were connected.
    Example: 300

  - `data.queue_time` (integer)
    Total time in seconds the caller waited in queue before connecting, when assigned to a team.
    Example: 45

  - `data.hold_time` (integer)
    Total time in seconds the caller was placed on hold during the call.
    Example: 60

  - `data.transcript` (array)
    The call transcript if available, otherwise an empty array.

  - `data.transcript.start_time` (any)
    The start time of the turn, as a seconds offset from the start of the call. A string on calls transcribed by Amazon Transcribe, a number on Fin Voice calls.
    Example: 0.0

  - `data.transcript.end_time` (any)
    The end time of the turn, as a seconds offset from the start of the call. A string on calls transcribed by Amazon Transcribe, a number on Fin Voice calls.
    Example: 3.00

  - `data.transcript.speaker_label` (string)
    The diarization label for the speaker.
    Example: Teammate 1

  - `data.transcript.speaker` (string)
    The diarization label for the speaker. Same value as `speaker_label`.
    Example: Teammate 1

  - `data.transcript.content` (string)
    The transcribed text spoken during this turn.
    Example: Hello, thanks for calling. How can I help today?

  - `data.transcript.speaker_type` (string)
    The type of the speaker - either `admin` for a teammate or `user` for a contact. Absent on Fin Voice call transcripts and on calls transcribed before speaker attribution shipped, where only `speaker_label` identifies the speaker.
    Example: admin

  - `data.transcript.speaker_id` (string)
    The id of the teammate or contact who is the speaker. `-1` when the teammate who spoke has since been deleted, in which case `speaker_name` is `Deleted teammate`.
    Example: 789

  - `data.transcript.speaker_name` (string)
    The resolved display name of the speaker. A contact who has been merged into another resolves to the name on the surviving record. Omitted when the speaker cannot be resolved or has no name, for example a contact whose record was scrambled by a GDPR deletion request. Clients should fall back to `speaker_label` when this is absent.
    Example: Jane Doe

  - `data.transcript.article_sources` (array)
    Sources Fin cited during this turn. Only present on Fin Voice call transcripts.
    Example: [{"title":"Password Reset Guide","entity_type":120,"entity_id":"8185560"}]

  - `data.transcript.article_sources.title` (string)
    The title of the cited source.
    Example: Password Reset Guide

  - `data.transcript.article_sources.entity_type` (integer)
    The type of the cited entity.
    Example: 120

  - `data.transcript.article_sources.entity_id` (string)
    The id of the cited entity.
    Example: 8185560

  - `data.transcript.triggered_guidance` (array)
    Guidance rules that Fin matched during this turn. Only present on Fin Voice call transcripts.
    Example: [{"match_type":"clarification","rule_id":"3","rule_text":"If the customer asks about pricing, ask which plan they're interested in before answering"}]

  - `data.transcript.triggered_guidance.match_type` (string)
    How the rule was matched.
    Example: clarification

  - `data.transcript.triggered_guidance.rule_id` (string)
    The id of the matched guidance rule.
    Example: 3

  - `data.transcript.triggered_guidance.rule_text` (string)
    The text of the matched guidance rule.
    Example: If the customer asks about pricing, ask which plan they're interested in before answering

  - `data.transcript_status` (string)
    The status of the transcript if available.

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid