Docs

Laravel Integration Guide

Add Heyo live chat to your Laravel application with Blade template integration. Works with Livewire and Inertia.

This guide shows you how to add Heyo to your Laravel application. Works with Blade templates, Livewire, and Inertia.js.

Installation

Add to Blade Layout

Add the Heyo script to your main layout file (usually resources/views/layouts/app.blade.php):

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>@yield('title', config('app.name'))</title>
    
    {{-- Add Heyo before closing head tag --}}
    <script src="https://heyo.so/embed/script" defer data-project-id="{{ config('services.heyo.project_id') }}"></script>
</head>
<body>
    @yield('content')
</body>
</html>

Add to config/services.php:

return [
    // ... other services
    
    'heyo' => [
        'project_id' => env('HEYO_PROJECT_ID'),
    ],
];

Add to .env:

HEYO_PROJECT_ID=YOUR_PROJECT_ID

Pass User Data

Method 1: Auth Check in Blade

<script src="https://heyo.so/embed/script" defer data-project-id="{{ config('services.heyo.project_id') }}"></script>

@auth
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: '{{ config('services.heyo.project_id') }}',
      user: {
        name: '{{ auth()->user()->name }}',
        email: '{{ auth()->user()->email }}',
        id: {{ auth()->user()->id }}
      }
    });
  }
});
</script>
@endauth

Method 2: JSON Encode

For more complex user data:

@auth
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: '{{ config('services.heyo.project_id') }}',
      user: @json([
        'name' => auth()->user()->name,
        'email' => auth()->user()->email,
        'id' => auth()->user()->id,
        'created_at' => auth()->user()->created_at->toIso8601String(),
      ])
    });
  }
});
</script>
@endauth

Advanced Usage

Create a Blade Component

Create app/View/Components/HeyoWidget.php:

<?php

namespace App\View\Components;

use Illuminate\View\Component;

class HeyoWidget extends Component
{
    public function render()
    {
        return view('components.heyo-widget');
    }
    
    public function getUserData()
    {
        if (!auth()->check()) {
            return null;
        }
        
        return [
            'name' => auth()->user()->name,
            'email' => auth()->user()->email,
            'id' => auth()->user()->id,
        ];
    }
}

Create resources/views/components/heyo-widget.blade.php:

<script src="https://heyo.so/embed/script" defer data-project-id="{{ config('services.heyo.project_id') }}"></script>

@if($userData = $getUserData())
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: '{{ config('services.heyo.project_id') }}',
      user: @json($userData)
    });
  }
});
</script>
@endif

Usage in layouts:

<head>
    <x-heyo-widget />
</head>

Service Provider Method

Create app/Providers/HeyoServiceProvider.php:

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;

class HeyoServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Blade::directive('heyo', function () {
            return "<?php echo view('heyo::widget'); ?>";
        });
        
        $this->loadViewsFrom(__DIR__.'/../../resources/views/heyo', 'heyo');
    }
}

'providers' => [
    // ...
    App\Providers\HeyoServiceProvider::class,
],

Usage:

<head>
    @heyo
</head>

Laravel Livewire Integration

Heyo works seamlessly with Livewire. Add to your layout:

<!DOCTYPE html>
<html>
<head>
    @livewireStyles
    <script src="https://heyo.so/embed/script" defer data-project-id="{{ config('services.heyo.project_id') }}"></script>
</head>
<body>
    @yield('content')
    
    @livewireScripts
</body>
</html>

Control from Livewire components:

// In a Livewire component
public function openChat()
{
    $this->dispatchBrowserEvent('open-heyo-chat');
}

<script>
window.addEventListener('open-heyo-chat', () => {
    window.HEYO?.show();
});
</script>

Inertia.js Integration

For Inertia.js apps, add to resources/js/app.js:

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';

createInertiaApp({
    resolve: name => require(`./Pages/${name}`),
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el);
        
        // Initialize Heyo
        if (props.initialPage.props.auth.user) {
            window.HEYO?.init({
                projectId: import.meta.env.VITE_HEYO_PROJECT_ID,
                user: props.initialPage.props.auth.user
            });
        }
    },
});

In your Inertia middleware, share user data:

public function share(Request $request)
{
    return array_merge(parent::share($request), [
        'auth' => [
            'user' => $request->user() ? [
                'name' => $request->user()->name,
                'email' => $request->user()->email,
            ] : null,
        ],
    ]);
}

Multi-Tenant Applications

For multi-tenant apps, use different Project IDs per tenant:

@php
$projectId = auth()->user()->tenant->heyo_project_id ?? config('services.heyo.project_id');
@endphp

<script src="https://heyo.so/embed/script" defer data-project-id="{{ $projectId }}"></script>

Route-Based Control

Show chat only on specific routes:

@unless(request()->routeIs('checkout.*'))
<script src="https://heyo.so/embed/script" defer data-project-id="{{ config('services.heyo.project_id') }}"></script>
@endunless

Best Practices

Store Project ID in config/services.php
Use .env for environment-specific IDs
Use @json() directive for safe JSON encoding
Create Blade components for reusability
Leverage Laravel's auth helpers
Check authentication before passing user data

Troubleshooting

Widget not appearing

Verify HEYO_PROJECT_ID is set in .env
Run php artisan config:clear after changes
Check browser console for errors

User data not showing

Ensure user is authenticated
Use @json() for proper JSON encoding
Check that config is cached properly

Blade component not found

Run php artisan view:clear
Verify component namespace and location

Next Steps

JavaScript Integration Guide

Add Heyo live chat to your JavaScript application. Works with vanilla JS, jQuery, and any library.

Next.js Integration Guide

Add Heyo live chat to your Next.js app with support for App Router and Pages Router.