Docs

PHP Integration Guide

Add Heyo live chat to any PHP website or application. Works with vanilla PHP, frameworks, and CMSs.

This guide shows you how to add Heyo to your PHP website or application. Works with vanilla PHP, custom frameworks, and any PHP setup.

Installation

Basic Setup

Add the Heyo script to your PHP template or header file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My PHP Site</title>
    
    <!-- Add Heyo before closing head tag -->
    <script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
</head>
<body>
    <!-- Your content -->
</body>
</html>

Using PHP Include Files

If you use header/footer includes:

header.php:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?php echo $page_title ?? 'My Site'; ?></title>
    
    <script src="https://heyo.so/embed/script" defer data-project-id="<?php echo HEYO_PROJECT_ID; ?>"></script>
</head>
<body>

config.php:

<?php
define('HEYO_PROJECT_ID', 'YOUR_PROJECT_ID');

index.php:

<?php
require_once 'config.php';
require_once 'header.php';
?>

<h1>Welcome to my site</h1>

<?php require_once 'footer.php'; ?>

Pass User Data

Method 1: Session Data

If you have user authentication via sessions:

<?php
session_start();
$isLoggedIn = isset($_SESSION['user_id']);
?>

<script src="https://heyo.so/embed/script" defer data-project-id="<?php echo HEYO_PROJECT_ID; ?>"></script>

<?php if ($isLoggedIn): ?>
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: '<?php echo HEYO_PROJECT_ID; ?>',
      user: {
        name: '<?php echo htmlspecialchars($_SESSION['user_name'], ENT_QUOTES); ?>',
        email: '<?php echo htmlspecialchars($_SESSION['user_email'], ENT_QUOTES); ?>',
        id: <?php echo (int)$_SESSION['user_id']; ?>
      }
    });
  }
});
</script>
<?php endif; ?>

Method 2: JSON Encoding

For more complex data:

<?php
if ($isLoggedIn) {
    $userData = [
        'name' => $_SESSION['user_name'],
        'email' => $_SESSION['user_email'],
        'id' => $_SESSION['user_id'],
        'plan' => $_SESSION['user_plan'] ?? 'free',
    ];
}
?>

<?php if ($isLoggedIn): ?>
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: '<?php echo HEYO_PROJECT_ID; ?>',
      user: <?php echo json_encode($userData); ?>
    });
  }
});
</script>
<?php endif; ?>

Advanced Usage

Create a Helper Function

Create helpers.php:

<?php

function heyo_widget($projectId = null) {
    $projectId = $projectId ?? HEYO_PROJECT_ID;
    if (empty($projectId)) {
        return '';
    }
    
    return sprintf(
        '<script src="https://heyo.so/embed/script" defer data-project-id="%s"></script>',
        htmlspecialchars($projectId, ENT_QUOTES)
    );
}

function heyo_user_data(array $user = null) {
    if (empty($user)) {
        return '';
    }
    
    $projectId = HEYO_PROJECT_ID;
    $userJson = json_encode($user);
    
    return <<<HTML
    <script>
    window.addEventListener('load', function() {
      if (window.HEYO) {
        window.HEYO.init({
          projectId: '{$projectId}',
          user: {$userJson}
        });
      }
    });
    </script>
    HTML;
}

function get_current_user() {
    if (!isset($_SESSION['user_id'])) {
        return null;
    }
    
    return [
        'name' => $_SESSION['user_name'] ?? '',
        'email' => $_SESSION['user_email'] ?? '',
        'id' => $_SESSION['user_id'],
    ];
}

Usage:

<?php
require_once 'config.php';
require_once 'helpers.php';
session_start();
?>

<!DOCTYPE html>
<html>
<head>
    <?php echo heyo_widget(); ?>
</head>
<body>
    <h1>My Site</h1>
    
    <?php echo heyo_user_data(get_current_user()); ?>
</body>
</html>

Object-Oriented Approach

Create Heyo.php:

<?php

class Heyo {
    private $projectId;
    private $user;
    
    public function __construct($projectId) {
        $this->projectId = $projectId;
    }
    
    public function setUser(array $user) {
        $this->user = $user;
        return $this;
    }
    
    public function renderWidget() {
        if (empty($this->projectId)) {
            return '';
        }
        
        return sprintf(
            '<script src="https://heyo.so/embed/script" defer data-project-id="%s"></script>',
            htmlspecialchars($this->projectId, ENT_QUOTES)
        );
    }
    
    public function renderUserInit() {
        if (empty($this->user)) {
            return '';
        }
        
        $userJson = json_encode($this->user);
        
        return <<<HTML
        <script>
        window.addEventListener('load', function() {
          if (window.HEYO) {
            window.HEYO.init({
              projectId: '{$this->projectId}',
              user: {$userJson}
            });
          }
        });
        </script>
        HTML;
    }
}

Usage:

<?php
$heyo = new Heyo(HEYO_PROJECT_ID);

if (isset($_SESSION['user_id'])) {
    $heyo->setUser([
        'name' => $_SESSION['user_name'],
        'email' => $_SESSION['user_email'],
        'id' => $_SESSION['user_id'],
    ]);
}
?>

<!DOCTYPE html>
<html>
<head>
    <?php echo $heyo->renderWidget(); ?>
</head>
<body>
    <h1>My Site</h1>
    
    <?php echo $heyo->renderUserInit(); ?>
</body>
</html>

Environment-Based Configuration

Using .env file (manually):

<?php
// Load environment variables
$env = parse_ini_file('.env');

define('HEYO_PROJECT_ID', $env['HEYO_PROJECT_ID'] ?? '');

.env:

HEYO_PROJECT_ID=YOUR_PROJECT_ID

Show Only on Specific Pages

<?php
$currentPage = basename($_SERVER['PHP_SELF']);
$showChat = !in_array($currentPage, ['checkout.php', 'payment.php']);
?>

<?php if ($showChat): ?>
<script src="https://heyo.so/embed/script" defer data-project-id="<?php echo HEYO_PROJECT_ID; ?>"></script>
<?php endif; ?>

Database-Driven User Data

If storing users in a database:

<?php
function getCurrentUser($pdo) {
    if (!isset($_SESSION['user_id'])) {
        return null;
    }
    
    $stmt = $pdo->prepare('SELECT id, name, email FROM users WHERE id = ?');
    $stmt->execute([$_SESSION['user_id']]);
    return $stmt->fetch(PDO::FETCH_ASSOC);
}

$user = getCurrentUser($pdo);
?>

<?php if ($user): ?>
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: '<?php echo HEYO_PROJECT_ID; ?>',
      user: <?php echo json_encode($user); ?>
    });
  }
});
</script>
<?php endif; ?>

Best Practices

Always use htmlspecialchars() or htmlentities() when outputting user data
Use json_encode() for complex data structures
Store Project ID in config file or environment variables
Create helper functions for reusability
Check user authentication before passing data
Use prepared statements for database queries

Security Considerations

XSS Prevention

Always escape output:

<?php
// BAD - Vulnerable to XSS
echo "<script>var name = '{$_SESSION['user_name']}';</script>";

// GOOD - Properly escaped
echo "<script>var name = '" . htmlspecialchars($_SESSION['user_name'], ENT_QUOTES) . "';</script>";

// BETTER - Using JSON encoding
$userData = ['name' => $_SESSION['user_name']];
echo "<script>var user = " . json_encode($userData) . ";</script>";
?>

SQL Injection Prevention

Use prepared statements:

<?php
// BAD - Vulnerable to SQL injection
$user = $pdo->query("SELECT * FROM users WHERE id = {$_SESSION['user_id']}")->fetch();

// GOOD - Using prepared statement
$stmt = $pdo->prepare('SELECT * FROM users WHERE id = ?');
$stmt->execute([$_SESSION['user_id']]);
$user = $stmt->fetch();
?>

Troubleshooting

Widget not appearing

Verify Project ID is correctly set
Check that script is in <head> tag
Look for JavaScript errors in console

User data not showing

Ensure proper HTML escaping
Check that session is started
Verify JSON encoding is valid

Variables not defined

Check that config file is included
Verify constants are defined before use

Next Steps

Nuxt Integration Guide

Add Heyo live chat to your Nuxt application with SSR support for Nuxt 2, 3, and Bridge.

React Integration Guide

Add Heyo live chat to your React application with hooks and TypeScript support.