# Telavox Developer Portal — full content

> The single-file variant of /llms.txt. Inlines portal overviews, the auth flows, the best-practices guidance, and the v1 → CAPI migration summary so an AI agent can answer most questions in one fetch instead of crawling the site. Always-current OpenAPI specs are available at the URLs listed under each API.

## Customer API (CAPI)
Status: Stable. Customer-facing REST API.

Hub: https://developer.telavox.com/capi
Reference (interactive): https://developer.telavox.com/capi/reference
OpenAPI spec (JSON, fetched live from upstream): https://developer.telavox.com/api/spec/capi
Token onboarding: https://developer.telavox.com/capi/tokens

### Tagline
Build customer-facing integrations against Telavox.

### Who CAPI is for
CAPI is the customer-facing REST API. It is the right choice if you are integrating Telavox into a product or workflow owned by a single Telavox customer (yourself or your employer).

### API conventions
- REST over HTTPS, JSON request and response bodies, UTF-8 encoded.
- Bearer authentication using the JWT issued by Manage tokens.
- Implement exponential backoff for retries — the spec covers the exact policy.

### Get a token
CAPI tokens are user-scoped and minted from your own Telavox account. Anyone with a Telavox login can create one — tokens inherit your user permissions.

Steps to mint a JWT:
- Open the Telavox web or desktop app.
- Go to My Account → Username and Password.
- Choose Manage tokens.
- Create a new token and copy the value immediately.

Use the token:
Send the token in the Authorization header with a Bearer prefix:
  Authorization: Bearer <your-jwt>
The "Test Request" feature on the reference page auto-prepends Bearer if you paste only the JWT, but real clients (curl, Postman, your code) must include the prefix explicitly.

## Partner API (PAPI)
Status: Stable. Partner-facing REST API.

Hub: https://developer.telavox.com/papi
Reference (interactive): https://developer.telavox.com/papi/reference
OpenAPI spec (JSON, fetched live from upstream): https://developer.telavox.com/api/spec/papi
Token onboarding: https://developer.telavox.com/papi/tokens

### Tagline
Build partner integrations and white-label solutions.

### Who PAPI is for
PAPI is aimed at Telavox partners building integrations, white-label solutions, and value-added services on top of Telavox. Tokens are issued to a dedicated API user — not to a human partner login.

### API conventions
- REST over HTTPS, JSON request and response bodies, UTF-8 encoded.
- JWT-based authentication; the JWT is bound to an API user with assigned groups.
- Implement exponential backoff for retries.

### Get a token
PAPI tokens are JWTs bound to a dedicated API user, not to a human partner login. Create them from inside Partner.

Steps to mint a JWT:
- Sign in to Partner with your administrator credentials.
- Go to Administration → Users/Groups.
- Click New group, name it (e.g. "Token Group"), and grant it the permission "Can create their own Partner JWT tokens".
- Go to Administration → Users/Groups → API-tokens and create an API user — fill in the description and contact email.
- Assign the API user to both the Admin group and the new token group.
- Copy the JWT immediately. It is shown once and cannot be retrieved again.

Use the token:
Send the JWT in the Authorization header with a Bearer prefix:
  Authorization: Bearer <your-jwt>
The PAPI backend strips exactly the literal "Bearer " prefix; any other auth scheme or a too-short value results in a 500. The "Test Request" feature on the reference page auto-prepends Bearer if you paste only the JWT, but real clients (curl, Postman, your code) must include the prefix explicitly.

## Legacy v1 API
Status: Deprecated. The previous-generation API. Migrate to CAPI.

Hub: https://developer.telavox.com/v1
Reference (per-actionbean): https://developer.telavox.com/v1/reference
Migration guide → CAPI: https://developer.telavox.com/v1/migration

### Overview
This document describes the services exposed by the legacy v1 API. These services were primarily intended for 3rd-party systems that integrate with Telavox. The reader should be familiar with the end-user application and related concepts before implementing a client.

### Sunset
The v1 API is deprecated and will be removed on 31 December 2026. Migrate to the Customer API (CAPI) before then.

### Migration summary
The v1 surface is completely covered by CAPI. The frictions are: two GET → POST verb changes, a flipped default on autoAnswer, the loss of Basic Auth, and the lack of a single "current user identity" endpoint.

Mapping (v1 → CAPI):
- GET /extensions/  →  GET /v1/extensions/users
    Lists users only — PBX resources (queues, IVRs, faxes, …) live under /v1/extensions/pbx.
- GET /extensions/{ext}  →  GET /v1/extensions/users/{user}  or  GET /v1/extensions/pbx/{extension}
    Split by resource type. Use users/{user} for a person, pbx/{extension} for a queue / IVR / shared-voicemail.
- GET /extensions/me  →  (no direct equivalent)
    CAPI exposes per-user actions under /v1/extensions/users/me/… but no single object that names your own extension. See gap #1 below.
- GET /calls  →  GET /v1/extensions/users/me/calls/history
    fromDate / toDate behave the same; new optional callType filter. withRecordings is gone — call /v1/extensions/users/me/calls/recordings separately if needed.
