Trovacast

Voice

Conferences

Open a live call to more parties: dial numbers in, offer it to an agent, mute or remove a party, and end it — with an event as each party joins and leaves.

A conference is a live call opened to more parties. Any answered call whose audio streams through Trovacast can become one — a call to your own agent, an AI agent call, a flow call, a click-to-call bridge, an inbound call routed to a flow or an application — and the conference’s id is that call’s id. Writes need calls:write, reads calls:read; send an Idempotency-Key on every write.

Open a conference

Open a live call as a conference
curl -X POST 'https://api.trovacast.com/v1/conferences' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: conference-2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f' \
  -H 'Content-Type: application/json' \
  -d '{
  "callId": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f"
}'
201 Created (json)
{
  "object": "conference",
  "id": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
  "callId": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
  "status": "active",
  "participants": [
    {
      "object": "conference_participant",
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5e",
      "kind": "caller",
      "status": "joined",
      "callId": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
      "numberLast4": "3210",
      "agentMembershipId": null,
      "muted": false,
      "held": false,
      "joinedAt": "2026-11-05T10:00:01.000Z",
      "leftAt": null
    }
  ],
  "createdAt": "2026-11-05T10:02:00.000Z",
  "endedAt": null
}

Opening a call that is already a conference answers it as it stands. A leg dialled from another call cannot be opened — open its root call (rootCallId) — and a test-mode key has no conferences (422 TEST_MODE_UNSUPPORTED, whatever the id): the call sandbox has no audio to share. To a live key a test call is a call that does not exist (404 CONFERENCE_NOT_FOUND).

Add a party

  • to.number — dials the number into the conference as a leg of its call (legRole: conference), rated per started minute like any call, and through every rule a dial passes: the destination policy, the organization’s list of destinations for connected parties, the billing gate, the leg cap. It rings for ringTimeoutSec (5–120, default 30) and is hung up if nobody answers.
  • to.agentMembershipId — offers the conference to an agent’s desk (an active seat of the organization); they join when they accept, and appear as a party then (conference.participant.joined).
  • to.callId — moving another live call in is not supported yet (422 CONFERENCE_PARTICIPANT_UNSUPPORTED, reason: call): dial its party’s number instead.
Dial a supervisor’s mobile in
curl -X POST 'https://api.trovacast.com/v1/conferences/2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f/participants' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: conference-2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f-add-1' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": {
    "number": "+919812345678"
  },
  "ringTimeoutSec": 30
}'
201 — ringing (json)
{
  "object": "conference_participant_added",
  "participantId": "7b6a5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d",
  "kind": "number",
  "conference": {
    "object": "conference",
    "id": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
    "status": "active"
  }
}

Mute, remove, end

  • PATCH /v1/conferences/{conferenceId}/participants/{participantId} with { "muted": true } (or false) mutes or unmutes a party: the others stop (or start again) hearing them.
  • DELETE /v1/conferences/{conferenceId}/participants/{participantId} takes a party off: a dialled number is hung up, an agent released. The caller is the conference call itself (422 CONFERENCE_PARTICIPANT_UNSUPPORTED, reason: caller): end the conference instead.
  • POST /v1/conferences/{conferenceId}/end hangs the conference call up, and every party with it. Ending one that already ended answers it as it stands.

Parties

participants lists every party, oldest first, including those who left: kind is caller (the party the call reached), number, agent or ai; status is ringing, joined, left or failed; a number shows its last four digits only. A supervisor listening in from the desk is never listed. A party’s id is what mute and remove take; a dialled number’s callId is its own call in the conference call’s graph (GET /v1/calls?rootCallId=).

When a write is refused

  • Not answered yet, or over — 409 CALL_NOT_ANSWERED, 409 CALL_NOT_LIVE; a conference whose call ended is 409 CONFERENCE_ENDED.
  • Audio not streamed through Trovacast — a phone-leg or SIM call cannot be a conference (409 CALL_NOT_CONTROLLABLE).
  • The server carrying the call did not answer — 409 CALL_ON_ANOTHER_REPLICA: retry with the same Idempotency-Key. Writes reaching any other server are forwarded to it; reads answer from any server.
  • Too many legs — 409 CHILD_LEG_LIMIT: the call already has as many live legs as it may.

Events

conference.participant.joined and conference.participant.left carry { conference, participant } as each party joins, and as each hangs up or is removed (once per party); conference.ended carries { conference } once its call ends — its participants show who was still on. Each needs calls:read.

EventWhen it is sentKey scopes
conference.participant.joinedA party joined a conference. A dialled number answered, or an agent accepted. Once per party.data: conference, participantcalls:read
conference.participant.leftA party left a conference. It hung up, or was removed. Once per party.data: conference, participantcalls:read
conference.endedA conference’s call ended. Its participants show who was still on. Once per conference.data: conferencecalls:read

Errors

CodeStatusMeaning and what to do
CALL_NOT_ANSWERED409The call is not answered yet: actions start once it is in_progress (after call.answered).What to do: Act again once call.answered has arrived.
CALL_NOT_CONTROLLABLE409The call’s audio does not stream through Trovacast (a phone-leg or SIM call), so it cannot be spoken to, held or transferred from the API.What to do: Do not retry. Only calls whose audio streams through Trovacast can be controlled — every POST /v1/calls mode, and inbound calls routed to a flow or an application.
CALL_NOT_LIVE409The call has ended, or never went live. Nothing was done.What to do: Do not retry: read the call (GET /v1/calls/{callId}) for how it ended.
CALL_ON_ANOTHER_REPLICA409The Trovacast server carrying the call’s audio could not be reached in time (it is restarting or failed). Any other server forwards actions to it, so this is rare.What to do: Retry shortly with the same Idempotency-Key, which is safe: the action runs at most once.
CHILD_DIAL_DESTINATION_NOT_ALLOWED422The number a BRIDGE call or a transfer would dial is outside the organization’s list of destinations for connected parties (India by default). Nothing was dialled.What to do: Dial a number inside that list, or contact us to widen it for your organization.
CHILD_LEG_LIMIT409The call already has as many live legs dialled from it as it may (transfer targets, bridged numbers).What to do: End one of its legs first (POST /v1/calls/{callId}/hangup on the leg), then add the party again.
CONFERENCE_ENDED409The conference's call has ended: nobody can be added, muted or removed. POST /v1/conferences/{conferenceId}/end still answers it as it stands.What to do: Do not retry on this conference: it is over. GET /v1/conferences/{conferenceId} shows who took part.
CONFERENCE_NOT_FOUND404No conference with that id in this organization. A conference's id is its call's; a call never opened as one (POST /v1/conferences) is not a conference. See Conferences.What to do: Open the call as a conference first (POST /v1/conferences with its callId), or check the id.
CONFERENCE_PARTICIPANT_NOT_FOUND404No such party in the conference (a party's id is its leg's, from participants), or — when adding an agent — no active seat with that id in the organization.What to do: Use a party’s id from participants (GET /v1/conferences/{conferenceId}), or the membership id of an active seat when adding an agent.
CONFERENCE_PARTICIPANT_UNSUPPORTED422Not available on a conference (reason): call — moving another live call in is not supported yet; caller — the caller is the conference call itself; leg — a leg dialled from another call cannot be opened as a conference.What to do: Act on reason: for call, dial its party’s number in instead (to.number); for caller, end the conference to hang them up; for leg, open its root call (rootCallId).
TEST_MODE_UNSUPPORTED422A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead.