Create Conference | Pinnacle

import { PinnacleClient } from "rcs-js";
async function main() {
    const client = new PinnacleClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.conferences.create({
        label: "escalation-4412",
        participants: [
            {
                callId: "call_7cQe4F8xT1yB2mN9pK3L",
                label: "caller",
            },
            {
                to: "+14155551234",
                from: "+14155559876",
                label: "specialist",
            },
        ],
    });
}
main();

{
  "id": "conf_Hk2mX9pQ4rT7vB1nL8sW",
  "label": "escalation-4412",
  "status": "waiting",
  "participant_count": 1,
  "max_participants": 1,
  "hold_audio_url": "string",
  "speaking_events": true,
  "metadata": {},
  "created_at": "2024-01-15T09:30:00Z",
  "started_at": "2024-01-15T09:30:00Z",
  "ended_at": "2024-01-15T09:30:00Z",
  "ended_reason": "empty",
  "participants": [
    {
      "call_id": "call_7cQe4F8xT1yB2mN9pK3L",
      "conference_id": "conf_Hk2mX9pQ4rT7vB1nL8sW",
      "label": "supervisor",
      "status": "dialing",
      "from": "+14155559876",
      "to": "+14155551234",
      "muted": true,
      "on_hold": true,
      "whisper_to": [
        "string"
      ],
      "end_conference_on_leave": true,
      "joined_at": "2024-01-15T09:30:00Z",
      "left_at": "2024-01-15T09:30:00Z",
      "left_reason": "hangup"
    }
  ]
}

Create a conference: a room that calls can be added to. Each participant is an ordinary call.

You can add participants in the same request. Existing calls are added first, so the conference is live before dialed participants answer. With no participants the conference is waiting until the first one joins.

Send an Idempotency-Key to make dialed participants safe to retry: each one is dialed at most once.

Authentication

PINNACLE-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

labelstringOptionalformat: "^[A-Za-z0-9_-]{1,64}$"

max_participantsintegerOptional2-50Defaults to 10

hold_audio_urlstringOptionalformat: "uri"

speaking_eventsbooleanOptionalDefaults to false

Send participant.speaking whenever the active speaker changes. Off by default because it can fire several times a second.

metadatamap from strings to stringsOptional

participantslist of objectsOptional

Participants to add right away. Existing calls are added first, so the conference is live before dialed participants answer.

Response

Conference created.

idstring

labelstring or null

statusenum

waiting: Created, but nobody has joined yet.
active: At least one participant has joined.
ended: Over. Every participant’s call has been hung up.

Allowed values:

participant_countinteger

Participants currently joined.

max_participantsinteger2-50

hold_audio_urlstring or null

What participants on hold hear.

speaking_eventsboolean

Whether participant.speaking events are sent when the active speaker changes.

metadatamap from strings to strings

created_atstringformat: "date-time"

started_atstring or nullformat: "date-time"

ended_atstring or nullformat: "date-time"

ended_reasonenum or null

Why a conference ended. A conference never ends just because one person is left.

empty: The last participant left.
ended_by_api: Ended with DELETE /conferences/{id} or the conference.end command.
participant_ended_it: A participant added with end_conference_on_leave: true left.
time_limit: Reached the 4-hour limit.
expired_waiting: Nobody joined in time.
failed: The conference couldn’t be started.

participantslist of objects

Errors

400

Bad Request Error

401

Unauthorized Error

409

Conflict Error

500

Internal Server Error

502

Bad Gateway Error

Authentication

Headers

Request

Response

Errors