README

Official PHP SDK for SimpleChat.dev - Session recording and analytics platform.

Installation

composer require simplechat/php-sdk

Basic Usage

use SimpleChat\SDK\SimpleChatClient;

$client = new SimpleChatClient('your-api-key');

// Create a session
$session = $client->sessions()->create('user-123', ['plan' => 'premium']);
echo $session['tracking_url'];
echo $session['admin_url'];

// List sessions
$sessions = $client->sessions()->list('active', null, 50, 0);

// Get session
$session = $client->sessions()->get('session-hash');

// Log events
$client->events()->log('session-hash', 'button_click', ['button' => 'signup']);

// Send chat message
$client->chat()->send('session-hash', 'Hello!', 'visitor');

Laravel Integration

Setup

Add to config/services.php:

'simplechat' => [
    'api_key' => env('SIMPLECHAT_API_KEY'),
],

Or set in .env:

SIMPLECHAT_API_KEY=your-api-key

Usage with Facade

use SimpleChat\SDK\Laravel\Facades\SimpleChat;

$session = SimpleChat::sessions()->create('user-123');

Usage with Dependency Injection

use SimpleChat\SDK\SimpleChatClient;

class YourController
{
    public function __construct(private SimpleChatClient $simplechat) {}

    public function track()
    {
        $session = $this->simplechat->sessions()->create(auth()->id());
        return response()->json($session);
    }
}

API Reference

Sessions

// Create session
$client->sessions()->create(?string $externalId, ?array $metadata): array

// List sessions
$client->sessions()->list(?string $status, ?string $externalId, int $limit, int $offset): array

// Get session
$client->sessions()->get(string $hash): array

// Get tracker URL
$client->sessions()->getTracker(): array

Events

// Log single event
$client->events()->log(string $sessionHash, string $type, array $data, ?string $pageUrl): array

// Log batch events
$client->events()->logBatch(string $sessionHash, array $events): array

// List events
$client->events()->list(string $sessionHash, int $afterId): array

Chat

// Send message
$client->chat()->send(string $sessionHash, string $message, string $senderType, ?int $userId): array

Exception Handling

use SimpleChat\SDK\Exceptions\SimpleChatException;
use SimpleChat\SDK\Exceptions\AuthenticationException;
use SimpleChat\SDK\Exceptions\NotFoundException;

try {
    $session = $client->sessions()->create();
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (NotFoundException $e) {
    // Resource not found
} catch (SimpleChatException $e) {
    // Other errors
}