API Reference - Voice Tracking

Prerequisite

If you haven't set up a voice agent in the Paygent dashboard yet, please follow our setup guide first. You'll need an Agent ID to start tracking.

Track voice agent usage directly via our REST API. This is ideal for custom integrations where you prefer not to use our SDKs. Follow the session lifecycle below to ensure accurate tracking and billing.

Integration Steps

Follow this 6-step sequence to implement a robust voice tracking pipeline.

1. Create or Get Customer

Before starting a session, ensure your customer exists in Paygent. This endpoint retrieves an existing customer by externalId or creates a new one if not found.

cURL

1curl --location 'https://cp-api.withpaygent.com/api/v1/customers/create-or-get' \
2--header 'paygent-api-key: YOUR_API_KEY' \
3--header 'Content-Type: application/json' \
4--data '{
5    "name": "Customer Name",
6    "externalId": "customer-123"
7}'

2. Initialize Voice Session

Initialize a unique session for each voice call. Use your own unique sessionId (e.g., Call SID or UUID) to link all subsequent tracking events.

cURL

1curl --location 'https://cp-api.withpaygent.com/api/v1/voice/session' \
2--header 'paygent-api-key: YOUR_API_KEY' \
3--header 'Content-Type: application/json' \
4--data '{
5    "sessionId": "voice_call_unique_uuid", # use the same sessionId throughout the session
6    "agentId": "your-voice-agent-id",
7    "customerId": "customer-123"
8}'

3. Track STT

Track Speech-to-Text usage by providing the audio duration in minutes.

cURL

1curl --location 'https://cp-api.withpaygent.com/api/v1/voice/stt' \
2--header 'paygent-api-key: YOUR_API_KEY' \
3--header 'Content-Type: application/json' \
4--data '{
5    "sessionId": "voice_call_unique_uuid", # use the same sessionId throughout the session
6    "audioMinutes": 0.5,
7    "provider": "deepgram",
8    "model": "nova-2",
9    "plan": "default"
10}'

4. Track LLM

Track Large Language Model usage by providing prompt and completion token counts.

cURL

1curl --location 'https://cp-api.withpaygent.com/api/v1/voice/llm' \
2--header 'paygent-api-key: YOUR_API_KEY' \
3--header 'Content-Type: application/json' \
4--data '{
5    "sessionId": "voice_call_unique_uuid", # use the same sessionId throughout the session
6    "provider": "openai",
7    "model": "gpt-4o",
8    "plan": "default",
9    "promptTokens": 1000,
10    "completionTokens": 500,
11    "cachedTokens": 200
12}'

5. Track TTS

Track Text-to-Speech usage by providing the total character count processed.

cURL

1curl --location 'https://cp-api.withpaygent.com/api/v1/voice/tts' \
2--header 'paygent-api-key: YOUR_API_KEY' \
3--header 'Content-Type: application/json' \
4--data '{
5    "sessionId": "voice_call_unique_uuid", # use the same sessionId throughout the session
6    "provider": "amazon-polly",
7    "model": "neural",
8    "plan": "default",
9    "characters": 28000
10}'

6. Set Indicator

Finally, set a voice indicator (e.g., call completion) with the total call duration in minutes.

cURL

1curl --location 'https://cp-api.withpaygent.com/api/v1/voice/indicator' \
2--header 'paygent-api-key: YOUR_API_KEY' \
3--header 'Content-Type: application/json' \
4--data '{
5    "sessionId": "voice_call_unique_uuid", # use the same sessionId throughout the session
6    "indicator": "per-minute-call",
7    "totalDuration": 0.5
8}'

Need help? Contact us at support@withpaygent.com