# Welcome to Teleman AI Documentation

Complete guide to building and managing automated voice calling campaigns with AI-powered message generation, real-time analytics, and professional softphone integration.

15 Documentation Guides
35K+ Words Written
10,000+ Lines of Documentation
100% Production Ready

## Quick Access

Jump to the section you need

🚀

### Installation Guide

Complete setup instructions for all environments with system requirements and configuration steps.

⚡

### Quick Start

20-minute tutorial to get your first campaign running and making calls.

📢

### Campaign Management

Create and manage automated calling campaigns with TTS, audio files, and DTMF support.

📞

### Softphone

Make calls directly from your browser with full call controls and recording capabilities.

💰

### Credits & Pricing

Understand the credit system, pricing rules, and how to manage your account balance.

🔌

### CRM Integrations

Connect your CRM and marketing tools with real-time webhooks for seamless data sync.

⏰

### Cron Jobs Setup

Configure scheduled tasks for automated campaign processing and system maintenance.

## Platform Features

Everything you need for professional voice campaigns

#### 🎤 Text-to-Speech

Multiple voice options in various languages with natural-sounding AI voices.

#### 🔊 Audio Files

Upload pre-recorded messages in MP3 or WAV format for professional campaigns.

#### 📊 Real-time Analytics

Track campaign performance with detailed metrics and call analytics.

#### 🎯 DTMF Support

Interactive voice response with keypad input for customer interactions.

#### 🤖 AMD Detection

Answering machine detection to optimize campaign effectiveness.

#### 📝 Call Recording

Record and playback calls for quality assurance and compliance.

#### 👥 Contact Management

Organize contacts with lists, tags, and custom variables.

#### 🔒 Role-Based Access

Admin, Customer, and Agent roles with granular permissions.

#### 💳 Stripe Integration

Secure payment processing for credit top-ups with PCI DSS compliance.

## Installation Guide

Complete setup instructions for Teleman AI

Before You Begin

Make sure you have all system requirements ready: PHP 8.2+, MySQL 8.0+, Node.js 18+, and Composer installed.

### System Requirements

Component | Minimum | Recommended
--- | --- | ---
PHP | 8.2.0 | 8.3+
MySQL | 8.0 | 8.0+
Node.js | 18.x | 20.x LTS
RAM | 2 GB | 4 GB+
Storage | 5 GB | 10 GB+

### Installation Steps

#### Clone the Repository

bash

    git clone https://github.com/TheCodeStudioxyz/teleman-new-vue.git
    cd teleman-new-vue

#### Install Dependencies

bash

    composer install
    npm install

#### Configure Environment

bash

    cp .env.example .env
    php artisan key:generate

Edit `.env` file with your database credentials and app configuration.

#### Run Migrations & Seed

bash

    php artisan migrate:fresh --seed

#### Build Frontend Assets

bash

    npm run build

#### Start the Application

bash

    php artisan serve

Visit `http://localhost:8000` in your browser.

Installation Complete!

Your Teleman AI instance is now running. Default admin credentials are `admin@example.com` / `password`

## Quick Start Guide

Get your first campaign running in 20 minutes

Follow this tutorial to create and launch your first calling campaign...

Complete documentation for Quick Start available in the markdown files. This HTML version provides the essential overview.

## CRM Integrations

Connect your CRM and marketing automation tools with real-time webhooks

Teleman AI integrates seamlessly with your existing CRM, marketing automation platforms, and custom systems through powerful webhook-based integrations. Automatically sync call data, leads, contacts, and campaign events in real-time.

### What are CRM Integrations?

CRM Integrations allow you to push data from Teleman AI to external systems automatically. When specific events occur (like a call completion, a hot lead detected, or a contact update), Teleman sends an HTTP webhook to your configured endpoint with the relevant data.

Production Ready

Built with reliability in mind: automatic retries, delivery logs, webhook testing, and multiple authentication methods.

### Supported Events

Choose which events trigger webhooks to your system:

📞

#### Call Completed

Triggered when a call ends. Includes full call data with transcript, duration, sentiment score, and AI-detected intent.

🔥

#### Lead Qualified

Triggered when AI detects a hot lead based on sentiment analysis and conversation quality (high score/positive sentiment).

👤

#### Contact Added

Triggered when a new contact is created manually or imported. Perfect for syncing your contact database.

✏️

#### Contact Updated

Triggered when contact information is modified. Keep your CRM data synchronized in real-time.

🚀

#### Campaign Started

Triggered when a campaign is launched. Track campaign lifecycle and send notifications.

🔢

#### DTMF Response

Triggered when a contact presses a phone key during a call. Capture survey responses and menu selections.

### Authentication Methods

Secure your webhooks with multiple authentication options:

#### 🔓 None (Testing Only)

No authentication required. Use only for development and testing. Not recommended for production.

#### 🎟️ Bearer Token