- GET /dial/{number}?autoanswer=…  →  POST /v1/extensions/users/me/dial  body { phoneNumber, autoAnswer }
    Verb change: GET → POST. Number moves URL → body. autoAnswer default flipped — see gap #3.
- GET /sms/{number}?message=…  →  POST /v1/extensions/users/me/sms  body { phoneNumber, message }
    Verb change: GET → POST. Both fields move URL → body.
- POST /hangup  →  POST /v1/extensions/users/me/hangup
    Same verb, deeper path. No body, no params.
- GET /recordings/{recordingId}  →  GET /v1/extensions/users/calls/recordings/{recording}
    Same shape, deeper path. Still returns the audio bytestream.

## Best practices
Source: https://developer.telavox.com/best-practices

Guidance for building integrations that stay fast, predictable, and friendly to the platform. None of this is enforced as a hard limit today — but following it keeps your integration out of the way of throttling and other defensive measures.

### Authentication
- Send your token as Authorization: Bearer <jwt>. The portal's "Test Request" feature auto-prefixes Bearer if you paste a raw JWT; your own clients should always include the prefix.
- Keep tokens out of source control, logs, and URLs. Treat them like passwords — store them in a secret manager or environment variables, never in commit history.
- Rotate tokens periodically and any time you suspect leakage. Build the rotation path into your integration before you need it; tokens that "never expire" tend to become tokens nobody knows how to replace.

### Traffic shape
- Keep concurrency modest. A handful of in-flight requests is plenty for most integrations; large bursts cause queueing on our side and timeouts on yours.
- Prefer endpoints that return a collection over fan-out calls. If an endpoint accepts a list of IDs, use it instead of looping one-by-one.
- Walk paginated endpoints to completion sequentially. Don't request many pages in parallel — order matters for cursors, and parallel paging multiplies load without buying you much speed.
- Poll only as often as you actually use the data. Most state in Telavox does not change second-to-second; polling at one-minute or longer intervals is almost always fine, and gentler intervals (5–15 minutes) are better for background sync.
- Cache responses on your side where it's safe to. Honour any Cache-Control or ETag headers we send; refetching unchanged data is the easiest waste to eliminate.

### Retries and errors
Today most error responses collapse to 400 (your request is wrong — do not retry) or 500 (something failed on our side — retry with backoff). More granular codes are rolling out, so build your client to dispatch on the status code rather than parsing error bodies, and the guidance below will continue to apply as the surface area expands.
- Retry 5xx responses with exponential backoff (e.g. 1s, 2s, 4s, 8s) and jitter — a small random offset on each attempt — capped at a reasonable number of attempts (3–5). Jitter matters because it prevents clustered clients from all retrying in lockstep. Surface the failure once retries are exhausted rather than looping indefinitely.
- Do not retry 4xx responses. They mean your request itself is wrong — retrying with the same payload will keep failing and just add noise.
- When 429 Too Many Requests starts appearing (not common today, but coming as we roll out per-endpoint rate limits), retry with the same exponential-backoff-with-jitter strategy as 5xx. If the response carries a Retry-After header, use it as a minimum wait — keep growing your backoff from there if subsequent attempts also fail.
- Be careful retrying writes (POST/PUT/DELETE). If a request times out, the server may still have applied the change; retry only when you can detect or tolerate the duplicate.

### Schema and versioning
- Ignore fields you don't use. Treat new fields in responses as additive — adding a field is not a breaking change, and your client should not crash on unknown keys.
- Pin to a specific API version in your client (the version selector on each reference page tells you what's current). Plan a migration window when a version is announced for deprecation rather than waiting until sunset.
- Keep an eye on the Announcements page. Releases, breaking changes, and deprecations are published there with explicit dates — that's the canonical source for what's changing.

### Identify yourself
- Set a descriptive User-Agent on every request, including a contact URL or email, e.g. "AcmeCRM/2.3 (+https://acme.example/contact)" or "AcmeCRM/2.3 (ops@acme.example)". This is how we route operational issues back to the right people.
- If we can reach you, we will email you before throttling or blocking — almost always with a fix proposal, not an ultimatum. If we cannot reach you (no contact in User-Agent, contact endpoint dead, nobody answering) and your integration is causing problems, we will block first and ask later. Keep the contact alive; treat it as part of the integration.

### A note on enforcement
We do not publish specific rate-limit thresholds — limits vary by endpoint and are subject to change. We reserve the right to throttle or block integrations that place undue strain on the platform, but the purpose of this page is to make that outcome unnecessary.

All integrations must include a descriptive User-Agent header on every request. Use a value that clearly identifies your application and, where applicable, your organization — for example, AcmeCRM/2.3 (ops@acme.example). Generic or missing User-Agent strings may be treated as unidentified traffic and throttled or blocked accordingly.

If you are unsure whether your integration is within reasonable bounds, reach out before you ship. We would rather help you get it right early than have to intervene later.

## Announcements
Source (human-rendered, with filter chips): https://developer.telavox.com/announcements

### 2026-05-18 — Legacy v1 API will be removed on 31 December 2026 [v1] (deprecation)
The legacy v1 API is deprecated and will be sunset on 31 December 2026. Plan your migration to the Customer API (CAPI) before then; the full v1 reference remains available at /v1/reference during the migration window.