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()orhtmlentities()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