Developers Overview

Build custom integrations, automate workflows, and extend LiveTok with our comprehensive API and developer tools.

Overview

LiveTok provides two primary methods for integrating with your systems: Webhooks and APIs. Understanding the difference between these approaches helps you choose the right tool for your integration needs.

Webhooks vs APIs

Webhooks are event-driven notifications that LiveTok sends to your server when something happens (like a conversation starting or ending). Think of webhooks as LiveTok calling you to inform you about events in real-time. Your server receives these notifications and can respond with custom logic or data.

When to use Webhooks:

Track when conversations start and end for analytics or billing
Add custom context to conversations based on your business logic (e.g., customer tier, account status)
Integrate with your CRM or support systems to log customer interactions
Set per-session limits or access control based on your business rules
Trigger workflows in your system based on conversation events

Example use cases:

When a VIP customer starts a conversation, automatically notify your sales team
After a conversation ends, create a ticket in your support system
Add customer purchase history as context when they contact support
Apply different rate limits based on customer subscription level

APIs are request-response interfaces where you call LiveTok to retrieve data or perform actions. Think of APIs as you calling LiveTok to ask for information or trigger an action. You make a request when you need something, and LiveTok responds with the result.

When to use APIs:

Retrieve conversation transcripts and analytics data
Manage your knowledge base content programmatically
Create or modify agent configurations
Bulk import or export data
Build custom dashboards or reports

Example use cases:

Pull conversation analytics into your business intelligence tools
Automatically sync product catalog updates to your agent’s knowledge base
Export all conversation transcripts for compliance or training purposes
Programmatically create agents for different departments or regions

Core Features

Webhooks

Session begin notifications
Session end notifications
Real-time event handling
Custom business logic integration
Bidirectional communication

Quick Start

Set Up Webhooks

Configure webhooks in your agent settings:

Go to Dashboard > Agents
Select your agent
Scroll to Webhooks section
Configure:
- Begin Session URL
- End Session URL
- Optional headers for authentication

Set Up Webhooks →

Webhook Events

Session Begin

Triggered when a new conversation session starts (call or messaging).

Event Payload:

{
  "event": "session_begin",
  "sessionId": "123",
  "kind": "whatsapp",
  "agentId": 1,
  "agentName": "My Agent",
  "phoneNumber": "+1234567890",
  "timestamp": "2024-03-15T10:30:00Z"
}
```text
 
**Response (Optional):**
```json
{
  "allowed": true,
  "context": {
    "customer_tier": "premium",
    "custom_field": "value"
  },
  "limits": {
    "dailyMessageLimit": 100,
    "dailyCallMinutes": 60
  }
}
```text
 
**Use Cases:**
- Access control (allow/deny sessions)
- Add custom context for AI Agent
- Set per-session limits
- Track session analytics
- Integrate with CRM
 
### Session End
 
Triggered when a conversation session ends.
 
**Event Payload:**
```json
{
  "event": "session_end",
  "sessionId": "123",
  "kind": "whatsapp",
  "agentId": 1,
  "agentName": "My Agent",
  "phoneNumber": "+1234567890",
  "duration": 300,
  "timestamp": "2024-03-15T10:35:00Z"
}
```text
 
**Use Cases:**
- Log session duration
- Update CRM records
- Trigger follow-up actions
- Analytics and reporting
- Billing/usage tracking
 
[Full Webhook Documentation →](/developers/notifications)
 
---
 
## Development Environment
 
### Testing Webhooks
 
**Local Testing:**
 
Use ngrok to expose your local server:
 
```bash
# Start your local server
node server.js
 
# Expose via ngrok
ngrok http 3000
 
# Use ngrok URL in agent webhook settings
https://abc123.ngrok.io/webhooks/livetok
```text
 
---
 
## Best Practices
 
### Webhook Security
 
**Verify Webhook Source:**
 
Add authentication headers when configuring webhooks:
 
```javascript
// In agent settings, add headers:
headers: {
  "X-API-Key": "your-secret-key"
}
 
// In your webhook handler:
app.post('/webhooks/livetok', (req, res) => {
  const apiKey = req.headers['x-api-key'];
 
  if (apiKey !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }
 
  // Process webhook...
});
```text
 
**Use HTTPS:**
- Always use HTTPS endpoints
- Never use HTTP for webhooks
- Validate SSL certificates
 
### Error Handling
 
**Retry Logic:**
 
LiveTok automatically retries failed webhooks:
- Retries up to 3 times
- Exponential backoff between retries
- Returns 200 OK to acknowledge receipt
 
```javascript
app.post('/webhooks/livetok', async (req, res) => {
  try {
    // Acknowledge immediately
    res.status(200).send('OK');
 
    // Process asynchronously
    await processWebhook(req.body);
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Webhook already acknowledged, handle error appropriately
  }
});
```text
 
### Logging
 
**Track Webhook Activity:**
 
```javascript
app.post('/webhooks/livetok', (req, res) => {
  const event = req.body;
 
  console.log('Webhook received:', {
    event: event.event,
    sessionId: event.sessionId,
    timestamp: new Date().toISOString()
  });
 
  // Process and respond...
});
```text
 
---
 
## Resources
 
### Documentation
 
- [Webhook Details →](/developers/notifications)
- [Integration Examples →](/integrations)
 
### Support
 
- **Chat** - Talk to our AI Agent in the dashboard
- **Email** - hello@livetok.ai
- **Status** - status.livetok.ai
 
---
 
## Next Steps
 
- [Set Up Webhooks →](/developers/notifications)
- [Browse Integrations →](/integrations)
- [View Support Options](/support)
 
---
 
## Need Help?
 
- Chat with our AI Agent in the dashboard
- Email developers@livetok.ai
- Check our [Support page](/support)

Reporting Webhooks