Home Assistant Jokes Integration

A custom Home Assistant integration that fetches random jokes from multiple sources and provides them as a sensor entity.

Features

🎭 Fetches random jokes from 5 built-in sources — 3 family-friendly (on by default) plus 2 opt-in sources clearly marked ⚠️ not family-friendly
🔀 Random provider selection for variety
🛡️ Fault tolerance - automatically tries alternative providers if one fails
📊 Creates a sensor entity with state "OK" when successful
🏷️ Stores joke text, ID, and source as attributes (no 255 character state limitation)
⏰ Configurable refresh interval (1-1440 minutes, default: 5 minutes)
🤖 AI-powered joke explanations using Home Assistant's AI integration
⚙️ Easy configuration through Home Assistant UI
🔄 Supports options flow for changing settings
🛡️ Robust error handling and logging
📱 HACS compliant for easy installation

Installation

HACS (Recommended)

Open HACS in your Home Assistant instance
Find "Jokes" in the integration list and install it
Restart Home Assistant
Go to Configuration > Integrations
Click "+ Add Integration" and search for "Jokes"

Or open it directly from here:

Manual Installation

Download the latest release from the releases page
Extract the contents
Copy the custom_components/ha_jokes folder to your Home Assistant custom_components directory
Restart Home Assistant
Go to Configuration > Integrations
Click "+ Add Integration" and search for "Jokes"

Configuration

Initial Setup

Go to Settings → Devices & Services
Click "+ Add Integration"
Search for "Jokes"
Set your desired refresh interval (1-1440 minutes, default: 5)
Click "Submit"

Changing Options

Go to Settings → Devices & Services
Find the Jokes integration
Click "Configure"
Adjust the refresh interval as needed
Select/de-select joke providers
Click "Submit"

The setup and options screens list every joke source. The two opt-in sources are labelled ⚠️ not family-friendly and are unchecked by default:

Usage

After installation, the integration creates a sensor entity:

Entity ID: sensor.joke
State: "OK" when successful, "Error" when failed
Icon: 🙂 (mdi:emoticon-happy-outline)

Attributes

The sensor provides the following attributes:

joke: The complete joke text
joke_id: Unique identifier for the joke
source: The joke provider that supplied the joke
last_updated: Timestamp of the last successful update
refresh_interval: Current refresh interval in minutes

Example Usage in Lovelace

Simple Entity Card

type: entity
entity: sensor.joke
attribute: joke
name: "Joke of the Moment"

Markdown Card with last updated time

type: markdown
content: |
  ## 😄 Joke
  {{ state_attr('sensor.joke', 'joke') }}
  
  *Last updated @ {{ as_datetime(state_attr('sensor.joke', 'last_updated')).strftime('%H:%M %d %b %Y') }}*
  *Source: {{ state_attr('sensor.joke', 'source') }}*

Markdown Card with time since last update

type: markdown
content: |
  ## 😄 Joke
  {{ state_attr('sensor.joke', 'joke') }}
  
  *Last updated: {{ relative_time(as_datetime(state_attr('sensor.joke', 'last_updated'))) }} ago*
  *Source: {{ state_attr('sensor.joke', 'source') }}*

Custom Card with Conditional Display

type: conditional
conditions:
  - entity: sensor.joke
    state: "OK"
card:
  type: markdown
  content: |
    ## 🎭 Today's Joke
    {{ state_attr('sensor.joke', 'joke') }}
    
    **Joke ID**: {{ state_attr('sensor.joke', 'joke_id') }}
    **Source**: {{ state_attr('sensor.joke', 'source') }}
    **Updated**: {{ state_attr('sensor.joke', 'last_updated') }}

Button Card Example (requires button-card from HACS)

type: custom:button-card
entity: sensor.joke
name: Daily Joke
show_state: false
styles:
  card:
    - background-color: var(--primary-background-color)
    - padding: 20px
    - border-radius: 15px
  name:
    - font-size: 20px
    - font-weight: bold
    - color: var(--primary-text-color)
custom_fields:
  joke: |
    [[[
      return `<div style="font-size: 16px; line-height: 1.5; margin-top: 10px;">
        ${states['sensor.joke'].attributes.joke}
      </div>`
    ]]]
  source: |
    [[[
      return `<div style="font-size: 12px; color: var(--secondary-text-color); margin-top: 10px;">
        Source: ${states['sensor.joke'].attributes.source}
      </div>`
    ]]]