Standard OAuth 2.0 bearer token authentication. Most CRMs and APIs use this method. Token is sent in the `Authorization: Bearer {token}` header.

#### 🔑 API Key

Custom header-based authentication. Specify your own header name (e.g., `X-API-Key`) and secret value. Flexible for custom integrations.

#### 🔐 HMAC Signature

Maximum security using cryptographic signatures. Teleman signs each request with your secret key using SHA-256. Your endpoint verifies the signature to ensure authenticity.

### Getting Started

Quick Setup

Navigate to Integrations → CRM Integrations in the sidebar to create your first integration.

#### Step 1: Create Integration

1. Go to CRM Integrations page
2. Click "Add Integration" button
3. Enter a descriptive name (e.g., "Salesforce Production")
4. Provide your webhook endpoint URL
5. Select which events should trigger webhooks
6. Choose authentication method and configure credentials
7. Enable the integration

#### Step 2: Test Your Integration

Before going live, test your webhook endpoint:

1. Click the "Test" button on your integration card
2. Teleman sends a sample webhook to your endpoint
3. Check the response status and verify your endpoint received the data
4. Review the Webhook Logs to see delivery details

#### Step 3: Monitor Delivery

View all webhook deliveries in real-time:

- Click "View Logs" on any integration
- See timestamps, status codes, and response data
- Green badges indicate successful deliveries (2xx status)
- Red badges show failures with error details
- Click "Retry" to resend failed webhooks

### Webhook Payload Example

Example payload for a `call_completed` event:

POST /your-webhook-endpoint

    {
      "event": "call_completed",
      "data": {
        "call_id": 1234,
        "contact_id": 5678,
        "campaign_id": 91,
        "phone_number": "+1234567890",
        "duration": 45,
        "status": "completed",
        "transcript": "Hello, this is John...",
        "sentiment": "positive",
        "sentiment_score": 0.85,
        "ai_detected_intent": "interested",
        "created_at": "2025-12-22T10:30:00Z"
      },
      "timestamp": "2025-12-22T10:30:15Z",
      "integration_id": 42
    }

Payloads vary by event type. Each event includes relevant data fields and metadata.

### Best Practices

#### ✅ Respond Quickly

Return a 2xx status code within 5 seconds. Process heavy tasks asynchronously in a background queue.

#### 🔄 Handle Retries

Make your endpoint idempotent. Teleman retries failed webhooks up to 3 times with exponential backoff.

#### 🔐 Verify Signatures

Always verify HMAC signatures in production. Reject requests with invalid signatures to prevent spoofing.

#### 📝 Log Everything

Log incoming webhooks on your side. This helps debug issues and provides an audit trail.

#### 🧪 Test Regularly

Use the built-in test feature regularly to ensure your integration remains functional after changes.

#### 📊 Monitor Logs

Check webhook logs periodically for failures. High failure rates may indicate endpoint issues.

### Troubleshooting

#### Webhook not arriving?

- Check if the integration is enabled (Active status)
- Verify the event is selected in your integration settings
- Ensure your endpoint URL is correct and accessible
- Check webhook logs for delivery attempts and errors

#### Getting 4xx errors?

- 400 Bad Request: Your endpoint rejected the payload format
- 401 Unauthorized: Authentication credentials are incorrect
- 404 Not Found: Endpoint URL is incorrect or route doesn't exist
- 429 Too Many Requests: Your endpoint is rate-limiting Teleman

#### Getting 5xx errors?

- 500 Internal Server Error: Your endpoint code has a bug
- 502 Bad Gateway: Reverse proxy or load balancer issue
- 503 Service Unavailable: Your endpoint is down or overloaded
- 504 Gateway Timeout: Your endpoint took too long to respond (>30s)

Retry Behavior

Failed webhooks are retried 3 times with delays: 1 minute, 5 minutes, then 15 minutes. After 3 failures, the webhook is marked as permanently failed and requires manual retry.

### Advanced Features

#### Custom Headers

Add custom HTTP headers to your webhook requests (useful for API keys, routing info, etc.):

    X-Tenant-ID: abc123
    X-Environment: production
    X-Source: teleman-ai

#### Event Filtering

Create multiple integrations for different event types. For example:

- CRM Integration: Only `lead_qualified` and `contact_added`
- Analytics Integration: Only `call_completed` events
- Notification Service: Only `campaign_started` events

#### Manual Retry

Failed webhooks can be manually retried from the Webhook Logs page. This is useful when:

- Your endpoint was temporarily down
- You fixed a bug in your webhook handler
- Authentication credentials were incorrect

### Related Documentation

For detailed API documentation, code examples, and advanced configuration, see:

- `docs/CRM_INTEGRATION_README.md` - Complete feature overview
- `docs/CRM_INTEGRATION_QUICKSTART.md` - Step-by-step setup guide
- `docs/CRM_INTEGRATION_TESTING.md` - Testing and quality assurance
- `docs/CRM_INTEGRATION_COMPLETE.md` - Technical implementation details