Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

The Talkover API uses Bearer token authentication with environment tokens. All API requests must include a valid environment token in the Authorization header.

​
Overview

Authentication is handled through Environment Tokens that you can generate in your Talkover dashboard. These tokens provide secure access to your account’s resources and are used to authenticate all API requests.

​
Getting Your Environment Token

​
Step 1: Access Your Dashboard

  1. Log in to your Talkover account at app.talkover.ai
  2. Navigate to Account in the left sidebar
  3. Click on “Environments”

​
Step 2: Find Your Token

Your environment tokens will be displayed in the Environments section. Each environment has its own token that starts with talq_ followed by a long string of characters.
Environment tokens are sensitive credentials. Keep them secure and never share them publicly or commit them to version control.

​
Using Your Environment Token

​
Authorization Header

Include your environment token in the Authorization header of all API requests: 
Authorization: Bearer talq_your_environment_token_here

​
Example Request

curl -H "Authorization: Bearer talq_your_environment_token_here" \
  https://app.talkover.ai/api/v1/health

​
Security Best Practices

​
1. Keep Tokens Secure

  • Never expose tokens in client-side code or public repositories
  • Use environment variables to store tokens securely
  • Rotate tokens regularly for enhanced security
  • Monitor token usage for suspicious activity

​
2. Token Management

  • Use different tokens for different environments (development, staging, production)
  • Limit token permissions to only what’s necessary
  • Revoke compromised tokens immediately
  • Use token expiration when available

​
3. Request Security

  • Always use HTTPS for API requests
  • Validate responses to ensure they come from Talkover
  • Handle errors gracefully without exposing sensitive information
  • Log requests securely without including tokens

​
Environment Variables

Store your environment token securely using environment variables:

​
Bash/Shell

export TALKOVER_TOKEN="talq_your_environment_token_here"

​
JavaScript/Node.js

const token = process.env.TALKOVER_TOKEN;

​
Python

import os
token = os.environ.get('TALKOVER_TOKEN')

​
PHP

$token = getenv('TALKOVER_TOKEN');

​
Code Examples

​
cURL

curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer $TALKOVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890"
  }'

​
JavaScript

const response = await fetch('https://app.talkover.ai/api/v1/agents/agent_123456/call', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TALKOVER_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+1234567890'
  })
});

​
Python

import requests
import os

headers = {
    'Authorization': f'Bearer {os.environ.get("TALKOVER_TOKEN")}',
    'Content-Type': 'application/json'
}

data = {
    'to': '+1234567890'
}

response = requests.post(
    'https://app.talkover.ai/api/v1/agents/agent_123456/call',
    headers=headers,
    json=data
)

​
PHP

$token = getenv('TALKOVER_TOKEN');
$headers = [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
];

$data = [
    'to' => '+1234567890'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.talkover.ai/api/v1/agents/agent_123456/call');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

​
Error Responses

​
Invalid Token

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing authentication token",
  "status_code": 401
}

​
Expired Token

{
  "error": "TOKEN_EXPIRED",
  "message": "Authentication token has expired",
  "status_code": 401
}

​
Missing Token

{
  "error": "MISSING_TOKEN",
  "message": "Authorization header is required",
  "status_code": 401
}

​
Token Scopes and Permissions

Environment tokens have access to:
  • Voice Agents - Create, read, update, and delete voice agents
  • Calls - Initiate and manage calls
  • Campaigns - Create and manage call campaigns
  • Call History - Access call logs and analytics
  • Account Settings - Read account information
Environment tokens have full access to your account. Use them responsibly and never share them with unauthorized parties.

​
Troubleshooting

​
Common Issues

  1. “Invalid token” error
    • Verify the token is correct and complete
    • Check that the token starts with talq_
    • Ensure no extra spaces or characters
  2. “Token expired” error
    • Generate a new environment token
    • Update your application with the new token
    • Check token expiration settings
  3. “Missing token” error
    • Ensure the Authorization header is included
    • Verify the header format: Bearer <token>
    • Check that the token is not empty

​
Getting Help

If you’re experiencing authentication issues:
  1. Check your token in the dashboard
  2. Verify the request format matches the examples
  3. Test with a simple request like the health endpoint
  4. Contact support if the issue persists

​
Next Steps