Lerty API - Quick Start Guide

Welcome to the Lerty API! This page provides a quick introduction to integrating with Lerty.

📚 Full API Reference (Swagger UI) 📥 Download Integration Guide

Getting Started

1. Get Your API Key

  1. Log in to your Lerty dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New API Key
  4. Copy and securely store your API key
⚠️ Security Note: Never expose your API key in client-side code. Store it securely in environment variables or server configuration.

2. Send Your First Message

Send a message to an agent:

curl -X POST "https://lerty.ai/api/agents/YOUR_AGENT_ID/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, I need help!",
    "metadata": {
      "source": "api_test",
      "user_email": "test@example.com"
    }
  }'
✅ Success! If you receive a JSON response with "success": true, you're all set!

Common Use Cases

WordPress Integration (WSForm, FlowMattic)

Integrate Lerty with WordPress form submissions:

// In your WordPress functions.php or plugin
add_action('wsf_submit_post_complete', function($submit) {
    $api_key = 'YOUR_API_KEY';
    $agent_id = 'YOUR_AGENT_ID';

    wp_remote_post("https://lerty.ai/api/agents/{$agent_id}/send", [
        'headers' => [
            'Authorization' => "Bearer {$api_key}",
            'Content-Type' => 'application/json',
        ],
        'body' => json_encode([
            'content' => $submit->meta['field_message'],
            'metadata' => [
                'source' => 'wsform',
                'user_email' => $submit->meta['field_email'],
            ]
        ])
    ]);
});

Sending Typing Indicators

Show users your agent is thinking:

// Start typing
curl -X POST "https://lerty.ai/api/agents/YOUR_AGENT_ID/callback" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_type": "typing",
    "conversation_id": "CONVERSATION_ID",
    "data": {"typing": true}
  }'

// Process your response...

// Stop typing
curl -X POST "https://lerty.ai/api/agents/YOUR_AGENT_ID/callback" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_type": "typing",
    "conversation_id": "CONVERSATION_ID",
    "data": {"typing": false}
  }'

Push Notifications

Send push notifications to user devices:

curl -X POST "https://lerty.ai/api/push/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "title": "New Message",
    "body": "You have a new message from support",
    "priority": "high"
  }'

Live Activities

Live Activities display real-time progress on the user's lock screen. Start them with a push notification containing workflow_state data.

Starting a Live Activity

Send a push notification with workflow_state to start a Live Activity with sound:

curl -X POST "https://lerty.ai/api/push/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "title": "Order Placed",
    "body": "Your order #7890 has been placed",
    "badge": 1,
    "sound": "cashregister.caf",
    "priority": "high",
    "interruption_level": "time-sensitive",
    "data": {
      "id": "live-test-order-7890",
      "category": "order",
      "notification_type": "workflow_tracking",
      "conversation_id": "order-7890",
      "item_title": "Order #7890",
      "item_subtitle": "$899.99",
      "item_details": "iPhone 15 Pro Max",
      "workflow_state": {
        "step_name": "Order Placed",
        "current_step": 1,
        "total_steps": 4,
        "progress_percent": 25,
        "steps": [
          {"name": "Order Placed", "status": "completed"},
          {"name": "Payment Processing", "status": "pending"},
          {"name": "Preparing Shipment", "status": "pending"},
          {"name": "Shipped", "status": "pending"}
        ]
      },
      "customer_branding": {
        "name": "Acme Corp",
        "color": "#FF6B35",
        "logo_url": null
      }
    }
  }'
📝 Configuration Options:

Silent/Passive Updates

Send background updates without sound or notification banner (useful for frequent updates):

curl -X POST "https://lerty.ai/api/push/live-activity/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_id": "notif_456",
    "priority": "low",
    "content_state": {
      "itemTitle": "Order Processing",
      "status": "Preparing",
      "progressPercent": 35,
      "currentStep": 2
    }
  }'

Note: Use "priority": "low" for silent Live Activity updates that only appear on the lock screen without alerting the user.

Updating a Live Activity

Send progress updates to an active Live Activity:

curl -X POST "https://lerty.ai/api/push/live-activity/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_id": "notif_456",
    "content_state": {
      "itemTitle": "Order Delivery",
      "itemSubtitle": "Your package is on the way",
      "status": "In Transit",
      "currentStep": 2,
      "totalSteps": 4,
      "stepName": "Out for Delivery",
      "progressPercent": 50,
      "lastUpdate": 1730462400
    }
  }'

Ending a Live Activity

Dismiss the Live Activity when complete:

curl -X POST "https://lerty.ai/api/push/live-activity/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_id": "notif_456",
    "event": "end",
    "dismissal_date": 1730465000,
    "content_state": {
      "itemTitle": "Delivery Complete",
      "status": "Delivered",
      "progressPercent": 100,
      "lastUpdate": 1730462700
    }
  }'

Note on Timestamps: All timestamps (lastUpdate, dismissal_date) use Unix timestamp format in seconds. You can generate this in most languages:

API Endpoints Overview

Endpoint Method Purpose
/api/agents/:id/send POST Send message to agent
/api/agents/:id/callback POST Send typing indicators
/webhooks/agents/:id/message POST Send agent reply
/api/push/send POST Send push notification
/api/push/send/bulk POST Send bulk notifications
/api/push/devices GET List user devices
/api/push/live-activity/update POST Update Live Activity

Rate Limits

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Need Help?

Built with ❤️ by Lerty | lerty.ai