> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# transcribe

> Start transcribing speech on an active call via REST.

Start transcribing an active call in the background. The transcription covers the whole
call and completes when the call ends. For real-time transcription, use live transcription.
Status updates are delivered to the optional `status_url`.

`control_id` is a caller-chosen identifier for this operation, unique per
active operation of this kind on the call. The TypeScript SDK types it as
optional, but the API requires it — a request that omits it is rejected.

Keep it to stop the transcription later with
[`transcribeStop`](/docs/server-sdks/reference/typescript/rest/calling/transcribe-stop).

## **Request**

### Schema (`Calling.CallTranscribeRequest`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    CallingCallTranscribeRequestCommand:
      type: string
      enum:
        - calling.transcribe
      description: >-
        The `calling.transcribe` command starts transcribing an active call in
        the background.
      title: CallingCallTranscribeRequestCommand
    CallingCallTranscribeRequestParams:
      type: object
      properties:
        control_id:
          type: string
          description: >-
            Unique identifier for this transcription operation, used to control
            it later.
        status_url:
          type: string
          format: uri
          description: >-
            An HTTP or HTTPS URL that receives the status callback when the
            transcription finishes.
      required:
        - control_id
      description: An object of parameters that will be utilized by the active command.
      title: CallingCallTranscribeRequestParams
    Calling.CallTranscribeRequest:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: The unique identifying ID of an existing call.
        command:
          $ref: '#/components/schemas/CallingCallTranscribeRequestCommand'
          description: >-
            The `calling.transcribe` command starts transcribing an active call
            in the background.
        params:
          $ref: '#/components/schemas/CallingCallTranscribeRequestParams'
          description: An object of parameters that will be utilized by the active command.
      required:
        - id
        - command
        - params
      title: Calling.CallTranscribeRequest
```

## **Response**

### Schema (`Calling.CallResponse`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    Calling.CallDirection:
      type: string
      enum:
        - inbound
        - outbound
        - outbound-api
      description: The direction of the call.
      title: Calling.CallDirection
    CallingCallLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingCallLegSource
    Calling.ChargeDetails:
      type: object
      properties:
        description:
          type: string
          description: Description for this charge.
        charge:
          type: number
          format: double
          description: Charged amount.
      required:
        - description
        - charge
      description: One itemized charge applied to the call.
      title: Calling.ChargeDetails
    Calling.CallResponseStatus:
      type: string
      enum:
        - queued
        - initiated
        - created
        - ringing
        - answered
        - ending
        - ended
        - failed
        - canceled
        - completed
      description: The status of the call throughout its lifecycle.
      title: Calling.CallResponseStatus
    CallingCallLegType0:
      type: string
      enum:
        - relay_pstn_call
      title: CallingCallLegType0
    CallingCallLegType1:
      type: string
      enum:
        - relay_sip_call
      title: CallingCallLegType1
    CallingCallLegType2:
      type: string
      enum:
        - relay_webrtc_call
      title: CallingCallLegType2
    CallingCallLegType:
      oneOf:
        - $ref: '#/components/schemas/CallingCallLegType0'
        - $ref: '#/components/schemas/CallingCallLegType1'
        - $ref: '#/components/schemas/CallingCallLegType2'
      description: Type of this call.
      title: CallingCallLegType
    Calling.CallLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingCallLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          oneOf:
            - $ref: '#/components/schemas/Calling.CallResponseStatus'
            - type: 'null'
          description: The status of the call.
        duration:
          type:
            - integer
            - 'null'
          description: The duration of the call in seconds.
        duration_ms:
          type:
            - integer
            - 'null'
          description: The duration of the call in milliseconds.
        billing_ms:
          type:
            - integer
            - 'null'
          description: The billable duration of the call in milliseconds.
        type:
          $ref: '#/components/schemas/CallingCallLegType'
          description: Type of this call.
        parent_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: The parent call ID if this is a child call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - duration
        - duration_ms
        - billing_ms
        - type
        - parent_id
      description: Returned when the call is a standard PSTN, SIP, or WebRTC call.
      title: Calling.CallLeg
    CallingFabricDeviceLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingFabricDeviceLegSource
    CallingFabricDeviceLegType:
      type: string
      enum:
        - fabric_subscriber_device_leg
      description: Type of this call.
      title: CallingFabricDeviceLegType
    Calling.FabricDeviceLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingFabricDeviceLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          description: >-
            The status of the call. Always null for Fabric subscriber device
            legs.
        type:
          $ref: '#/components/schemas/CallingFabricDeviceLegType'
          description: Type of this call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - type
      description: >-
        Returned when the call is a Fabric subscriber device leg. The `status`
        field is always null for this type.
      title: Calling.FabricDeviceLeg
    Calling.CallResponse:
      oneOf:
        - $ref: '#/components/schemas/Calling.CallLeg'
        - $ref: '#/components/schemas/Calling.FabricDeviceLeg'
      title: Calling.CallResponse
```

## **Example**

```typescript {9}
import { RestClient } from "@signalwire/sdk";

const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});

await client.calling.transcribe("call-id-xxx", {
  control_id: "transcribe-1",
  status_url: "https://example.com/transcribe-status",
});
```

> Start transcribing speech on an active call via REST.