Skip to navigation
API ReferenceCallsCall Lifecycle

Update Call Metadata

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

Authentication

PINNACLE-API-KEYstring
API Key authentication via header

Path parameters

idstringRequired>=1 character
Pinnacle call ID.

Request

This endpoint expects an object.
metadatamap from strings to stringsRequired
String metadata carried on future call events. Maximum serialized size is 2 KB.

Response

Updated call.
idstring
stateenum

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.
directionenum

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.
Allowed values:
tostring
fromstring
created_atstringformat: "date-time"
started_atstring or nullformat: "date-time"
answered_atstring or nullformat: "date-time"
ended_atstring or nullformat: "date-time"
metadatamap from strings to strings
recordboolean

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_stateenum or null

If no recording has been captured or enabled for the call, then null.

Allowed values:
hangup_causestring or null
conference_idstring or nullOptional

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

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error