Entities Card

type: entities
title: Joke
entities:
  - entity: sensor.joke
    type: attribute
    attribute: joke
    name: Current Joke
  - entity: sensor.joke
    type: attribute
    attribute: source
    name: Source
    icon: mdi:information-outline
  - entity: sensor.joke
    type: attribute
    attribute: last_updated
    name: Last Updated
    icon: mdi:clock-outline

Automations

You can use the sensor in automations:

automation:
  - alias: "Announce Joke"
    trigger:
      - platform: state
        entity_id: sensor.joke
        attribute: joke
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "New Joke!"
          message: "{{ state_attr('sensor.joke', 'joke') }}"

AI-Powered Joke Explanations

The integration provides an ha_jokes.explain_joke service that uses Home Assistant's AI integration to explain the current joke in plain language. This is perfect for jokes that might have wordplay, cultural references, or puns that need clarification.

Requirements

Home Assistant AI integration must be configured (e.g., OpenAI, Google Generative AI, or Azure AI)
A default AI conversation agent must be set up

Usage

From the Developer Tools:

Go to Developer Tools → Actions
Select the ha_jokes.explain_joke action
Click "Perform Action"

In Automations:

automation:
  - alias: "Explain Joke on Request"
    trigger:
      - platform: state
        entity_id: input_boolean.explain_joke_trigger
        to: "on"
    action:
      - service: ha_jokes.explain_joke
      - service: notify.mobile_app_your_phone
        data:
          title: "Joke Explanation"
          message: "{{ state_attr('sensor.joke_explanation', 'explanation') }}"

In Scripts:

script:
  get_joke_explanation:
    sequence:
      - service: ha_jokes.explain_joke
      - delay:
          seconds: 5
      - service: notify.persistent_notification
        data:
          title: "Joke Explanation"
          message: "{{ state_attr('sensor.joke_explanation', 'explanation') }}"

Explanation Sensor

After calling the explain_joke service, the explanation is stored in the sensor.joke_explanation entity:

Entity ID: sensor.joke_explanation
State: "Explained" when an explanation is available, "Not Explained" otherwise
Attribute: explanation contains the AI-generated explanation

Example Lovelace Card:

type: vertical-stack
cards:
  - type: markdown
    content: |
      ## 😄 Joke
      {{ state_attr('sensor.joke', 'joke') }}
  - type: button
    name: Explain This Joke
    icon: mdi:comment-question-outline
    tap_action:
      action: call-service
      service: ha_jokes.explain_joke
  - type: conditional
    conditions:
      - entity: sensor.joke_explanation
        state: "Explained"
    card:
      type: markdown
      content: |
        ### 💡 Explanation
        {{ state_attr('sensor.joke_explanation', 'explanation') }}

Jokes Card (recommended)

The integration ships its own Lovelace card, custom:ha-jokes-card. It is bundled with the integration and auto-registered — there is nothing to install in HACS and no Lovelace resource to add by hand. After a restart, add a card to your dashboard, pick "Jokes Card" from the card picker (or paste the YAML below).

The card shows the current joke in a styled quote, its source and how long ago it updated, an Explain it button (triggers an AI explanation via ha_jokes.explain_joke), a New joke button (fetches a fresh joke on demand), and a conditional explanation panel that appears once an explanation has been generated. It uses your active theme's colours, so it looks right in both light and dark mode.

The AI writes its explanation in Markdown, and the card renders it properly — bold emphasis, paragraphs, and numbered/bulleted lists — using Home Assistant's own Markdown renderer, so it matches the styling of the core Markdown card. Two-part jokes keep the line break between setup and punchline.

The card has a visual editor — pick it from the card picker and you get proper form controls for every option below, so there is no need to write YAML by hand.

The explanation panel clears itself whenever the joke changes (the New joke button, a manual refresh, or the automatic refresh interval), so you never see an explanation for a joke that is no longer on screen.

type: custom:ha-jokes-card
# all options below are optional — these are the defaults
entity: sensor.joke
explanation_entity: sensor.joke_explanation
title: Joke of the Moment
explanation_position: below
height: 0
width: 0
show_source: true
show_buttons: true

