Skip to content
TipPage Docs
Esc
↑↓navigate↵open⌘Jpreview

Claim a TTS as now playing

Marks a queued TTS as currently playing - the same call the overlay makes. Fires queue.tts.started. While claimed, other consumers get 409 already_playing. If your effect then fails and the tip should not count as played, undo the claim with release instead of finishing. See the claim, do your thing, finish guide for the full pattern. Requires tts:control.

POST/tts/{orderId}/start
Authorization
AuthorizationBearer token (tp_live_... or tpat_...) · headerrequired
A TipPage API key (`tp_live_...`, created in Dashboard → Settings → Developer) or an OAuth 2.0 access token (`tpat_...`, see the OAuth guide). Both carry the same scopes and are accepted on every endpoint.
Path parameters
orderIdstringrequired
The tip's order id (e.g. `tip_1755100000000_ab12cd`) - the only external row reference.
Responses
200Claimed.
successboolean
tipQueueTip
A tip in the pending TTS queue.
Show properties
order_idstring
namestring
Display name (post-filter).
amountnumber | null
messagestring | null
The tip message (post-filter - what shows on stream).
tts_urlstring<uri> | null
Pre-rendered audio; `null` until rendering completes.
is_replayboolean
is_sub_rewardboolean
sourcestring
Where the tip came from: `stripe`, `paypal`, `manual` (dashboard manual tip), `api` (POST /tips), `sub_reward`, `replay`, `test`, `ayupcc`, or `unknown` for tips older than source tracking.
external_sourcestring | null
Developer-API tips only - the `source` label the caller sent (`kofi`, `ayupcc`); `null` for every other source. Says where the tip came from, not whether money moved - see `is_paid`.
external_refstring | null
Developer-API tips only - the caller's own payment reference.
is_paidboolean
Real money changed hands (Stripe, PayPal, or a developer-API tip sent with `paid: true`). `false` for manual tips, free integration tips and sub rewards - those never count toward the streamer's totals.
platformstring | null
The platform of the account the donor was signed in with when they tipped; `null` for an unattributed tip.
Allowed:twitchkicknull
platform_user_idstring | null
The donor's id on that platform, when signed in.
name_was_filteredboolean
message_was_filteredboolean
queued_atstring<date-time>
401Missing or invalid credential (`missing_api_key` / `invalid_api_key`, or `invalid_token` for an expired/revoked OAuth access token).
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
403The key lacks the required scope (`missing_scope`).
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
required_scopestring
404No such resource.
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
409`queue_paused` (the queue is paused) or `already_playing` (another tip holds the slot; `current_order_id` names it).
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
current_order_idstring
429Rate limit exceeded - check the `RateLimit-*` headers.
errorstring
Request
curl -X POST "https://api.tippage.com/v1/tts/string/start" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "success": true,
  "tip": {
    "order_id": "tip_1755100000000_ab12cd",
    "name": "string",
    "amount": 5,
    "message": "string",
    "tts_url": "http://example.com",
    "is_replay": true,
    "is_sub_reward": true,
    "source": "string",
    "external_source": "string",
    "external_ref": "string",
    "is_paid": true,
    "platform": "twitch",
    "platform_user_id": "string",
    "name_was_filtered": true,
    "message_was_filtered": true,
    "queued_at": "2019-08-24T14:15:22Z"
  }
}