New: Threema Integration by LukasQ · Pull Request #165993 · home-assistant/core

LukasQ · 2026-03-19T09:52:54Z

Proposed change

My first core PR 🥳

Reopened as a clean PR after the previous one (#165787) was closed due to force-push noise affecting other contributors. Apologies for the disruption.

Privacy matters. Threema is one of the few messengers that doesn't require a phone number, is fully end-to-end encrypted by default, and is open source. With over 12 million users — especially popular in the DACH region — it's a natural fit for Home Assistant
This integration brings Threema Gateway support to HA Core, enabling users to send secure text messages from their automations. It supports both E2E encrypted and simple transport modes, key pair generation during setup, and a QR code entity for identity verification — staying true to Threema's security-first philosophy.

What's included:

Config flow with credential validation, key generation, and reauthentication
~~threema.send_message service (E2E encrypted or simple mode)~~ notify entity
~~QR code image entity for gateway identity verification~~ future release
Full test coverage (config flow, setup/unload, service calls, error handling, image platform)
Silver quality scale compliance, but ready for gold

What's not included (intentionally)

No notify entity — NotifyEntity.async_send_message doesn't support recipients, and Threema always requires one. The custom service is the right interface here. Built on the official SDK. Depends on threema.gateway==8.0.0 and qrcode==8.2
QR code image entity for gateway identity verification -> next release!

Additional developer related info is added to the readme.md, including a small roadmap.

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

Link to documentation pull request: Threema Integration Docs home-assistant.io#44160
Link to the brands pull request: Added Threema Brand brands#9994

Checklist

I understand the code I am submitting and can explain how it works.
The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.
Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io Threema Integration Docs home-assistant.io#44160

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies a diff between library versions and ideally a link to the changelog/release notes is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

Copilot

Pull request overview

Adds a new Home Assistant Core integration for Threema Gateway, enabling secure outbound messaging via a dedicated threema.send_message service and providing a QR-code image entity for gateway identity verification.

Changes:

Introduces the threema integration (config flow, runtime client, service registration, and image platform).
Adds translations, service metadata, icons, and quality scale declaration for the integration.
Adds full test suite coverage and registers new dependencies + strict typing configuration.

Reviewed changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`homeassistant/components/threema/__init__.py`	Integration setup/unload and `send_message` service handler
`homeassistant/components/threema/client.py`	Threema Gateway SDK wrapper client + key generation
`homeassistant/components/threema/config_flow.py`	Multi-step config flow including key generation + reauth
`homeassistant/components/threema/const.py`	Integration constants
`homeassistant/components/threema/image.py`	QR code `ImageEntity` implementation
`homeassistant/components/threema/icons.json`	Service icon metadata
`homeassistant/components/threema/manifest.json`	Integration manifest + requirements
`homeassistant/components/threema/quality_scale.yaml`	Declared quality scale status
`homeassistant/components/threema/services.yaml`	Service schema/selector metadata
`homeassistant/components/threema/strings.json`	Config flow/service/exception translations
`homeassistant/components/threema/README.md`	Developer-focused integration documentation
`tests/components/threema/__init__.py`	Test package marker
`tests/components/threema/conftest.py`	Shared fixtures and mocks for Threema tests
`tests/components/threema/test_config_flow.py`	Config flow + reauth tests
`tests/components/threema/test_image.py`	QR image entity tests
`tests/components/threema/test_init.py`	Setup/unload + service behavior tests
`requirements_all.txt`	Adds runtime dependencies for the integration
`requirements_test_all.txt`	Adds test environment dependencies
`mypy.ini`	Enables strict mypy checks for `homeassistant.components.threema.*`
`.strict-typing`	Marks integration as strict-typing
`homeassistant/generated/config_flows.py`	Registers config flow domain
`homeassistant/generated/integrations.json`	Adds generated integration metadata
`CODEOWNERS`	Adds code ownership entries for the new integration and tests

You can also share your feedback on Copilot code review. Take the survey.

homeassistant/components/threema/config_flow.py

homeassistant/components/threema/__init__.py

Add new integration for Threema Gateway messaging service. Supports E2E encrypted and simple text messaging, key pair generation, QR code identity verification, and reauthentication. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

NoRi2909

Two small comments.

homeassistant/components/threema/strings.json

good catch. Co-authored-by: Norbert Rittel <norbert@rittel.de>

Co-authored-by: Norbert Rittel <norbert@rittel.de>

Copilot

Pull request overview

Adds a new Home Assistant Core integration for the Threema Gateway, enabling automations to send Threema messages (simple transport or E2E) and exposing a QR-code image entity for gateway identity verification.

Changes:

Implement Threema integration core: config flow (including key generation + reauth), runtime client wrapper, and threema.send_message service.
Add image platform entity that renders the gateway public key as a PNG QR code.
Add full test suite plus dependency pins, strict typing config, and generated metadata updates.

Reviewed changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
homeassistant/components/threema/init.py	Registers service, sets up config entries, forwards to image platform
homeassistant/components/threema/client.py	Wraps `threema.gateway` SDK for validation and message sending + key generation
homeassistant/components/threema/config_flow.py	Multi-step config flow (existing/new gateway), validation, and reauth
homeassistant/components/threema/const.py	Domain and config key constants
homeassistant/components/threema/image.py	ImageEntity that generates/stores QR code PNG bytes
homeassistant/components/threema/manifest.json	Declares integration metadata, requirements, logging, quality scale
homeassistant/components/threema/ गुणवत्ता_scale.yaml	Quality scale status declarations for the new integration
homeassistant/components/threema/services.yaml	Service selectors/field requirements for `send_message`
homeassistant/components/threema/strings.json	Config flow/service/entity/exception translations
homeassistant/components/threema/icons.json	Service icon mapping
homeassistant/components/threema/README.md	Developer-facing integration architecture/decisions notes
tests/components/threema/init.py	Test package marker for the integration
tests/components/threema/conftest.py	Shared fixtures for config entries and SDK patching
tests/components/threema/test_config_flow.py	Config flow test coverage (new/existing/reauth/error paths)
tests/components/threema/test_init.py	Setup/unload + service behavior tests
tests/components/threema/test_image.py	QR image entity creation/availability tests
requirements_all.txt	Adds runtime dependency pins for Threema + QR generation
requirements_test_all.txt	Adds test dependency pins for Threema + QR generation
mypy.ini	Enables strict mypy settings for `homeassistant.components.threema.*`
.strict-typing	Adds the integration to strict typing enforcement list
homeassistant/generated/integrations.json	Registers the new integration in generated metadata
homeassistant/generated/config_flows.py	Registers config flow domain in generated list
CODEOWNERS	Adds code ownership for integration + tests

You can also share your feedback on Copilot code review. Take the survey.

tests/components/threema/test_init.py

homeassistant/components/threema/image.py

joostlek

Hello 👋🏻,

So I would love to know a few things:

I know Threema as a chat app, what is the gateway qr code supposed to do?
Please make sure you either include a platform or services, not both. But preferrably a platform as that shows how state is handled in the integration
The current service has a recipient and a message, I would strongly consider to look at a notify entity. A benefit of using the notify entity is that you can group them and for example send a message to both telegram and threema with a group of notify entities, or send it to alexa if you want to. You would likely have to look into subentries for this one, given that we need to know the recipients before we can create the entity.
What's the idea behind the client.py? Ideally we have all device specific logic in a library hosted on pypi, and not in the integration

home-assistant · 2026-03-19T10:41:12Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

LukasQ · 2026-03-19T11:18:45Z

1. I know Threema as a chat app, what is the gateway qr code supposed to do?

QR Code displays the gateway's public key in Threema's 3mid: verification format. Users scan it with the Threema app to verify the gateway's identity — the three green dots confirming authenticity. Same verification mechanism as Threema's contact verification.

2. Please make sure you either include a platform or services, not both. But preferrably a platform as that shows how state is handled in the integration
3. The current service has a recipient and a message, I would strongly consider to look at a notify entity. A benefit of

Platform vs Service / Notify Entity: I originally used a service because I'm planning to extend this with image/file support. Now that you mentioned it, I could also go the Telegram way and use 'data'
Let me mull that over and come back with an updated approach.

4. What's the idea behind the client.py? Ideally we have all device specific logic in a library hosted on pypi, and not in the integration

The SDK (threema.gateway) handles all API communication — HTTP requests, encryption, key management, and the Threema protocol. client.py is essentially glue code: it maps SDK exceptions to HA-specific exception types and manages the connection context. Happy to extract it into a separate PyPI package if you feel that's necessary, but the actual device/service logic lives in the SDK already.

joostlek · 2026-03-19T11:28:57Z

Now that you mentioned it, I could also go the Telegram way and use 'data'

I believe data is for the old notify service, which is different

In any case, I think we should limit the initial scope, and I think a notify entity would make sense right of the bat, I would like to have more opinions on the image entity, so I think we can get it in a mergable state faster with notify entities and leave the other discussions for a later PR. (as in, I need to double check we like the qe code dependency in its current form as its not in a library)

Copilot

Pull request overview

Adds a new Home Assistant Threema Gateway integration (service-based) to enable sending Threema messages from automations, including an optional QR-code image entity for gateway identity verification.

Changes:

Introduces the threema integration with config flow (including key generation + reauth) and a threema.send_message service.
Adds an image platform entity that generates a QR code from the gateway public key.
Adds dependencies, typing config, generated integration metadata, and comprehensive tests.

Reviewed changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`homeassistant/components/threema/__init__.py`	Registers `send_message` service; sets up/unloads config entries and forwards to image platform.
`homeassistant/components/threema/client.py`	Implements `ThreemaAPIClient` wrapper and keypair generation helper.
`homeassistant/components/threema/config_flow.py`	Implements multi-step config flow (existing/new setup, credential validation, reauth).
`homeassistant/components/threema/const.py`	Defines integration constants and config keys.
`homeassistant/components/threema/image.py`	Adds QR-code `ImageEntity` for gateway identity verification.
`homeassistant/components/threema/manifest.json`	Declares integration metadata and requirements.
`homeassistant/components/threema/quality_scale.yaml`	Declares quality-scale compliance status for the new integration.
`homeassistant/components/threema/services.yaml`	Defines UI selectors/fields for `threema.send_message`.
`homeassistant/components/threema/strings.json`	Adds translations for config flow, service fields, and raised exceptions.
`homeassistant/components/threema/icons.json`	Adds service icon mapping.
`homeassistant/components/threema/README.md`	Adds developer-facing integration documentation/architecture notes.
`tests/components/threema/__init__.py`	Adds test package marker for the integration tests.
`tests/components/threema/conftest.py`	Provides fixtures for config entries, connection mocks, and message mocks.
`tests/components/threema/test_config_flow.py`	Tests config flow paths (existing/new, validation errors, reauth).
`tests/components/threema/test_image.py`	Tests QR-code image entity creation and availability.
`tests/components/threema/test_init.py`	Tests setup/unload and `send_message` service behavior & errors.
`requirements_all.txt`	Adds runtime requirements (`qrcode`, `threema.gateway`).
`requirements_test_all.txt`	Adds test requirements (`qrcode`, `threema.gateway`).
`.strict-typing`	Enables strict typing for the new integration module.
`mypy.ini`	Adds a strict mypy section for `homeassistant.components.threema.*`.
`homeassistant/generated/integrations.json`	Registers generated integration metadata entry for `threema`.
`homeassistant/generated/config_flows.py`	Registers `threema` in the generated config flow list.
`CODEOWNERS`	Assigns code ownership for the new integration and its tests.

You can also share your feedback on Copilot code review. Take the survey.

homeassistant/components/threema/config_flow.py

LukasQ · 2026-03-19T11:43:02Z

In any case, I think we should limit the initial scope, and I think a notify entity would make sense right of the bat

Already working on it.

as in, I need to double check we like the qe code dependency in its current form as its not in a library

It's already used by e.g. the PSN Integration afaik and I recommend strongly to include a QR code (whatever lib to use ;) ) to implement full verification in the first shot. Ideas?

joostlek · 2026-03-19T12:26:04Z

Well we still want to limit to a single platform in the initial PR, so you'd have to pick anyhow :)

Copilot

Pull request overview

Copilot reviewed 19 out of 21 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

Copilot reviewed 19 out of 21 changed files in this pull request and generated no new comments.

homeassistant/components/threema/config_flow.py

homeassistant/components/threema/README.md

tests/components/threema/conftest.py

tests/components/threema/test_config_flow.py

tests/components/threema/test_notify.py

Copilot

Pull request overview

Copilot reviewed 18 out of 20 changed files in this pull request and generated 2 comments.

tests/components/threema/conftest.py

Copilot

Pull request overview

Copilot reviewed 18 out of 20 changed files in this pull request and generated 2 comments.

homeassistant/components/threema/manifest.json

homeassistant/components/threema/quality_scale.yaml

joostlek · 2026-04-10T10:07:12Z

Putting back to draft as the library seems to use nacllib which doesn't seem to work on my dev environment

edenhaus

The library requires system packages to be installed and this is not anymore allowed. Currently the required libsodium is installed as it's part of a subsub dependency of ffmpeg but that could change anytime

Copilot AI review requested due to automatic review settings March 19, 2026 09:52

home-assistant bot added cla-signed has-tests integration: threema new-integration quality-scale labels Mar 19, 2026

This was referenced Mar 19, 2026

Threema Integration Docs home-assistant/home-assistant.io#44160

Open

Added Threema Brand home-assistant/brands#9994

Open

Copilot AI reviewed Mar 19, 2026

View reviewed changes

homeassistant/components/threema/config_flow.py Outdated Show resolved Hide resolved

homeassistant/components/threema/config_flow.py Outdated Show resolved Hide resolved

homeassistant/components/threema/__init__.py Outdated Show resolved Hide resolved

LukasQ force-pushed the feature/threema branch from 4c4bb12 to 3fcc223 Compare March 19, 2026 10:12

Add Threema integration

5834ad0

Add new integration for Threema Gateway messaging service. Supports E2E encrypted and simple text messaging, key pair generation, QR code identity verification, and reauthentication. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings March 19, 2026 10:19

LukasQ force-pushed the feature/threema branch from 3fcc223 to 5834ad0 Compare March 19, 2026 10:19

Merge branch 'dev' into feature/threema

5f50611

NoRi2909 reviewed Mar 19, 2026

View reviewed changes

homeassistant/components/threema/strings.json Outdated Show resolved Hide resolved

homeassistant/components/threema/strings.json Outdated Show resolved Hide resolved

LukasQ and others added 2 commits March 19, 2026 11:22

Update homeassistant/components/threema/strings.json

38d0986

good catch. Co-authored-by: Norbert Rittel <norbert@rittel.de>

Update homeassistant/components/threema/strings.json

dd4eaeb

Co-authored-by: Norbert Rittel <norbert@rittel.de>

Copilot AI reviewed Mar 19, 2026

View reviewed changes

tests/components/threema/test_init.py Outdated Show resolved Hide resolved

homeassistant/components/threema/image.py Outdated Show resolved Hide resolved

Fixed Copolot issue home-assistant#2 and home-assistant#3

b01d3c2

joostlek requested changes Mar 19, 2026

View reviewed changes

home-assistant bot marked this pull request as draft March 19, 2026 10:41

Added new roadmap ideas

60092cd

Copilot AI review requested due to automatic review settings March 19, 2026 11:25

Copilot AI reviewed Mar 19, 2026

View reviewed changes

homeassistant/components/threema/config_flow.py Outdated Show resolved Hide resolved

Moved from service to notify entity

5481ad0

Copilot started reviewing on behalf of LukasQ April 2, 2026 10:59 View session

full invalid journey in tests

4bd3a43

Copilot AI reviewed Apr 2, 2026

View reviewed changes

LukasQ added 2 commits April 2, 2026 13:07

closed 100% configflow codecov

783a641

corrected test

7b87a19

Copilot AI review requested due to automatic review settings April 2, 2026 11:27

Copilot started reviewing on behalf of LukasQ April 2, 2026 11:28 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

LukasQ marked this pull request as ready for review April 2, 2026 12:57

home-assistant bot requested a review from joostlek April 2, 2026 12:57

joostlek requested changes Apr 6, 2026

View reviewed changes

home-assistant bot marked this pull request as draft April 6, 2026 13:23

LukasQ added 2 commits April 7, 2026 08:48

deleted remote

dd133d9

updated exceptions

21671ee

Copilot AI review requested due to automatic review settings April 8, 2026 07:31

Copilot started reviewing on behalf of LukasQ April 8, 2026 07:32 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

tests/components/threema/conftest.py Show resolved Hide resolved

tests/components/threema/conftest.py Show resolved Hide resolved

LukasQ added 2 commits April 8, 2026 09:03

removed key editing in setup phase

e546ae7

updated testing

e403c0a

Copilot AI review requested due to automatic review settings April 8, 2026 09:36

Copilot started reviewing on behalf of LukasQ April 8, 2026 09:37 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

homeassistant/components/threema/manifest.json Show resolved Hide resolved

homeassistant/components/threema/quality_scale.yaml Show resolved Hide resolved

LukasQ marked this pull request as ready for review April 8, 2026 09:54

home-assistant bot requested a review from joostlek April 8, 2026 09:54

joostlek added 2 commits April 10, 2026 00:28

Merge branch 'dev' into feature/threema

c088ce9

Fix

409c226

joostlek marked this pull request as draft April 10, 2026 10:09

LukasQ mentioned this pull request Apr 10, 2026

Dependency on unmaintained libnacl causes issues for integrators threema-ch/threema-msgapi-sdk-python#75

Open

edenhaus requested changes Apr 10, 2026

View reviewed changes

Uh oh!

Conversation

LukasQ commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

My first core PR 🥳

Type of change

Additional information

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NoRi2909 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

joostlek left a comment

Choose a reason for hiding this comment

Uh oh!

home-assistant bot commented Mar 19, 2026

Uh oh!

LukasQ commented Mar 19, 2026

Uh oh!

joostlek commented Mar 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

LukasQ commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joostlek commented Mar 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

joostlek commented Apr 10, 2026

LukasQ commented Mar 19, 2026 •

edited

Loading

LukasQ commented Mar 19, 2026 •

edited

Loading