Browse the Telegram voice catalog
Returns a page of voices for Telegram voice messages, ordered by popularity (most popular first), as a data array.
Returns a page of voices for Telegram voice messages, ordered by popularity (most popular first), as a data array. Each entry carries a stable slug — the value you pass as telegram.voice.voiceId on a voice send — plus name, description, bestLanguage, languages, gender, tags, featured, and popularity; the top-level default field names the voice used when a send omits voiceId (currently adrian). limit defaults to 50 and is clamped to 1–100, and offset (default 0) drives plain offset paging — there is no cursor, and count reports the size of the returned page, not the catalog total, so keep paging until you get a short page. language filters to voices whose best language matches the given code (en, de, es, …), and featured=true returns only celebrity and character voices. Passing q switches the call into relevance-ranked search: results come back with mode set to search, an echoed query, and a score on each row, and in that mode offset and featured no longer apply (page size still honors limit). This is a read-only call — no idempotency key, no side effects — that any valid API key may make regardless of its scopes; sustained reads share your account's per-key read rate limit and return 429 when it is exceeded. Pass kind=phone to get the phone voice catalog instead — the 22 Dairo Live voices accepted as voice on POST /v1/phone/calls — where each row is { voiceId, name, description, language, gender, accent } (language is multilingual, en, or pt) and language, gender, and q filter it; the same rows are served by GET /v1/phone/voices.
Scope: __any__. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
language | string | no | Filter by best language (e.g. en, de, es). |
q | string | no | Free-text search over name and description. |
featured | boolean | no | Only celebrity/character voices. |
limit | integer | no | Maximum number of items in the page. (minimum 1, maximum 100, default 50) |
offset | integer | no | (minimum 0, default 0) |
kind | "tts", "phone" | no | tts (default) for the Telegram TTS catalog, or phone for the Dairo Live phone voices (rows shaped like PhoneVoice). (default "tts") |
gender | string | no | Filter by gender. |
Response
200 Success. Body: application/json, object.
| Field | Type | Required | Description |
|---|---|---|---|
object | string | no | |
count | integer | no | |
limit | integer | no | |
offset | integer | no | |
default | string | no | |
data | array of TelegramVoice | no |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
List a contact's message history
Returns the contact's cross-channel message history — inbound and outbound messages merged into a single newest-first list — so you can read the whole relationship across email, a2a, telegram, and other channels in one call.
List the phone numbers this account owns
Returns the phone numbers this account owns, newest first, as a { object: "list", data } array.