Calls

What actually happened on your channels.

const { calls } = await connect.calls.list({ workspaceId, from, to });
const call = await connect.calls.get(callId);
// call.transcript, call.outcome, call.durationSeconds, call.extraction

A call record carries the outcome, the duration, the transcript, any tool calls the agent made, and whatever post-call extraction the agent was configured to perform.

Transcripts are the customer's data. They contain whatever the caller said - names, card numbers, medical details, whatever the conversation was about. Whether a call is recorded at all is the workspace's setting, not yours, so treat an absent transcript as normal rather than as a failure. Whatever you store from here falls under the deletion policy you declared for this application.

Records appear after a call completes, not during it. There is no live stream on this API.

Endpoints

GET /api/v1/application/calls

List your calls

Scope calls:read  ·  Rate limit 30 requests / min per IP, 60 requests / min per API key

Every call that arrived on a channel assigned to your application, newest first, across all of your subscribing workspaces.

The application is resolved from your API key and is never a parameter, so there is no request that reads another partner's calls. channelId only narrows within what you already hold; one belonging to someone else simply matches nothing.

Calls your UI placed are a separate list. A call a member places with <ConnectCallButton> leaves from the workspace's own number, which is usually assigned to no application, so it never appears above. Pass placedByApplication=true (optionally with workspaceId) for exactly those - the calls call.completed / call.missed describe with handler: "member". That is what to reconcile a timeline from when a webhook was delivered somewhere else.

Otherwise channelId is the only filter, and that is a budget decision rather than an oversight - every filter here costs a Firestore composite index against a project already at the 200 ceiling. Filter the rest client-side, or read the aggregate from /analytics.

Page until hasMore is false; do not stop on an empty items.

What this deliberately does not return: the routing snapshot taken at pick-up (unbounded, unvalidated, and available live at GET /channels/{channelId}), the carrier's own call id and hangup text, and the carrier's measure of the recording's length. agentId/agentVersion carry who answered, and durationSeconds/billDurationSeconds are the two durations Connect stands behind.

Parameters

Responses

Response body

GET /api/v1/application/calls/{callId}

Get one call and its transcript

Scope calls:read  ·  Rate limit 30 requests / min per IP, 60 requests / min per API key

The call record plus every transcript turn, ordered by sequence - which is the sort to trust, since two turns can share a millisecond.

interrupted marks a turn the caller talked over, and is only ever true for an agent turn. extraction is your agent's own post-call structured output, keyed by its extractionSchema; Connect stores it without interpreting it.

A long call's transcript is capped at 2,000 turns, the same ceiling applied when it was written.

Recording and transcript files land in the workspace's Drive: recordingFileId and transcriptFileId are Drive file ids, readable with a drive:read key. Both are null until the carrier posts the audio, which is normal for a call that has only just ended - see recordingStatus.

A call belonging to another application answers 404, not 403, for the same enumeration reason the channel reads give.

Parameters

Responses

Response body

GET /api/v1/application/calls/availability

Can the signed-in member call from here

Scope calls:place  ·  Rate limit 30 requests / min per IP, 30 requests / min per API key

Whether the member can place a browser call right now, and if not, why - so a Call button can say what is missing instead of failing when pressed. Member-only, like every calls:place endpoint; a member without "Make calls" is refused 403, which the SDK's bridge reports as status: "no_permission".

status, in precedence order: no_number (the workspace holds no business number - offer names the subscription whose plan sells the "Business number" add-on), number_pending (one was bought but Connect's pool was empty; an admin can retry in Connect), no_balance (not a minute's worth of prepaid minutes), available.

canTopUp and canManageNumber are the member's own (billing:update, subscription:update): offer the next step only to someone who can take it. Buying minutes and adding a number both happen in Connect - link to /calling and to /billing/subscriptions/{offer.subscriptionId} with client_id and return_to so they come back.

Responses

Response body

GET /api/v1/application/calls/settings

Read whether the workspace records its calls

Scope calls:place  ·  Rate limit 30 requests / min per IP, 30 requests / min per API key

The workspace's call-recording switch - the same setting Connect's Calling screen edits - plus canManage, whether the signed-in member may change it (their own channel:manage). Member-only: requires X-Connect-Session-Token; reading needs the member's workspace:read.

recordingRatePaisePerMinute is what recording adds to every billed minute, pre-tax - show it beside the switch, because turning it on changes what every call costs.

Responses

Response body

PUT /api/v1/application/calls/settings

Switch call recording on or off

Scope calls:place  ·  Rate limit 30 requests / min per IP, 30 requests / min per API key

Turns recording of member calls on or off for the workspace. Member-only, and the member must hold channel:manage - the change is audited against them, not your key.

Applies to calls started after it: a call in progress keeps the setting, and the price, it began with. While it is on, the person called hears that the call may be recorded as they answer, and call.analyzed follows each recorded call. Answers the settings as they now stand.

Request body

Responses

Response body

GET /api/v1/application/calling/readiness

Read whether the workspace may legally make each kind of call

