Skip to navigation
API OverviewKeypad (DTMF)

Send DTMF sequence

View as Markdown

Rate limit: Per command · Burst: 20 · Refill: 20 req/s

Send an ordered sequence of DTMF key presses and waits to the remote party during an answered phone session. Each action specifies its key-press duration or wait. The platform preserves action order, but a wait.duration_ms value is a minimum delay and the next action might start later.

The platform accepts only one active sequence per session. It does not accept this command for ringing calls or WebSocket sessions created with POST /v1/sessions:connectWebsocket.

A 202 response confirms that the platform durably admitted the sequence. It does not confirm that the remote party handled the keys, and the platform does not emit an acceptance webhook.

See Keypad input lifecycle events for complete payload schemas and examples.

Authentication

AuthorizationBearer

Send Authorization: Bearer <app_uuid>:<api_key> using an active API key. See Authentication for details.

Path parameters

uuidstringRequired

Session identifier.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]*$"<=128 characters

Optional key for safely retrying mutating requests. An explicitly empty header is treated like omission and does not enable replay protection. See Idempotency for details.

Operation-IdstringOptionalformat: "uuid"

optional client-supplied lowercase RFC-4122 v4 UUID returned as operation_uuid; platform generates one when omitted; correlation metadata distinct from Idempotency-Key.

Request

This endpoint expects an object.
sequencelist of objectsRequired
Ordered key and wait actions. Waits may appear anywhere and consecutive waits are allowed. The total nominal duration may not exceed ten minutes, and the sequence must include at least one key action.

Response headers

traceparentstringOptionalformat: "^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"=55 characters

Server-owned W3C Trace Context for correlating this response with support and observability data. It is present on successful and error responses. A valid incoming traceparent is linked to, but never becomes, the server-owned trace identifier.

Response

Command accepted for async execution
operation_uuidstring
statusenum
Allowed values:
already_endedtrueOptional

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.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
406
Not Acceptable Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error