Conferences

Create Conference

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.

post/conferences

Request

  • Base URL: https://api.pinnacle.sh
  • URL: https://api.pinnacle.sh/conferences
  • Auth: API key in header PINNACLE-API-KEY

Headers

Idempotency-Keystring

Request body

labelstring
max_participantsinteger
hold_audio_urlstring uri
speaking_eventsboolean

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

metadataobject

Response

Conference created.

idstring required
labelstring nullable required
status'waiting' | 'active' | 'ended' required
  • waiting: Created, but nobody has joined yet.
  • active: At least one participant has joined.
  • ended: Over. Every participant's call has been hung up.
participant_countinteger required

Participants currently joined.

max_participantsinteger required
hold_audio_urlstring nullable required

What participants on hold hear.

speaking_eventsboolean required

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

metadataobject required
created_atstring date-time required
started_atstring date-time nullable required
ended_atstring date-time nullable required
ended_reason'empty' | 'ended_by_api' | 'participant_ended_it' | 'time_limit' | 'expired_waiting' | 'failed' required

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.

Changes

No recorded changes to this operation across all 1 revision of this API.