> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.telekesher.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.telekesher.dev/_mcp/server. # Play prompt and collect DTMF digits POST https://api.telekesher.dev/v1/sessions/{uuid}/play_and_get_digits Content-Type: application/json **Rate limit: Per command** · **Burst:** 4 · **Refill:** 0.8 req/s This POST has its own bucket. The cancel DELETE is configured identically, but uses a separate bucket. Play an audio prompt and collect DTMF digits from the caller. **Single-shot:** the gateway runs exactly one prompt/collect cycle and emits one `digits.collected` carrying a `status`. The gateway never retries on its own — **the client owns the retry loop**: inspect the `status` field and re-issue this command with whatever prompt fits (e.g. an "invalid PIN" prompt on `status: invalid`). **Triggered webhooks:** `digits.collected`. Individual `dtmf.received` events also fire during collection. For every finite prompt source, the gateway probes with HEAD first and falls back to a ranged GET. A prompt that cannot be prepared returns a synchronous HTTP error and emits no webhook. Reference: https://docs.telekesher.dev/api/collect-keypad-input/collect ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: voice-api version: 1.0.0 paths: /v1/sessions/{uuid}/play_and_get_digits: post: operationId: playPromptAndCollectDTMFDigits summary: Play prompt and collect DTMF digits description: >- **Rate limit: Per command** · **Burst:** 4 · **Refill:** 0.8 req/s This POST has its own bucket. The cancel DELETE is configured identically, but uses a separate bucket. Play an audio prompt and collect DTMF digits from the caller. **Single-shot:** the gateway runs exactly one prompt/collect cycle and emits one `digits.collected` carrying a `status`. The gateway never retries on its own — **the client owns the retry loop**: inspect the `status` field and re-issue this command with whatever prompt fits (e.g. an "invalid PIN" prompt on `status: invalid`). **Triggered webhooks:** `digits.collected`. Individual `dtmf.received` events also fire during collection. For every finite prompt source, the gateway probes with HEAD first and falls back to a ranged GET. A prompt that cannot be prepared returns a synchronous HTTP error and emits no webhook. tags: - collectKeypadInput parameters: - name: uuid in: path description: '[Session](/api/sessions) UUID (format `{5-char-prefix}-{uuid}`).' required: true schema: type: string - name: Authorization in: header description: >- Application auth. Send `Authorization: Bearer :`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details. required: true schema: type: string - name: Idempotency-Key in: header description: >- Optional client-generated key for a mutating endpoint. It identifies one method, route, query, content type, and exact raw body within the authenticated app. Reusing it for a different request returns 422. While its record exists, a retry replays the original accepted response when available. Keys are valid for 1 hour. Allowed characters: letters, digits, dot, hyphen, underscore; max 128 characters. See the Idempotency guide. required: false schema: type: string responses: '202': description: Command accepted for async execution content: application/json: schema: $ref: '#/components/schemas/AsyncCommandResponse' '400': description: >- Missing `Authorization`, malformed Bearer credentials, or invalid request parameters. A syntactically valid credential with an invalid API key returns `401` instead. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestBadRequestError '401': description: >- The Bearer credential is syntactically valid but its API key is invalid. Missing `Authorization` or malformed Bearer credentials return `400`. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestUnauthorizedError '404': description: >- The requested resource was not found or is not owned by the authenticated app. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestNotFoundError '409': description: A media transition is already in progress; retry after it settles. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestConflictError '413': description: Request body exceeds the endpoint's size limit. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestContentTooLargeError '415': description: >- A request with a JSON body must use `Content-Type: application/json`. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestUnsupportedMediaTypeError '422': description: >- The `Idempotency-Key` was reused with a different request body. A key maps to one request; use a new key. See the Idempotency guide. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestUnprocessableEntityError '429': description: >- Rate limit exceeded — a per-command, per-room, or per-app token bucket was empty. The `retry_after` field gives the integer seconds to wait before retrying. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestTooManyRequestsError '500': description: Internal gateway error. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestInternalServerError '502': description: The prompt source is unavailable, so the command was not accepted. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestBadGatewayError '503': description: >- Playback stop unavailable while replacing the active prompt or playback. content: application/json: schema: $ref: >- #/components/schemas/PlayPromptAndCollectDTMFDigitsRequestServiceUnavailableError requestBody: content: application/json: schema: type: object properties: operation_uuid: type: string format: uuid description: >- Optional caller-supplied per-command correlation id, a bare lowercase RFC-4122 v4 UUID (no prefix). Echoed back as `operation_uuid` in the 202 ack. A later lifecycle webhook carries it only when the gateway can unambiguously associate that event with this command; the field is correlation, not proof of causation. When omitted, the gateway mints one. Not an idempotency key — request deduplication is the `Idempotency-Key` header. Invalid input (not a v4 UUID) is rejected with `400 invalid_request`. between_digits_timeout_ms: type: integer default: 2000 description: Milliseconds to wait between digits before timing out. first_digit_timeout_ms: type: integer default: 5000 description: Milliseconds to wait for the first digit before timing out. max_digits: type: integer default: 10 description: Maximum digits to collect. Must be >= min_digits. min_digits: type: integer default: 1 prompt_files: type: array items: type: string format: uri description: Audio URLs to play as the prompt (http(s) only). terminators: type: array items: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostRequestBodyContentApplicationJsonSchemaTerminatorsItems default: - '#' description: 'DTMF terminator characters. Only # and * allowed.' validation: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostRequestBodyContentApplicationJsonSchemaValidation description: Optional input validation. required: - prompt_files servers: - url: https://api.telekesher.dev description: Gateway server components: schemas: V1SessionsUuidPlayAndGetDigitsPostRequestBodyContentApplicationJsonSchemaTerminatorsItems: type: string enum: - '#' - '*' title: >- V1SessionsUuidPlayAndGetDigitsPostRequestBodyContentApplicationJsonSchemaTerminatorsItems V1SessionsUuidPlayAndGetDigitsPostRequestBodyContentApplicationJsonSchemaValidation: type: object properties: regex: type: string description: >- RE2 regular expression the collected digits must match (no whitespace, <=256 chars). On match-and-fail, status is `invalid`. description: Optional input validation. title: >- V1SessionsUuidPlayAndGetDigitsPostRequestBodyContentApplicationJsonSchemaValidation AsyncCommandResponseStatus: type: string enum: - in_progress - completed title: AsyncCommandResponseStatus AsyncCommandResponse: type: object properties: operation_uuid: type: string format: uuid status: $ref: '#/components/schemas/AsyncCommandResponseStatus' already_ended: type: boolean enum: - true description: >- Optional. Set to `true` on idempotent terminal commands when the session was already in a terminal state at the time the request was received. Absent otherwise. required: - operation_uuid - status description: >- 202 Accepted body for an async command. The command's success/failure is delivered later as a domain lifecycle webhook (e.g. `playback.started`/`stopped`/`failed`, `command.recording.start.accepted`, `digits.collected`, `session.answered`/`session.ended`). A lifecycle event carries `operation_uuid` only when it can be unambiguously associated with the submitted command — not as a generic ack on this response. title: AsyncCommandResponse V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode: type: string enum: - invalid_request - payload_too_large - result_set_too_large - unauthorized - forbidden - not_found - conflict - recording_not_active - room_full - rate_limited - unavailable - internal description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. title: >- V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode PlayPromptAndCollectDTMFDigitsRequestBadRequestError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestBadRequestError PlayPromptAndCollectDTMFDigitsRequestUnauthorizedError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestUnauthorizedError PlayPromptAndCollectDTMFDigitsRequestNotFoundError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestNotFoundError PlayPromptAndCollectDTMFDigitsRequestConflictError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestConflictError PlayPromptAndCollectDTMFDigitsRequestContentTooLargeError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestContentTooLargeError PlayPromptAndCollectDTMFDigitsRequestUnsupportedMediaTypeError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestUnsupportedMediaTypeError PlayPromptAndCollectDTMFDigitsRequestUnprocessableEntityError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestUnprocessableEntityError PlayPromptAndCollectDTMFDigitsRequestTooManyRequestsError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - retry_after - success title: PlayPromptAndCollectDTMFDigitsRequestTooManyRequestsError PlayPromptAndCollectDTMFDigitsRequestInternalServerError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestInternalServerError PlayPromptAndCollectDTMFDigitsRequestBadGatewayError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestBadGatewayError PlayPromptAndCollectDTMFDigitsRequestServiceUnavailableError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidPlayAndGetDigitsPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: PlayPromptAndCollectDTMFDigitsRequestServiceUnavailableError securitySchemes: bearerAppAuth: type: http scheme: bearer description: >- Application auth. Send `Authorization: Bearer :`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details. ``` ## Examples **Request** ```json { "prompt_files": [ "https://cdn.example.com/enter-pin.wav" ], "between_digits_timeout_ms": 2000, "first_digit_timeout_ms": 10000, "max_digits": 6, "min_digits": 4, "terminators": [ "#" ], "validation": { "regex": "^[0-9]{4,6}$" } } ``` **Response** ```json { "operation_uuid": "550e8400-e29b-41d4-a716-446655440000", "status": "in_progress" } ``` **SDK Code** ```python Collect keypad input_playPromptAndCollectDTMFDigits_example import requests url = "https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits" payload = { "prompt_files": ["https://cdn.example.com/enter-pin.wav"], "between_digits_timeout_ms": 2000, "first_digit_timeout_ms": 10000, "max_digits": 6, "min_digits": 4, "terminators": ["#"], "validation": { "regex": "^[0-9]{4,6}$" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Collect keypad input_playPromptAndCollectDTMFDigits_example const url = 'https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"prompt_files":["https://cdn.example.com/enter-pin.wav"],"between_digits_timeout_ms":2000,"first_digit_timeout_ms":10000,"max_digits":6,"min_digits":4,"terminators":["#"],"validation":{"regex":"^[0-9]{4,6}$"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Collect keypad input_playPromptAndCollectDTMFDigits_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits" payload := strings.NewReader("{\n \"prompt_files\": [\n \"https://cdn.example.com/enter-pin.wav\"\n ],\n \"between_digits_timeout_ms\": 2000,\n \"first_digit_timeout_ms\": 10000,\n \"max_digits\": 6,\n \"min_digits\": 4,\n \"terminators\": [\n \"#\"\n ],\n \"validation\": {\n \"regex\": \"^[0-9]{4,6}$\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Collect keypad input_playPromptAndCollectDTMFDigits_example require 'uri' require 'net/http' url = URI("https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"prompt_files\": [\n \"https://cdn.example.com/enter-pin.wav\"\n ],\n \"between_digits_timeout_ms\": 2000,\n \"first_digit_timeout_ms\": 10000,\n \"max_digits\": 6,\n \"min_digits\": 4,\n \"terminators\": [\n \"#\"\n ],\n \"validation\": {\n \"regex\": \"^[0-9]{4,6}$\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Collect keypad input_playPromptAndCollectDTMFDigits_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"prompt_files\": [\n \"https://cdn.example.com/enter-pin.wav\"\n ],\n \"between_digits_timeout_ms\": 2000,\n \"first_digit_timeout_ms\": 10000,\n \"max_digits\": 6,\n \"min_digits\": 4,\n \"terminators\": [\n \"#\"\n ],\n \"validation\": {\n \"regex\": \"^[0-9]{4,6}$\"\n }\n}") .asString(); ``` ```php Collect keypad input_playPromptAndCollectDTMFDigits_example request('POST', 'https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits', [ 'body' => '{ "prompt_files": [ "https://cdn.example.com/enter-pin.wav" ], "between_digits_timeout_ms": 2000, "first_digit_timeout_ms": 10000, "max_digits": 6, "min_digits": 4, "terminators": [ "#" ], "validation": { "regex": "^[0-9]{4,6}$" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Collect keypad input_playPromptAndCollectDTMFDigits_example using RestSharp; var client = new RestClient("https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"prompt_files\": [\n \"https://cdn.example.com/enter-pin.wav\"\n ],\n \"between_digits_timeout_ms\": 2000,\n \"first_digit_timeout_ms\": 10000,\n \"max_digits\": 6,\n \"min_digits\": 4,\n \"terminators\": [\n \"#\"\n ],\n \"validation\": {\n \"regex\": \"^[0-9]{4,6}$\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Collect keypad input_playPromptAndCollectDTMFDigits_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "prompt_files": ["https://cdn.example.com/enter-pin.wav"], "between_digits_timeout_ms": 2000, "first_digit_timeout_ms": 10000, "max_digits": 6, "min_digits": 4, "terminators": ["#"], "validation": ["regex": "^[0-9]{4,6}$"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.telekesher.dev/v1/sessions/uuid/play_and_get_digits")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```