Option	Default	Description
`entity`	`sensor.joke`	The joke sensor to display.
`explanation_entity`	`sensor.joke_explanation`	Sensor holding the AI explanation.
`title`	`Joke of the Moment`	Card heading.
`explanation_position`	`below`	`below` stacks the explanation under the joke; `side` puts it alongside. `side` automatically falls back to stacking when the card is too narrow for two columns.
`height`	`0`	Minimum card height in px (`0` = automatic). Useful to stop the card resizing as the explanation appears and disappears.
`width`	`0`	Maximum card width in px (`0` = fill the column).
`show_source`	`true`	Show the source/provider line.
`show_buttons`	`true`	Show the Explain it / New joke buttons.

If you'd rather not use the custom card, a built-in-cards-only alternative (plus an optional Mushroom variant) lives in examples/joke-cards.yaml — it works with core cards only.

API Information

This integration fetches jokes from several different sources, automatically selecting them in random order and providing fault tolerance if one source is unavailable:

Joke Sources

icanhazdadjoke.com - A curated collection of dad jokes
- Provides free access to dad jokes
- Returns jokes in JSON format with unique IDs
- No API key required
JokeAPI v2 - A RESTful API serving jokes
- Configured in safe mode (no explicit content)
- Returns single-line jokes only
- Free and open source
- No API key required
Official Joke API - A simple joke API
- Community-maintained joke collection
- Returns setup/punchline format jokes
- Free and open source
- No API key required
Geek Jokes - Random one-liners
- ⚠️ Not family-friendly — despite the name, the feed is mostly Chuck Norris jokes with some crude/edgy content and no safe-mode filter. Disabled by default; opt in via the integration options
- Returns single-line jokes
- Free, no API key required
Yo Mama Jokes - Roast-style "yo mama" jokes
- ⚠️ Not family-friendly (adult/roast humour) — disabled by default; opt in via the integration options
- Returns single-line jokes
- Free, no API key required

The integration randomly selects which provider to use for each joke request. If a provider fails to respond, it automatically tries the next provider, ensuring you always get a joke as long as at least one service is available.

Troubleshooting

Common Issues

Sensor shows "Error" state
- Check your internet connection
- Verify that at least one joke API is accessible
- Check Home Assistant logs for detailed error messages
- The integration will automatically try alternative providers
Integration not appearing
- Ensure you've restarted Home Assistant after installation
- Check that the custom_components/ha_jokes folder is in the correct location
- Verify all required files are present
Jokes not updating
- Check the refresh interval setting
- Verify the sensor state is "OK"
- Check logs for any error messages

Logs

To enable debug logging for this integration, add the following to your configuration.yaml:

logger:
  logs:
    custom_components.ha_jokes: debug

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Approach

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Credits

Jokes provided by:
- icanhazdadjoke.com
- JokeAPI v2 by Sven Fehler
- Official Joke API by David Katz
- Geek Jokes by Sameer Kumar (unfiltered, opt-in)
- Yo Mama Jokes (adult/roast humour, opt-in)
Integration developed for the Home Assistant community

Name		Name	Last commit message	Last commit date
.github		.github
custom_components/ha_jokes		custom_components/ha_jokes
examples		examples
images		images
scripts		scripts
.gitignore		.gitignore
BREAKING_CHANGES.md		BREAKING_CHANGES.md
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
info.md		info.md

Navigation Menu

Repository files navigation

Home Assistant Jokes Integration

Features

Installation

HACS (Recommended)

Manual Installation

Configuration

Initial Setup

Changing Options

Usage

Attributes

Example Usage in Lovelace

Simple Entity Card

Markdown Card with last updated time

Markdown Card with time since last update

Custom Card with Conditional Display

Button Card Example (requires button-card from HACS)

Entities Card

Automations

AI-Powered Joke Explanations

Requirements

Usage

Explanation Sensor

Jokes Card (recommended)

API Information

Joke Sources

Troubleshooting

Common Issues

Logs

Contributing

Development Approach

License

Support

Credits

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Home Assistant Jokes Integration

Features

Installation

HACS (Recommended)

Manual Installation

Configuration

Initial Setup

Changing Options

Usage

Attributes

Example Usage in Lovelace

Simple Entity Card

Markdown Card with last updated time

Markdown Card with time since last update

Custom Card with Conditional Display

Button Card Example (requires button-card from HACS)

Entities Card

Automations

AI-Powered Joke Explanations

Requirements

Usage

Explanation Sensor

Jokes Card (recommended)

API Information

Joke Sources

Troubleshooting

Common Issues

Logs

Contributing

Development Approach

License

Support

Credits

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages