> 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. # collect > Collect user input (DTMF or speech) on an active call via REST. Start collecting user input on an active call. Supports DTMF digit collection and speech recognition. `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 manage the collection later. ## **Request** ### Schema (`calling.collect`) ```yaml components: schemas: uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid Calling.CollectDigitsParams: type: object properties: max: type: integer description: Maximum number of digits to collect. Must be positive. terminators: type: string description: >- DTMF digits that terminate input when pressed. Allowed: `0-9`, `A-D` (case insensitive), `*`, `#`. Empty string disables terminators. digit_timeout: type: number format: double description: >- Time in seconds to wait between digit presses. Must be positive. Defaults to the server-configured digit timeout when omitted. required: - max description: Parameters for collecting DTMF digit input. title: Calling.CollectDigitsParams Calling.CollectSpeechEngine: type: string enum: - Google - Google.V2 - Deepgram description: >- Speech recognition engine for `calling.collect`. Note: values are case-sensitive. title: Calling.CollectSpeechEngine Calling.CollectSpeechParams: type: object properties: end_silence_timeout: type: number format: double description: >- Time in seconds of silence after speech to consider input complete. Must be positive. speech_timeout: type: number format: double description: Maximum time in seconds to wait for speech input. Must be positive. language: type: string description: >- Speech recognition language. Accepts a BCP-47 tag (e.g. `en-US`) or an `engine:tag` override (e.g. `Deepgram:en-US`) to pick a specific engine. Defaults to the server-configured ASR language when omitted. hints: type: array items: type: string description: Array of words or phrases to bias the speech recognition. model: type: string description: >- Provider-specific ASR model name (e.g. Deepgram `nova-3`). Freeform string; validation is performed by the selected engine. engine: $ref: '#/components/schemas/Calling.CollectSpeechEngine' description: Speech recognition engine to use. description: Parameters for collecting speech input. title: Calling.CollectSpeechParams CallingCallRequestDiscriminatorMappingCallingCollectParams: type: object properties: control_id: type: string description: >- Unique identifier for this collect operation, used to control it later. Must be unique per active collect on this call. initial_timeout: type: number format: double description: >- Maximum time in seconds to wait for initial input. Must be positive. Defaults to the server-configured no-input timeout when omitted. digits: $ref: '#/components/schemas/Calling.CollectDigitsParams' description: >- Configuration for collecting DTMF digit input. Provide `digits`, `speech`, or both. speech: $ref: '#/components/schemas/Calling.CollectSpeechParams' description: >- Configuration for collecting speech input. Provide `digits`, `speech`, or both. continuous: type: boolean default: false description: >- If `true`, the collect restarts after each result until `calling.collect.stop` is called. Continuous events include a `state` field indicating collect state. partial_results: type: boolean default: false description: >- If `true`, partial results are delivered as they are recognized, and events include a `final` field (`false` for partial, `true` for final). send_start_of_input: type: boolean default: false description: >- If `true`, a `start_of_input` webhook event is fired when input is first detected. start_input_timers: type: boolean default: false description: >- If `false`, the initial-timeout clock does not start until `calling.collect.start_input_timers` is called for this `control_id`. status_url: type: string format: uri description: HTTP or HTTPS URL that receives collect result webhooks. required: - control_id description: An object of parameters that will be utilized by the active command. title: CallingCallRequestDiscriminatorMappingCallingCollectParams Calling.CallCollectRequest: type: object properties: id: $ref: '#/components/schemas/uuid' description: The unique identifying ID of an existing call. params: $ref: >- #/components/schemas/CallingCallRequestDiscriminatorMappingCallingCollectParams description: An object of parameters that will be utilized by the active command. required: - id - params title: Calling.CallCollectRequest ``` ## **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 ``` ## **Examples** ### Collect DTMF Digits ```typescript {10-14} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); // Collect DTMF digits under a control ID you choose const result = await client.calling.collect("call-id-xxx", { control_id: "pin-collect-1", digits: { max: 4, terminators: "#", digit_timeout: 5.0 }, initial_timeout: 10.0, }); ``` ### Collect Speech ```typescript {9-15} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const result = await client.calling.collect("call-id-xxx", { control_id: "speech-collect-1", speech: { end_silence_timeout: 1.0, language: "en-US", }, }); ``` ### Collect Both ```typescript {9-14} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const result = await client.calling.collect("call-id-xxx", { control_id: "combined-collect-1", digits: { max: 1, terminators: "#" }, speech: { end_silence_timeout: 2.0 }, initial_timeout: 15.0, }); ``` > Collect user input (DTMF or speech) on an active call via REST.