Scope calls:place  ·  Rate limit 30 requests / min per IP, 30 requests / min per API key

Where the workspace stands on Connect's calling compliance journey - the steps Indian telecom rules ask of a business before it calls (DLT registration, a 140-series number with an approved voice header for sales calls, the autodialer notice to the operator, consent, calling hours). Two callers: a signed-in member (X-Connect-Session-Token; reading needs their workspace:read), or your own server with ?workspaceId= and no token - a dialer checking before it places a call. The workspace must subscribe to your application either way.

runs answers the question you actually have - may this workspace run service or sales calls, dialled by a rep (preview) or by software (automatic) - evaluated by the same gates the dialer refuses on, with the first reason worded for the member. Do not re-derive it from steps.

Send the member to setupUrl to finish a step; it carries your client_id so Connect offers the way back. canManage is their channel:manage - whether they can take the steps or need an admin - and always false on a server call, which has no member.

Parameters

Responses

Response body

POST /api/v1/application/calls/browser-token

Sign a member's browser in to the phone network

Scope calls:place  ·  Rate limit 30 requests / min per IP, 30 requests / min per API key

A short-lived carrier access token for Plivo's Browser SDK, which a member's browser logs in with before placing a call. Member-only: requires X-Connect-Session-Token, and that member must hold "Make calls" (call:place) - from their workspace role, or a role on your application carrying connect:call:place.

The token can place no call on its own. Every call it starts is refused by Connect unless POST /calls/start approved it first, so it carries no authority beyond signing in. It is valid for an hour, and the SDK stays registered between calls - a member making calls all morning signs in a handful of times.

You do not need to call this yourself: the SDK's <ConnectCallButton> does, through your bridge.

Responses

Response body

POST /api/v1/application/calls/start

Approve a call from a member to a number

Scope calls:place  ·  Rate limit 30 requests / min per IP, 30 requests / min per API key

Records a call from the signed-in member to phone and returns what their browser needs to place it - the number, the workspace number the callee will see, and two SIP headers to send with the call. Member-only, exactly as /calls/browser-token.

The call leaves from the workspace's own number, never the member's, and is not recorded. Every rule is applied here, before anything reaches the carrier: the workspace must hold an active number and be allowed to place calls, and the member must not already be on one (412).

The headers carry a one-time key valid for two minutes, and Connect dials the number on the record rather than anything the browser later sends - so a tampered browser can ring nobody it was not approved to. Read the outcome afterwards with GET /calls/{callId} (calls:read): handler is member, talkSeconds is how long the callee was on the line, and unansweredReason says why nobody picked up. Your application can read a call it placed even though the number belongs to the workspace.

Request body

Responses

Response body

POST /api/v1/application/calls/cancel

Cancel a call the browser never placed

Scope calls:place  ·  Rate limit 30 requests / min per IP, 30 requests / min per API key

For a call /calls/start approved but the browser could not place - the microphone was refused, sign-in failed, the member pressed Hang up while it was still connecting. The call is recorded as unanswered with unansweredReason: "cancelled".

Only the member who started it may cancel it, and only before the carrier has taken it; after that the carrier's own report closes the record, and this does nothing. Someone else's call answers 404.

Request body

Responses

GET /api/v1/application/do-not-call

Read whether a number asked the workspace not to call it

Scope do-not-call:read  ·  Rate limit 120 requests / min per API key

The workspace's do-not-call list is Connect's, and Connect enforces it: every outbound call - a member's /calls/start, from any application or from Connect itself, and every call an agent places - to a listed number is refused with do_not_call (409) before anything reaches the carrier. Read this to show the entry beside a record, never to decide whether to dial.

A number never listed answers doNotCall: false with every other field null, not 404. ?history=true adds the last twenty set/lifted events, newest first. Server-to-server, name the workspace with workspaceId; with X-Connect-Session-Token the workspace comes from the token and the member needs contact:read.

Parameters

Responses

Response body

PUT /api/v1/application/do-not-call

Put a number on the workspace's do-not-call list

Scope do-not-call:write  ·  Rate limit 120 requests / min per API key

Records that a person asked this workspace not to call them. From then on Connect refuses every outbound call to the number, whichever application or agent places it. Every purpose - a person who said "stop ringing me" meant the service call too.

Idempotent: a number already listed keeps its original entry - when they first asked is the fact worth keeping - and answers changed: false, so a backfill can be re-run. Every change is written to an append-only ledger attributed to your application, and to the member when X-Connect-Session-Token came with it (they need call:place - whoever can ring a person can record that they asked to stop). Server-to-server, actor names who made the change in your own terms; it is kept as your claim, never as a Connect user.

Request body

Responses

Response body

POST /api/v1/application/do-not-call/clear

Lift a number's do-not-call entry

Scope do-not-call:write  ·  Rate limit 120 requests / min per API key

Takes a number off the list, so calls to it are placed again. note is required: lifting the entry is a claim that the person took their request back, and the ledger keeps who made it and why. The entry is kept, lifted, with its history; a number not listed answers changed: false. With a session token the member needs contact:manage.

Request body

Responses

Response body