Docs

Ghost Integration Guide

Add Heyo live chat to your Ghost publication. Perfect for memberships and subscriber engagement.

This guide shows you how to add Heyo to your Ghost publication. Works with Ghost(Pro) and self-hosted Ghost.

Installation

Site-Wide Installation

In your Ghost Admin, go to Settings
Click Code injection
Paste this code in the Site Header section:

<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>

Click Save

The chat widget will now appear on all pages of your publication.

Member-Only Chat

Show chat only to logged-in members:

<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>

{{#if @member}}
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: {
        name: '{{@member.name}}',
        email: '{{@member.email}}',
        id: '{{@member.uuid}}'
      }
    });
  }
});
</script>
{{else}}
<style>
  #heyo-widget-button {
    display: none !important;
  }
</style>
{{/if}}

Premium Member Perks

Offer chat as a premium member benefit:

<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>

{{#if @member}}
  {{#has status="paid"}}
  <script>
  window.addEventListener('load', function() {
    if (window.HEYO) {
      window.HEYO.init({
        projectId: 'YOUR_PROJECT_ID',
        user: {
          name: '{{@member.name}}',
          email: '{{@member.email}}',
          subscription: 'premium'
        }
      });
      window.HEYO.show();
    }
  });
  </script>
  {{else}}
  <style>
    #heyo-widget-button {
      display: none !important;
    }
  </style>
  {{/has}}
{{/if}}

Advanced Usage

Show on Specific Pages

Use Ghost's route helpers:

<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>

{{#is "post"}}
<script>
// Show chat on blog posts
window.HEYO?.show();
</script>
{{/is}}

{{#is "page"}}
<style>
  /* Hide chat on static pages */
  #heyo-widget-button {
    display: none !important;
  }
</style>
{{/is}}

Pass Member Tier Information

{{#if @member}}
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: {
        name: '{{@member.name}}',
        email: '{{@member.email}}',
        tier: '{{#foreach @member.subscriptions}}{{tier.name}}{{/foreach}}',
        status: '{{@member.status}}'
      }
    });
  }
});
</script>
{{/if}}

Custom Trigger in Posts

Add a custom chat button to your posts using Ghost's markdown/HTML:

<button onclick="window.HEYO?.show()" style="padding: 12px 24px; background: #6366f1; color: white; border: none; border-radius: 8px; cursor: pointer;">
  Chat with me about this post
</button>

Theme Integration

Modify Theme Files

For more advanced integration, you can modify your Ghost theme:

Download your theme (Settings > Design)
Extract the zip file
Add Heyo script to default.hbs in the <head> section
Re-zip and upload the theme

This allows version control and more granular placement.

Custom Theme Development

If building a custom theme, add to default.hbs:

<!DOCTYPE html>
<html>
<head>
    {{! ... other head content ... }}
    <script src="https://heyo.so/embed/script" defer data-project-id="{{@site.heyo_project_id}}"></script>
</head>
<body>
    {{{body}}}
</body>
</html>

Note: You'll need to replace {{@site.heyo_project_id}} with your actual project ID since Ghost doesn't support custom site properties by default.