Docs

Django Integration Guide

Add Heyo live chat to your Django application with template integration and user context support.

This guide shows you how to add Heyo to your Django application. Works with Django templates, Jinja2, and Django Rest Framework.

Installation

Add to Base Template

Add the Heyo script to your base template (usually base.html or templates/base.html):

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

That's it! The chat widget will now appear on all pages using this template.

Pass User Data

Method 1: Template Variable

Pass user data from your Django views:

{# In your base template #}
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>

{% if user.is_authenticated %}
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: {
        name: '{{ user.get_full_name|escapejs }}',
        email: '{{ user.email|escapejs }}',
        id: '{{ user.id }}'
      }
    });
  }
});
</script>
{% endif %}

Method 2: JSON Script Tag

For more complex data:

{% if user.is_authenticated %}
<script id="heyo-user-data" type="application/json">
{
  "name": "{{ user.get_full_name|escapejs }}",
  "email": "{{ user.email|escapejs }}",
  "id": {{ user.id }},
  "created": "{{ user.date_joined.isoformat }}"
}
</script>

<script>
window.addEventListener('load', function() {
  const userData = JSON.parse(document.getElementById('heyo-user-data').textContent);
  if (window.HEYO) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: userData
    });
  }
});
</script>
{% endif %}

Advanced Usage

Create a Template Tag

Create templatetags/heyo_tags.py:

from django import template
from django.conf import settings
from django.utils.safestring import mark_safe
import json

register = template.Library()

@register.simple_tag
def heyo_widget():
    project_id = getattr(settings, 'HEYO_PROJECT_ID', '')
    if not project_id:
        return ''
    
    return mark_safe(
        f'<script src="https://heyo.so/embed/script" defer data-project-id="{project_id}"></script>'
    )

@register.simple_tag(takes_context=True)
def heyo_user_data(context):
    user = context.get('user')
    if not user or not user.is_authenticated:
        return ''
    
    user_data = {
        'name': user.get_full_name() or user.username,
        'email': user.email,
        'id': user.id,
    }
    
    return mark_safe(
        f'''<script>
        window.addEventListener('load', function() {{
          if (window.HEYO) {{
            window.HEYO.init({{
              projectId: '{getattr(settings, "HEYO_PROJECT_ID", "")}',
              user: {json.dumps(user_data)}
            }});
          }}
        }});
        </script>'''
    )

Usage in templates:

{% load heyo_tags %}

<!DOCTYPE html>
<html>
<head>
    {% heyo_widget %}
</head>
<body>
    {% block content %}{% endblock %}
    {% heyo_user_data %}
</body>
</html>

Add to settings.py:

HEYO_PROJECT_ID = 'YOUR_PROJECT_ID'

Context Processor

Create context_processors.py:

from django.conf import settings

def heyo_settings(request):
    return {
        'HEYO_PROJECT_ID': getattr(settings, 'HEYO_PROJECT_ID', ''),
        'heyo_user_data': {
            'name': request.user.get_full_name() if request.user.is_authenticated else None,
            'email': request.user.email if request.user.is_authenticated else None,
        } if request.user.is_authenticated else None
    }

Add to settings.py:

TEMPLATES = [
    {
        'OPTIONS': {
            'context_processors': [
                # ... other processors
                'your_app.context_processors.heyo_settings',
            ],
        },
    },
]

Usage in templates:

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

{% if heyo_user_data %}
<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.init({
      projectId: '{{ HEYO_PROJECT_ID }}',
      user: {{ heyo_user_data|safe }}
    });
  }
});
</script>
{% endif %}

Show Only on Specific Pages

Using Django's template conditions:

{% if request.path != '/checkout/' %}
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
{% endif %}

Django Rest Framework Integration

For API-based applications with a separate frontend, add Heyo to your frontend application and use DRF for user authentication.

You can create an API endpoint to get user data:

# views.py
from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view(['GET'])
def heyo_user_info(request):
    if not request.user.is_authenticated:
        return Response({'authenticated': False})
    
    return Response({
        'authenticated': True,
        'user': {
            'name': request.user.get_full_name(),
            'email': request.user.email,
            'id': request.user.id,
        }
    })

Django CMS / Wagtail

For Django CMS or Wagtail, add the Heyo script to your base template the same way:

{# In your CMS base template #}
<head>
    {% block extra_js %}{% endblock %}
    <script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
</head>

Best Practices

Add script to base template for site-wide availability
Use escapejs filter when passing user data
Store Project ID in Django settings
Create reusable template tags for cleaner templates
Use context processors for global availability
Check user authentication before passing data

Troubleshooting

Widget not appearing

Verify Project ID is correct in settings
Check that template is extending the base template
Ensure no JavaScript errors in console

User data not showing

Use escapejs filter to prevent XSS and escaping issues
Check that user is authenticated
Verify JSON is valid in browser console

Template tag not found

Ensure templatetags directory has __init__.py
Load template tags with {% load heyo_tags %}
Restart Django development server

Next Steps

Carrd Integration Guide

Add Heyo live chat to your Carrd landing page. Perfect for solo founders and quick MVPs.

Elementor Integration Guide

Add Heyo live chat to your Elementor website. Works with Elementor and Elementor Pro.