Calls

Update Call Metadata

Replace a call's metadata. For live calls, future call events carry the updated metadata.

patch/calls/{id}

Request

  • Base URL: https://api.pinnacle.sh
  • URL: https://api.pinnacle.sh/calls/{id}
  • Auth: API key in header PINNACLE-API-KEY

Path parameters

idstring required

Pinnacle call ID.

Request body

metadataCallMetadata required

String metadata carried on future call events. Maximum serialized size is 2 KB.

Response

Updated call.

idstring required
state'INITIATED' | 'RINGING' | 'ANSWERED' | 'BRIDGED' | 'ENDED' | 'FAILED' | 'NO_ANSWER' | 'BUSY' | 'CANCELED' required

Current voice call lifecycle state. This field is named state on Call objects and status on CALL.STATUS webhook payloads.

  • INITIATED: Pinnacle accepted the call request and is setting up the call with the voice provider.
  • RINGING: The call is ringing and has not been answered yet.
  • ANSWERED: The call has been answered and is active.
  • BRIDGED: The call is connected to another call leg, such as after a transfer or bridge command.
  • ENDED: The call ended normally.
  • FAILED: The call could not be established or could not continue because of a provider or system failure.
  • NO_ANSWER: The call rang until timeout without being answered.
  • BUSY: The destination was busy.
  • CANCELED: The call was canceled before normal completion.
direction'INBOUND' | 'OUTBOUND' required

Direction of the call relative to your Pinnacle team.

  • INBOUND: The call originated from an external caller and was received by one of your Pinnacle voice-enabled phone numbers.
  • OUTBOUND: The call was created from Pinnacle and dialed out from one of your voice-enabled phone numbers.
tostring required
fromstring required
created_atstring date-time required
started_atstring date-time nullable required
answered_atstring date-time nullable required
ended_atstring date-time nullable required
metadataobject required
recordboolean required

Whether recording was requested when this call was created.

This is intent, not progress. recording_state says what happened to the audio; record says whether any was ever asked for. A call with record: true and recording_state: null after it has ended means a recording was expected but never produced.

recording_state'PENDING' | 'READY' | 'FAILED' | 'DELETED' required

Recording processing state for a call.

  • PENDING: Audio was captured and is still being finalized. Download returns 425 until processing completes.
  • READY: The recording is finalized and can be downloaded with a signed URL.
  • FAILED: Recording finalization failed. Download returns 422.
  • DELETED: The recording was deleted. Download returns 410.
hangup_causestring nullable required
conference_idstring nullable

The conference this call is in, or was most recently in; null if never. Returned by GET /calls/{id}.

Changes

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