Welcome to Teleman AI Documentation

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.

Supported Events

Choose which events trigger webhooks to your system:

Authentication Methods

Secure your webhooks with multiple authentication options:

Getting Started

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:

{
  "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
}

Best Practices

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)

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

Feature Overview

Click-to-Call

Call contacts directly from anywhere in the application. The softphone widget handles the call while the contact record is automatically linked.

From Contacts List

1. Navigate to Contacts from the sidebar
2. Find the contact you want to call
3. Click the phone icon button in the contact's row
4. The softphone widget expands with the number pre-filled
5. Click "Call" in the softphone widget to initiate the call

From Contact Detail Page

1. Open any contact's detail page
2. Click the "Call This Contact" button in the header
3. The softphone widget opens with the number ready
4. Click "Call" to start the call

Post-Call Disposition

When a contact-linked call ends, a disposition modal automatically appears after a brief delay, prompting the agent to log the call outcome.

Disposition Codes

Disposition Modal Fields

• Disposition Code (required) - Select one of the 7 disposition codes above
• Call Notes (optional) - Free-text notes about the conversation
• Callback Date/Time (conditional) - Appears only when "Callback" disposition is selected

Sequential Calling Session

The calling session provides a dedicated interface for working through a contact list sequentially, maximizing agent productivity.

Starting a Calling Session

1. Navigate to Contacts
2. Optionally select a contact list from the filter dropdown
3. Click the "Start Calling" button
4. You'll be taken to the dedicated calling session page

Calling Session Interface

• Progress Bar - Visual indicator showing how far through the list you are
• Current Contact Card - Shows the contact's name, phone number, email, company, total calls, last contacted date, and notes
• Last Call Result - Displays the previous disposition for the current contact (if any)
• Call Now Button - Green button to initiate the call via the softphone
• Skip Contact - Move to the next contact without calling
• Previous / Next - Navigate manually through the list
• Contact Queue - Scrollable sidebar showing all contacts with their disposition badges
• List Switcher - Dropdown to switch between contact lists without leaving the session

Auto-Advance Behavior

After saving a disposition in the post-call modal, the calling session automatically advances to the next contact in the list. This creates a seamless workflow:

1. Click "Call Now" to call the current contact
2. Have your conversation
3. Call ends - disposition modal appears
4. Select disposition, add notes, save
5. Session auto-advances to the next contact
6. Repeat from step 1

Contact-Level Call Tracking

All manual calls made through click-to-call are tracked at the contact level, providing a complete call history.

Contact Detail Page - Call History

The contact detail page (Contacts > View Contact) shows:

• Total Calls - Cumulative count of all calls made to the contact
• Last Contacted - Timestamp of the most recent call
• Recent Calls Table - List of recent calls with:
  • Date and time
  • Disposition badge (color-coded)
  • Call notes
  • Duration

Contacts List View

The contacts index page shows quick indicators:

• Phone icon button - Quick click-to-call action on each row
• Total calls count visible in the table
• Last contacted date for at-a-glance status

Authorization & Roles

Manual calling features respect the existing role-based access control system:

Database Schema

Manual calling adds the following fields to the calls table:

php artisan migrate
# Runs: 2026_03_16_100000_add_disposition_and_contact_to_calls_table

API Reference

Save Disposition

{
  "disposition": "interested",   // required: one of 7 codes
  "call_notes": "Very interested in premium plan",  // optional
  "callback_at": "2026-03-20T14:00:00"  // optional, for callbacks
}

Initiate Call (with contact linking)

{
  "to_number": "+1234567890",
  "from_number": "+0987654321",
  "contact_id": 42,              // optional: links call to contact
  "enable_recording": true
}

Related Documentation