docs: custom reporting tags the Voice API - #421
Merged
Conversation
Tagging a Voice session is confirmed working in production, but the docs still said custom tag data was supported for text translation only. - Rework the how-to guide: generalize the framing away from "translate requests" and add a section on tagging a Voice session, including that the header can only ride the session request (the WebSocket carries no headers), so a tag covers a whole session and cannot be changed mid-session or applied per utterance. - Add speech_to_text_minutes and speech_to_speech_minutes to CustomTagBreakdown, the analytics response examples, and the endpoint reference table, and note that voice minutes are not part of total_characters. - Document X-DeepL-Reporting-Tag in the spec as a reusable components.parameters entry, referenced from POST /v2/translate and POST /v3/voice/realtime. The header was previously absent from the spec entirely, including for text translation. - Add an August 18 release note and bump info.version to 3.13.0. openapi.json is left untouched; CI regenerates it from the YAML.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
seekuehe
approved these changes
Aug 18, 2026
- Add the missing sample response to the Voice curl example, since CLAUDE.md requires request and response together and the translate section directly above it already shows one. - Replace an em-dash (banned) and drop "utterances", which appears nowhere else in the docs, in favour of "audio chunks" as used throughout the Voice pages. - Restore "only" in both scope warnings. Dropping it made the constraint read weaker than it is. - Fix the total_characters description, in the reference table and in the spec, which still claimed all services while voice minutes now sit in the same breakdown and are excluded from that total. - Note that the minute fields return fractional values. - Lead the release note with what a custom tag is, per the changelog convention, so the entry stands alone. - Trim the CustomReportingTag description down to purpose plus a link to the guide, in line with sibling parameters. - Say "text translation" throughout rather than alternating with "translate", and cross-link the tag from the voice session flow and from the guide's own Limitations list.
Verified against production: a tagged session streamed 8800 ms, dropped the WebSocket without ending the stream, reconnected via GET /v3/voice/realtime with only the token (no tag header), then streamed 8754 ms more. All 17553 ms landed under the original tag across four usage rows, with no untagged rows for the account. This was the gap flagged in review. Reconnection is a normal flow and the reconnect request cannot carry a tag, so silence here left developers unable to tell whether reconnected audio kept its attribution.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Tagging a Voice session is confirmed working in production, but the docs still said custom tag data was supported for text translation only.
openapi.json is left untouched; CI regenerates it from the YAML.