--- title: "Start recording a call" method: POST path: "/service_agents/calls/{id}/recording_start" tags: ["Service Agent"] --- # Start recording a call `POST /service_agents/calls/{id}/recording_start` ## Request - Base URL: `https://api.voipbin.net/v1.0` - URL: `https://api.voipbin.net/v1.0/service_agents/calls/{id}/recording_start` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Starts recording a call the calling agent owns. The call must be owned by the calling agent, belong to the agent's customer, and be in progress (answered). A call that is still ringing is rejected with 400 and is not answered by this request. If the call is already being recorded, the response is 409. Every field is optional. `duration` defaults to 7200 seconds (2 hours) and cannot be 0 or more than 7200 on this endpoint. A recording that ends on its own (silence, duration, or end key) clears the call's `recording_id`. The platform does not announce the recording to the other party. Informing the other party is the organization's responsibility. ## Path parameters - `id` string, uuid, required ## Request body - object - `format` 'wav': The format of the recording. - `end_of_silence` integer: The duration of silence (in seconds) after which the recording stops. 0 keeps recording regardless of silence. - `end_of_key` string: The DTMF key that stops the recording. - `duration` integer: The maximum duration of the recording (in seconds). If omitted, 7200 is used. ## Response `200` The call, with the `recording_id` of the started recording. - CallManagerCall - `id` string, uuid: The unique identifier of the call. - `customer_id` string, uuid: The customer ID that owns this call. Returned from the `GET /customers` response. - `owner_type` string: Type of the resource owner (e.g., agent, queue). - `owner_id` string, uuid: The unique identifier of the resource owner. Returned from the corresponding owner resource endpoint (e.g., `GET /agents`, `GET /queues`). - `flow_id` string, uuid: The flow ID associated with this call. Returned from the `POST /flows` or `GET /flows` response. - `activeflow_id` string, uuid: The activeflow ID associated with this call. Returned from the `POST /activeflows` or `GET /activeflows` response. - `type` '' | 'flow' | 'conference' | 'sip-service': Call type - `master_call_id` string, uuid: The unique identifier of the master call that initiated this call. Returned from the `POST /calls` or `GET /calls` response. - `chained_call_ids` string[]: Chained call IDs. Each ID is returned from the `POST /calls` or `GET /calls` response. - `recording_id` string, uuid: The current recording ID. Returned from the `GET /recordings` response. - `recording_ids` string[]: Recording IDs associated with this call. Each ID is returned from the `GET /recordings` response. - `groupcall_id` string, uuid: Group call ID. Returned from the `POST /groupcalls` or `GET /groupcalls` response. Indicates this call is part of a group call. - `source` CommonAddress: Contains source or destination detail info. - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session': Type of address. - `target` string: The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip. - `target_name` string: Address's name. - `name` string: Optional label for this address. - `detail` string: Additional notes about this address. - `destination` CommonAddress: Contains source or destination detail info. - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session': Type of address. - `target` string: The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip. - `target_name` string: Address's name. - `name` string: Optional label for this address. - `detail` string: Additional notes about this address. - `status` 'dialing' | 'ringing' | 'progressing' | 'terminating' | 'canceling' | 'hangup': Call status - `action` FlowManagerAction - `id` string, uuid, required: The unique identifier of this action within the flow. - `next_id` string, uuid: The identifier of the next action to execute. References an action `id` within the same flow's `actions` array. Null if this is the last action. - `type` 'ai_talk' | 'ai_summary' | 'amd' | 'answer' | 'beep' | 'branch' | 'call' | 'condition_call_digits' | 'condition_call_status' | 'condition_datetime' | 'condition_variable' | 'confbridge_join' | 'conference_join' | 'connect' | 'conversation_send' | 'digits_receive' | 'digits_send' | 'echo' | 'email_send' | 'external_media_start' | 'external_media_stop' | 'fetch' | 'fetch_flow' | 'goto' | 'hangup' | 'message_send' | 'mute' | 'play' | 'queue_join' | 'recording_start' | 'recording_stop' | 'sleep' | 'stop' | 'stream_echo' | 'talk' | 'transcribe_start' | 'transcribe_stop' | 'transcribe_recording' | 'variable_set' | 'webhook_send', required: Type of the action. - `option` object: Additional options based on the `type` field. - For `FlowManagerActionTypeAISummary`: see `FlowManagerActionOptionAISummary` - For `FlowManagerActionTypeAITalk`: see `FlowManagerActionOptionAITalk` - For `FlowManagerActionTypeAMD`: see `FlowManagerActionOptionAMD` - For `FlowManagerActionTypeAnswer`: see FlowManagerActionOptionAnswer - For `FlowManagerActionTypeBeep`: see FlowManagerActionOptionBeep - For `FlowManagerActionTypeBranch`: see FlowManagerActionOptionBranch - For `FlowManagerActionTypeCall`: see FlowManagerActionOptionCall - For `FlowManagerActionTypeConfbridgeJoin`: see FlowManagerActionOptionConfbridgeJoin - For `FlowManagerActionTypeConferenceJoin`: see FlowManagerActionOptionConferenceJoin - For `FlowManagerActionTypeConnect`: see FlowManagerActionOptionConnect - For `FlowManagerActionTypeConversationSend`: see FlowManagerActionOptionConversationSend - For `FlowManagerActionTypeDigitsReceive`: see FlowManagerActionOptionDigitsReceive - For `FlowManagerActionTypeDigitsSend`: see FlowManagerActionOptionDigitsSend - For `FlowManagerActionTypeEcho`: see FlowManagerActionOptionEcho - For `FlowManagerActionTypeEmailSend`: see FlowManagerActionOptionEmailSend - For `FlowManagerActionTypeExternalMediaStart`: see FlowManagerActionOptionExternalMediaStart - For `FlowManagerActionTypeExternalMediaStop`: see FlowManagerActionOptionExternalMediaStop - For `FlowManagerActionTypeFetch`: see FlowManagerActionOptionFetch - For `FlowManagerActionTypeFetchFlow`: see FlowManagerActionOptionFetchFlow - For `FlowManagerActionTypeGoto`: see FlowManagerActionOptionGoto - For `FlowManagerActionTypeHangup`: see FlowManagerActionOptionHangup - For `FlowManagerActionTypeMessageSend`: see FlowManagerActionOptionMessageSend - For `FlowManagerActionTypePlay`: see FlowManagerActionOptionPlay - For `FlowManagerActionTypeQueueJoin`: see FlowManagerActionOptionQueueJoin - For `FlowManagerActionTypeRecordingStart`: see FlowManagerActionOptionRecordingStart - For `FlowManagerActionTypeRecordingStop`: see FlowManagerActionOptionRecordingStop - For `FlowManagerActionTypeSleep`: see FlowManagerActionOptionSleep - For `FlowManagerActionTypeStreamEcho`: see FlowManagerActionOptionStreamEcho - For `FlowManagerActionTypeTalk`: see FlowManagerActionOptionTalk - For `FlowManagerActionTypeTranscribeStart`: see FlowManagerActionOptionTranscribeStart - For `FlowManagerActionTypeTranscribeStop`: see FlowManagerActionOptionTranscribeStop - For `FlowManagerActionTypeTranscribeRecording`: see FlowManagerActionOptionTranscribeRecording - For `FlowManagerActionTypeVariableSet`: see FlowManagerActionOptionVariableSet - For `FlowManagerActionTypeWebhookSend`: see FlowManagerActionOptionWebhookSend - ... - `tm_execute` string, date-time: Timestamp when this action was executed. - `direction` 'incoming' | 'outgoing': Call direction - `mute_direction` '' | 'both' | 'out' | 'in': Possible mute directions for the call - `hangup_by` '' | 'remote' | 'local': Indicates who hung up the call - `hangup_reason` '' | 'normal' | 'failed' | 'busy' | 'cancel' | 'timeout' | 'noanswer' | 'dialout' | 'amd': Reason for call hangup - `metadata` object, nullable: Internal metadata for the call. Contains key-value pairs set by the system. Currently supported keys: - `rtp_debug` (boolean): When `true`, RTPEngine is capturing RTP traffic for this call. - `tm_progressing` string, date-time: Timestamp for call progressing. - `tm_ringing` string, date-time: Timestamp for call ringing. - `tm_hangup` string, date-time: Timestamp for call hangup. - `tm_create` string, date-time: The creation timestamp. - `tm_update` string, date-time: The last update timestamp. - `tm_delete` string, date-time: The deletion timestamp, if applicable. ## Other responses - `400`: Invalid request (INVALID_ARGUMENT). - `401`: Authentication required (UNAUTHENTICATED). - `403`: Insufficient permission (PERMISSION_DENIED). - `404`: Resource not found (NOT_FOUND). - `409`: State conflict (ALREADY_EXISTS or FAILED_PRECONDITION). - `500`: Internal error (INTERNAL). - `503`: Upstream unavailable (UNAVAILABLE). ## Changes - **2026-11-02** `c4ee74347a54`: 1 info - endpoint added [Operation history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/service_agents/calls/:id/recording_start/post.md) --- [API](https://skmtc.dev/voipbin/apis/voipbin-api.md) - [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/a3618cfd2159?raw)