---
title: "Create a Tally voice session"
method: POST
path: "/tally/voice/sessions"
tags: ["Tally Voice"]
---

# Create a Tally voice session

`POST /tally/voice/sessions`

## Request

- Base URL: `https://ledgerhq.pro/api/v1`
- URL: `https://ledgerhq.pro/api/v1/tally/voice/sessions`
- Auth: one of:
  - HTTP bearer and API key in header `x-organization-id`
  - HTTP bearer and API key in header `x-organization-id`

Creates a short-lived gateway ticket for push-to-talk transcription (`mode=transcription`) or hands-free conversation (`mode=conversation`). Usage is metered for cost monitoring only and never blocks session creation. Media connects through the LedgerHQ voice gateway, not a public OpenAI endpoint.

## Request body

- object
  - `mode` 'transcription' | 'conversation'
  - `conversationId` string, uuid, nullable

## Response `201`

Voice session reserved

- object
  - `sessionId` string, uuid, required
  - `voiceSessionId` string, uuid
  - `mode` 'transcription' | 'conversation'
  - `conversationId` string, uuid, nullable
  - `ticket` string, required: Short-lived, one-time gateway credential.
  - `ticketExpiresAt` string, date-time, required
  - `gatewayUrl` string, uri, required
  - `connection` object
    - `transport` 'gateway_ws' | 'webrtc'
    - `path` string
    - `gatewayUrl` string, uri
    - `webrtcPath` string, nullable: App-relative SDP exchange path for conversation WebRTC. OpenAI credentials stay server-side.
  - `reservedSeconds` integer, required
  - `usage` TallyVoiceUsage, required
    - `enabled` boolean, required
    - `unlimited` boolean: When true, remainingSeconds is null and caps are not enforced.
    - `periodKey` string, required: Eastern Time calendar month.
    - `includedSeconds` integer, required
    - `purchasedSeconds` integer, required
    - `allowanceSeconds` integer, required
    - `usedMilliseconds` integer, required
    - `reservedMilliseconds` integer, required
    - `remainingSeconds` integer, nullable
    - `percentUsed` number, required
    - `warningLevel` 'none' | 'warning' | 'near_cap' | 'capped', required
    - `maxSessionSeconds` integer, required

## Other responses

- `409`: Error response
- `503`: Error response
- `default`: Error response

---

[API](https://skmtc.dev/ledgerhq-pro/apis/ledgerhq-bookkeeping-api.md) · [All operations](https://skmtc.dev/ledgerhq-pro/apis/ledgerhq-bookkeeping-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ledgerhq-pro/apis/ledgerhq-bookkeeping-api/revisions/9a8269f0a586?raw)