status-im/logos-docs
1
0
Fork 0
mirror of https://github.com/status-im/logos-docs.git synced 2026-08-31 02:51:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
deploy-develop
logos-docs/messaging/chat-module/build-logos-module-that-uses-chat-module-api/index.html
T
status-im-auto 077b79eb9f Update documentation
2026-07-26 05:59:32 +00:00

168 lines
78 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html><html lang=en dir=ltr class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-messaging/chat-module/build-logos-module-that-uses-chat-module-api" data-has-hydrated=false><head><meta charset=UTF-8><meta name=generator content="Docusaurus v3.10.2"><title data-rh=true>Build a Logos module that uses the Chat module API | Logos documentation</title><meta data-rh=true name=viewport content="width=device-width, initial-scale=1.0"/><meta data-rh=true name=twitter:card content=summary_large_image /><meta data-rh=true property=og:image content=https://docs.logos.co/img/social-card.jpg /><meta data-rh=true name=twitter:image content=https://docs.logos.co/img/social-card.jpg /><meta data-rh=true property=og:url content=https://docs.logos.co/messaging/chat-module/build-logos-module-that-uses-chat-module-api /><meta data-rh=true property=og:locale content=en /><meta data-rh=true name=docusaurus_locale content=en /><meta data-rh=true name=docsearch:language content=en /><meta data-rh=true name=docusaurus_version content=current /><meta data-rh=true name=docusaurus_tag content=docs-default-current /><meta data-rh=true name=docsearch:version content=current /><meta data-rh=true name=docsearch:docusaurus_tag content=docs-default-current /><meta data-rh=true property=og:title content="Build a Logos module that uses the Chat module API | Logos documentation"/><meta data-rh=true name=description content="Get started with private 1:1 end-to-end encrypted messaging in your own Logos module."/><meta data-rh=true property=og:description content="Get started with private 1:1 end-to-end encrypted messaging in your own Logos module."/><link data-rh=true rel=icon href=/img/favicon.png /><link data-rh=true rel=canonical href=https://docs.logos.co/messaging/chat-module/build-logos-module-that-uses-chat-module-api /><link data-rh=true rel=alternate href=https://docs.logos.co/messaging/chat-module/build-logos-module-that-uses-chat-module-api hreflang=en /><link data-rh=true rel=alternate href=https://docs.logos.co/messaging/chat-module/build-logos-module-that-uses-chat-module-api hreflang=x-default /><script data-rh=true type=application/ld+json>{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://docs.logos.co/messaging/chat-module/build-logos-module-that-uses-chat-module-api","name":"Build a Logos module that uses the Chat module API","position":1}]}</script><link rel=icon href=/img/favicon.png media="(prefers-color-scheme: light)"><link rel=icon href=/img/favicon-dark.png media="(prefers-color-scheme: dark)"><link rel=stylesheet href=/assets/css/styles.e45c7411.css /><script src=/assets/js/runtime~main.ea6c7eaa.js defer></script><script src=/assets/js/main.78385118.js defer></script></head><body><svg style="display: none;"><defs>
<symbol id=theme-svg-external-link viewBox="0 0 24 24"><path fill=currentColor d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
</defs></svg>
<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme-597")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||(window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light")),document.documentElement.setAttribute("data-theme-choice",t||"system")}(),function(){try{for(var[t,e]of new URLSearchParams(window.location.search).entries())if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id=__docusaurus><link rel=preload as=image href=/img/logo-light.png /><link rel=preload as=image href=/img/logo-dark.png /><div role=region aria-label="Skip to main content"><a class=skipToContent_fXgn href=#__docusaurus_skipToContent_fallback>Skip to main content</a></div><nav aria-label=Main class="theme-layout-navbar navbar navbar--fixed-top"><div class=navbar__inner><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded=false class="navbar__toggle clean-btn" type=button><svg width=30 height=30 viewBox="0 0 30 30" aria-hidden=true><path stroke=currentColor stroke-linecap=round stroke-miterlimit=10 stroke-width=2 d="M4 7h22M4 15h22M4 23h22"/></svg></button><a class=navbar__brand href=/><div class=navbar__logo><img src=/img/logo-light.png alt=Logos class="themedComponent_mlkZ themedComponent--light_NVdE"/><img src=/img/logo-dark.png alt=Logos class="themedComponent_mlkZ themedComponent--dark_xIcU"/></div></a><a class="navbar__item navbar__link" href=/get-started/what-is-logos>Get started</a><div class="navbar__item dropdown dropdown--hoverable"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link>Your path</a><ul class=dropdown__menu><li><a class=dropdown__link href=/run-an-app>Run an app</a><li><a class=dropdown__link href=/run-a-node/get-started/run-logos-node-blockchain-storage-delivery>Run a node</a><li><a class=dropdown__link href=/build-an-app>Build an app</a><li><a class=dropdown__link href=/contribute/welcome>Contribute</a></ul></div><div class="navbar__item dropdown dropdown--hoverable"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link>Explore</a><ul class=dropdown__menu><li><a class=dropdown__link href=/basecamp/get-started/install-logos-basecamp>Basecamp</a><li><a class=dropdown__link href=/blockchain/get-started/introduction-to-the-logos-blockchain>Blockchain</a><li><a class=dropdown__link href=/lez/get-started/introduction-to-the-logos-execution-zone>LEZ</a><li><a class=dropdown__link href=/core/build-modules/start-a-logos-module-from-the-cli>Core</a><li><a aria-current=page class="dropdown__link dropdown__link--active" href=/messaging/get-started/introduction-to-logos-messaging>Messaging</a><li><a class=dropdown__link href=/storage/get-started/run-logos-storage-node>Storage</a><li><a class=dropdown__link href=/mixnet/get-started/discover-nodes-and-send-messages-via-the-anoncomms-mixnet-demo-app>Mixnet</a><li><a class=dropdown__link href=/peer-discovery/welcome>Peer discovery</a></ul></div></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><a href=https://github.com/logos-co/logos-docs target=_blank rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type=button disabled title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill=currentColor d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill=currentColor d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill=currentColor d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"/></svg></button></div><div class=navbarSearchContainer_Bca1></div></div></div><div role=presentation class=navbar-sidebar__backdrop></div></nav><div id=__docusaurus_skipToContent_fallback class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class=docsWrapper_hBAB><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type=button></button><div class=docRoot_UBD9><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class=sidebarViewport_aRkj><div class=sidebar_njMd><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=false href=/messaging/get-started/introduction-to-logos-messaging><span class=categoryLinkLabel_W154>Get started</span></a></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=false href=/messaging/delivery/use-logos-delivery-module-api-from-app><span class=categoryLinkLabel_W154>Delivery module</span></a></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role=button aria-expanded=false href=/messaging/concepts/protocols><span class=categoryLinkLabel_W154>Concepts</span></a></div><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class=menu__list-item-collapsible><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role=button aria-expanded=true href=/messaging/chat-module/build-logos-module-that-uses-chat-module-api><span class=categoryLinkLabel_W154>Chat module</span></a></div><ul class=menu__list><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current=page tabindex=0 href=/messaging/chat-module/build-logos-module-that-uses-chat-module-api><span class=linkLabel_WmDU>Build a Logos module that uses the Chat module API</span></a><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class=menu__link tabindex=0 href=/messaging/chat-module/send-anonymised-messages-over-the-mix-network><span class=linkLabel_WmDU>Send anonymised messages over the mix network</span></a></ul></ul></nav></div></div></aside><main class=docMainContainer_TBSr><div class="container padding-top--md padding-bottom--lg"><div class=row><div class="col docItemCol_VOVn"><div class=docItemContainer_Djhp><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label=Breadcrumbs><ul class=breadcrumbs><li class=breadcrumbs__item><a aria-label="Home page" class=breadcrumbs__link href=/><svg viewBox="0 0 24 24" class=breadcrumbHomeIcon_YNFT><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill=currentColor /></svg></a><li class=breadcrumbs__item><span class=breadcrumbs__link>Chat module</span><li class="breadcrumbs__item breadcrumbs__item--active"><span class=breadcrumbs__link>Build a Logos module that uses the Chat module API</span></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type=button class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Build a Logos module that uses the Chat module API</h1></header>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=get-started-with-private-11-end-to-end-encrypted-messaging-in-your-own-logos-module>Get started with private 1:1 end-to-end encrypted messaging in your own Logos module.<a href=#get-started-with-private-11-end-to-end-encrypted-messaging-in-your-own-logos-module class=hash-link aria-label="Direct link to Get started with private 1:1 end-to-end encrypted messaging in your own Logos module." title="Direct link to Get started with private 1:1 end-to-end encrypted messaging in your own Logos module." translate=no>​</a></h4>
<p>This procedure covers how to build a Logos <a href=https://docs.logos.co/get-started/glossary#module target=_blank rel="noopener noreferrer" class="">module</a> that calls the <a href=https://github.com/logos-co/logos-chat-module target=_blank rel="noopener noreferrer" class="">logos-chat-module</a> API (tag <code>v0.1.2</code>) to exchange introduction bundles, open private 1:1 conversations, and send and receive end-to-end encrypted messages on the Logos network. It is intended for application developers who want to integrate private messaging without taking direct dependencies on <code>liblogoschat</code> or <code>logos-delivery</code>.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 14 16"><path fill-rule=evenodd d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"/></svg></span>info</div><div class=admonitionContent_BuS1><p>Identity, conversations, and message history persist in the instance directory you pass to <code>init()</code> (<code>identity.db</code> + <code>history.json</code>). Restarting an instance against the same directory restores its identity and conversations.</div></div>
<p>Before you start, make sure you have the following:</p>
<ul>
<li class="">
<p>Linux or macOS</p>
</li>
<li class="">
<p><strong>Nix</strong> with flakes enabled. Install from <a href=https://nixos.org/download.html target=_blank rel="noopener noreferrer" class="">nixos.org</a>, then enable flakes:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">mkdir -p ~/.config/nix</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Network access so that two instances can reach each other</p>
</li>
<li class="">
<p>An understanding of <a class="" href=/core/build-modules/build-a-logos-cpp-ui-module>Logos modules</a></p>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=what-to-expect>What to expect<a href=#what-to-expect class=hash-link aria-label="Direct link to What to expect" title="Direct link to What to expect" translate=no>​</a></h2>
<ul>
<li class="">You can initialise a chat client, connect to the Logos network, and exchange end-to-end encrypted messages with another instance.</li>
<li class="">You can open a private 1:1 conversation by exchanging introduction bundles <a href=https://docs.logos.co/get-started/glossary#out-of-band target=_blank rel="noopener noreferrer" class="">out of band</a> and calling <code>create_conversation</code> from the initiating side.</li>
<li class="">You can integrate the full chat lifecycle — init, subscribe to events, create bundle, open conversation, send, shut down — into any Logos C++ module.</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=step-1-scaffold-a-new-logos-module>Step 1: Scaffold a new Logos module<a href=#step-1-scaffold-a-new-logos-module class=hash-link aria-label="Direct link to Step 1: Scaffold a new Logos module" title="Direct link to Step 1: Scaffold a new Logos module" translate=no>​</a></h2>
<p>Scaffold a new module using <a href=https://github.com/logos-co/logos-module-builder target=_blank rel="noopener noreferrer" class=""><code>logos-module-builder</code></a>. For a full walkthrough, see the <a class="" href=/core/build-modules/build-a-logos-cpp-ui-module>Build a Logos C++ UI module</a> tutorial.</p>
<ol>
<li class="">
<p>Create and enter the project directory:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">mkdir your-module-name && cd your-module-name</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Initialise from the template:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">nix flake init -t github:logos-co/logos-module-builder/tutorial-v3#ui-qml-backend</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Initialise a Git repository and stage all generated files:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">git init && git add -A</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Keep the generated files — you build on them, you don't delete them. The template is a working <code>ui_example</code> module. Its main files are:</p>
<table><thead><tr><th>File<th>What it is<th>Can you edit it?<tbody><tr><td><code>src/ui_example_plugin.{h,cpp}</code><td>The C++ plugin<td>Yes — your chat code goes here (Steps 3–4)<tr><td><code>src/ui_example.rep</code>, <code>src/ui_example_interface.h</code><td>The module's interface<td>No<tr><td><code>src/qml/Main.qml</code><td>The example view<td>Later — replace with your own UI<tr><td><code>metadata.json</code>, <code>CMakeLists.txt</code><td>Build config<td>Step 2 only</table>
<p>You add your chat code in <code>UiExamplePlugin::initLogos()</code>. Leave the example <code>status</code> / <code>add</code> UI as is for now.</p>
</li>
</ol>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 14 16"><path fill-rule=evenodd d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"/></svg></span>info</div><div class=admonitionContent_BuS1><p>Keep the module named <code>ui_example</code>. The name is referenced in <code>metadata.json</code>, <code>CMakeLists.txt</code>, the <code>src/ui_example*</code> files, and <code>Main.qml</code> (<code>logos.module("ui_example")</code>) — they must all match, or <code>nix build</code> fails. To use a different name, change it in every one of these.</div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=step-2-declare-chat_module-as-a-dependency>Step 2: Declare <code>chat_module</code> as a dependency<a href=#step-2-declare-chat_module-as-a-dependency class=hash-link aria-label="Direct link to step-2-declare-chat_module-as-a-dependency" title="Direct link to step-2-declare-chat_module-as-a-dependency" translate=no>​</a></h2>
<p>Add <code>chat_module</code> to both <code>metadata.json</code> and <code>flake.nix</code>, pinning to the released tag so your app stays stable as the module's API evolves.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 14 16"><path fill-rule=evenodd d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"/></svg></span>info</div><div class=admonitionContent_BuS1><p>The flake input name (<code>chat_module</code>) must match the dependency name in <code>metadata.json</code>. <code>logos-module-builder</code> automatically generates the typed <code>chat_module</code> wrapper at build time.</div></div>
<ol>
<li class="">
<p>In <code>metadata.json</code>, add <code>chat_module</code> and <code>delivery_module</code> to the dependencies array and reuse <code>chat_module</code>'s bundled <code>delivery_module</code> contract:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-json codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"name"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"ui_example"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"dependencies"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token string" style=color:#e3116c>"chat_module"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"delivery_module"</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"dependency_overrides"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"delivery_module"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"input"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"chat_module"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"file"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"rust-lib/deps/delivery_module.lidl"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> ...</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>In <code>flake.nix</code>, pin <code>chat_module</code> and its <a href=https://docs.logos.co/get-started/glossary#transport target=_blank rel="noopener noreferrer" class="">transport</a> dependency <code>delivery_module</code>, then map the delivery input to the <code>delivery_module</code> dependency so the builder can resolve its runtime:</p>
<div class="language-nix codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-nix codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">inputs = {</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> logos-module-builder.url = "github:logos-co/logos-module-builder";</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> # Pin chat_module to the released tag so its API can't shift under `nix flake update`.</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> chat_module.url = "github:logos-co/logos-chat-module/v0.1.2";</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> # chat_module reaches delivery over IPC, but the builder still needs delivery's</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> # runtime build from a matching flake input. Pin the v0.1.3 tag: it carries the</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> # zerokit/RLN nix-build fix that earlier delivery tags (≤ v0.1.2) lack.</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> logos-delivery-module.url = "github:logos-co/logos-delivery-module/v0.1.3";</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">};</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">outputs = inputs@{ logos-module-builder, logos-delivery-module, ... }:</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> logos-module-builder.lib.mkLogosQmlModule {</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> src = ./.;</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> configFile = ./metadata.json;</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> # Map the delivery input to the `delivery_module` dependency name.</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> flakeInputs = { delivery_module = logos-delivery-module; } // inputs;</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> };</span><br/></div></code></pre></div></div>
</li>
</ol>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 14 16"><path fill-rule=evenodd d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"/></svg></span>info</div><div class=admonitionContent_BuS1><p>The <code>dependency_overrides</code> entry above only points the builder at delivery's <code>.lidl</code> contract for code generation — it does <strong>not</strong> supply delivery's runtime build. The builder resolves each <code>metadata.json</code> dependency's runtime from a matching flake input, so <code>delivery_module</code> needs the <code>logos-delivery-module</code> input, mapped in via <code>flakeInputs</code>. Without it, <code>nix build</code> cannot resolve <code>delivery_module</code>. This mirrors how <a href=https://github.com/logos-co/logos-chat-ui/blob/v0.1.2/flake.nix target=_blank rel="noopener noreferrer" class=""><code>logos-chat-ui</code></a> wires the two modules together.</div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=step-3-initialise-logosmodules-and-subscribe-to-events>Step 3: Initialise <code>LogosModules</code> and subscribe to events<a href=#step-3-initialise-logosmodules-and-subscribe-to-events class=hash-link aria-label="Direct link to step-3-initialise-logosmodules-and-subscribe-to-events" title="Direct link to step-3-initialise-logosmodules-and-subscribe-to-events" translate=no>​</a></h2>
<p>In your module's <code>initLogos()</code> function, construct <code>LogosModules</code> with the provided <code>LogosAPI*</code> and subscribe to all push events before calling <code>init()</code>. Subscribing first ensures you do not miss early events or the first incoming messages.</p>
<ol>
<li class="">
<p>Add the <code>LogosModules</code> member, then construct it in <code>initLogos()</code>.</p>
<p>In the header <code>src/ui_example_plugin.h</code> — add the include and the member:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token macro property directive-hash" style=color:#36acaa>#</span><span class="token macro property directive keyword" style=color:#00009f>include</span><span class="token macro property" style=color:#36acaa> </span><span class="token macro property string" style=color:#e3116c>"logos_sdk.h"</span><span class="token macro property" style=color:#36acaa> </span><span class="token macro property comment" style=color:#999988;font-style:italic>// generated umbrella — exposes LogosModules</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// inside the UiExamplePlugin class:</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">LogosModules</span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> m_logos </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>nullptr</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div>
<p>In <code>src/ui_example_plugin.cpp</code> — construct it:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>void</span><span class="token plain"> </span><span class="token class-name">UiExamplePlugin</span><span class="token double-colon punctuation" style=color:#393A34>::</span><span class="token function" style=color:#d73a49>initLogos</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">LogosAPI</span><span class="token operator" style=color:#393A34>*</span><span class="token plain"> api</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> logosAPI </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> api</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// keep the scaffold's two existing lines</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token function" style=color:#d73a49>setBackend</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>this</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> m_logos </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token keyword" style=color:#00009f>new</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>LogosModules</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">api</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Use m_logos->chat_module to call the Logos Chat module.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Subscribe to the module's push events. Each handler receives the event's positional arguments in the order declared in <code>chat_module.lidl</code>:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>auto</span><span class="token operator" style=color:#393A34>&</span><span class="token plain"> chat </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// A new message arrived in a conversation.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">chat</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>on</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"message_received"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList</span><span class="token operator" style=color:#393A34>&</span><span class="token plain"> a</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// a[0]: QString convo_id, a[1]: QString content, a[2]: qint64 timestamp_ms</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// One of your own messages was recorded/sent.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">chat</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>on</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"message_sent"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList</span><span class="token operator" style=color:#393A34>&</span><span class="token plain"> a</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// a[0]: convo_id, a[1]: content, a[2]: timestamp_ms</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// A conversation was created — incoming from a peer, or your own outgoing one.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">chat</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>on</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"conversation_created"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList</span><span class="token operator" style=color:#393A34>&</span><span class="token plain"> a</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// a[0]: QString convo_id, a[1]: bool is_outgoing, a[2]: QString peer_label</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">chat</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>on</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"conversation_updated"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList</span><span class="token operator" style=color:#393A34>&</span><span class="token plain"> a</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>/* a[0]: convo_id */</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">chat</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>on</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"conversation_deleted"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList</span><span class="token operator" style=color:#393A34>&</span><span class="token plain"> a</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>/* a[0]: convo_id */</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Delivery/connection state changed — drives your "connected" indicator.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">chat</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>on</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"delivery_state_changed"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>(</span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList</span><span class="token operator" style=color:#393A34>&</span><span class="token plain"> a</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// a[0]: QString delivery_state ("initialising" | "online" | "stopped" | "error")</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// a[1]: QString detail</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div>
<p>See <a href=https://github.com/logos-co/logos-chat-module/blob/v0.1.2/rust-lib/chat_module.lidl target=_blank rel="noopener noreferrer" class=""><code>rust-lib/chat_module.lidl</code></a> for the exact argument list of every method and event.</p>
</li>
</ol>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=step-4-drive-the-chat-lifecycle>Step 4: Drive the chat lifecycle<a href=#step-4-drive-the-chat-lifecycle class=hash-link aria-label="Direct link to Step 4: Drive the chat lifecycle" title="Direct link to Step 4: Drive the chat lifecycle" translate=no>​</a></h2>
<p>Status-bearing methods return their result <strong>synchronously</strong> as a <code>LogosResult</code>.</p>
<ul>
<li class=""><code>res.success</code> tells you whether the call succeeded;</li>
<li class=""><code>res.getError&lt;QString>()</code> carries the failure reason;</li>
<li class=""><code>res.getValue&lt;QString>()</code> carries the returned value (for example, the intro bundle).</li>
</ul>
<p>Ongoing activity — incoming messages, new conversations, delivery-state changes — arrives <strong>asynchronously</strong> through the push events you subscribed to in Step 3.</p>
<div class="theme-admonition theme-admonition-info admonition_xJq3 alert alert--info"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 14 16"><path fill-rule=evenodd d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"/></svg></span>info</div><div class=admonitionContent_BuS1><p><code>init()</code> starts delivery asynchronously, so the client is not connected the moment <code>init()</code> returns. Watch <code>delivery_state_changed</code> for the <code>online</code> state before creating conversations or sending messages.</div></div>
<p><code>init()</code> takes the instance directory, a delivery preset, and a TCP port:</p>
<table><thead><tr><th>Parameter<th>Type<th>Notes<tbody><tr><td><code>instance_path</code><td>string<td>Directory for this instance's persistent state. Use a distinct directory per instance to run several side by side.<tr><td><code>delivery_preset</code><td>string<td>Network preset for the delivery node. Use <code>logos.test</code> to reach the Logos test network. Must match across all participants.<tr><td><code>tcp_port</code><td>int<td><a href=https://docs.logos.co/get-started/glossary#logos-delivery target=_blank rel="noopener noreferrer" class="">Logos Delivery</a> TCP port. <code>0</code> picks a random port.</table>
<ol>
<li class="">
<p>Initialise the chat client:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QString dir </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>qEnvironmentVariable</span><span class="token punctuation" style=color:#393A34>(</span><span class="token string" style=color:#e3116c>"CHAT_INSTANCE_DIR"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"/tmp/chat-instance"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> LogosResult res </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>init</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">dir</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"logos.test"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token operator" style=color:#393A34>!</span><span class="token plain">res</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">success</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token function" style=color:#d73a49>qWarning</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>&lt;&lt;</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"init failed:"</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>&lt;&lt;</span><span class="token plain"> res</span><span class="token punctuation" style=color:#393A34>.</span><span class="token generic-function function" style=color:#d73a49>getError</span><span class="token generic-function generic class-name operator" style=color:#393A34>&lt;</span><span class="token generic-function generic class-name">QString</span><span class="token generic-function generic class-name operator" style=color:#393A34>></span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>return</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// init succeeded; delivery connects asynchronously.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Wait for delivery_state_changed with state == "online" before creating conversations.</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Read (or set) your identity:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QString myId </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>get_installation_name</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// Optionally choose a name: m_logos->chat_module.set_installation_name("alice");</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Create and share your introduction bundle:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> LogosResult bundle </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>create_intro_bundle</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>if</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">bundle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token plain">success</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QString myBundle </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> bundle</span><span class="token punctuation" style=color:#393A34>.</span><span class="token generic-function function" style=color:#d73a49>getValue</span><span class="token generic-function generic class-name operator" style=color:#393A34>&lt;</span><span class="token generic-function generic class-name">QString</span><span class="token generic-function generic class-name operator" style=color:#393A34>></span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// share `myBundle` out of band (the recipient pastes it — see Step 6)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div>
<div class="theme-admonition theme-admonition-warning admonition_xJq3 alert alert--warning"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 16 16"><path fill-rule=evenodd d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"/></svg></span>warning</div></div>
</li>
</ol>
<p>Each introduction bundle is <strong>single-use</strong> — it can open exactly one conversation. Generate a fresh bundle with <code>create_intro_bundle()</code> for every new contact you want to be able to reach you.
:::</p>
<ol start=4>
<li class="">
<p>Open a private conversation as the initiator, or receive one as the recipient:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// content is plain text — no encoding required.</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> LogosResult res </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>create_conversation</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">peerBundle</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"Hello!"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// On success a conversation_created event (is_outgoing == true) fires with the new convo_id.</span><br/></div></code></pre></div></div>
<ul>
<li class="">The initiator calls <code>create_conversation</code> with the peer's intro bundle and a plain-text opening message.</li>
<li class="">The recipient does not call anything; a <code>conversation_created</code> push event arrives automatically, followed by a <code>message_received</code> event.</li>
</ul>
</li>
<li class="">
<p>Send and receive messages:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>send_message</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">convoId</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"How are you?"</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// On success a message_sent event fires locally; the peer receives a message_received event.</span><br/></div></code></pre></div></div>
<ul>
<li class="">Message content is plain text in both directions — the module handles encoding and end-to-end encryption on the wire.</li>
</ul>
</li>
<li class="">
<p>Read history and conversation state at any time (synchronous reads):</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList convos </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>list_conversations</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// [Conversation]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantList msgs </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>get_messages</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">convoId</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// [Message]</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token keyword" style=color:#00009f>const</span><span class="token plain"> QVariantMap st </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>status</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>toMap</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// { convo_count, delivery_state, detail }</span><br/></div></code></pre></div></div>
<div class="theme-admonition theme-admonition-warning admonition_xJq3 alert alert--warning"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 16 16"><path fill-rule=evenodd d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"/></svg></span>warning</div></div>
</li>
</ol>
<p>Do not make a synchronous module read (<code>list_conversations</code>, <code>get_messages</code>, <code>status</code>) from <em>inside</em> an event handler — it re-enters the IPC replica while its read notifier is disabled and stalls until the call times out. Defer the read to the next event-loop turn instead (see <code>deferToEventLoop</code> in <a href=https://github.com/logos-co/logos-chat-ui/blob/v0.1.2/src/ChatBackend.cpp target=_blank rel="noopener noreferrer" class=""><code>logos-chat-ui</code></a>).
:::</p>
<ol start=7>
<li class="">
<p>Shut down cleanly:</p>
<div class="language-cpp codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-cpp codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">m_logos</span><span class="token operator" style=color:#393A34>-></span><span class="token plain">chat_module</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>shutdown</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// disconnects and tears the client down</span><br/></div></code></pre></div></div>
</li>
</ol>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=step-5-build-and-run>Step 5: Build and run<a href=#step-5-build-and-run class=hash-link aria-label="Direct link to Step 5: Build and run" title="Direct link to Step 5: Build and run" translate=no>​</a></h2>
<ol>
<li class="">
<p>Build the module:</p>
<div class="language-sh codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-sh codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">nix build</span><br/></div></code></pre></div></div>
</li>
<li class="">
<p>Preview the module using <code>logos-standalone-app</code> (for <code>ui_qml</code> modules):</p>
<div class="language-sh codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-sh codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">nix run # preview via logos-standalone-app (for ui_qml modules)</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">nix build .#lgx # package as .lgx for installation into logos-basecamp</span><br/></div></code></pre></div></div>
</li>
</ol>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=step-6-verify-a-two-instance-exchange>Step 6: Verify a two-instance exchange<a href=#step-6-verify-a-two-instance-exchange class=hash-link aria-label="Direct link to Step 6: Verify a two-instance exchange" title="Direct link to Step 6: Verify a two-instance exchange" translate=no>​</a></h2>
<p>A chat is only proven end to end when a message travels between two running instances. Start two copies of your module — each with its own <code>instance_path</code> and <code>tcp_port</code> — and confirm a message lands as a <code>message_received</code> event.</p>
<ol>
<li class="">Start both instances and wait until each reports <code>delivery_state == "online"</code> via <code>delivery_state_changed</code>.</li>
<li class="">In instance A, call <code>create_intro_bundle()</code> and share the returned bundle out of band (copy it into instance B).</li>
<li class="">In instance B, call <code>create_conversation(bundleFromA, "Hello from B")</code>. Instance A receives a <code>conversation_created</code> event (<code>is_outgoing == false</code>) followed by a <code>message_received</code> event carrying <code>"Hello from B"</code>.</li>
<li class="">In instance A, reply with <code>send_message(convoId, "Hi B")</code>. Instance B receives the matching <code>message_received</code> event.</li>
</ol>
<p>Seeing the <code>message_received</code> events on both sides confirms the full round trip: identity, intro-bundle exchange, conversation setup, and end-to-end encrypted delivery.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=troubleshooting-the-logos-chat-module>Troubleshooting the Logos Chat module<a href=#troubleshooting-the-logos-chat-module class=hash-link aria-label="Direct link to Troubleshooting the Logos Chat module" title="Direct link to Troubleshooting the Logos Chat module" translate=no>​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=why-does-a-method-fail>Why does a method fail?<a href=#why-does-a-method-fail class=hash-link aria-label="Direct link to Why does a method fail?" title="Direct link to Why does a method fail?" translate=no>​</a></h3>
<p>The method returns a <code>LogosResult</code> with <code>success == false</code> and a reason in <code>getError&lt;QString>()</code>. The most common cause is calling a conversation or message method before <code>init()</code> succeeded, or before delivery reached the <code>online</code> state. Call <code>init()</code> first, check <code>res.success</code>, and wait for a <code>delivery_state_changed</code> event with <code>delivery_state == "online"</code> before creating conversations or sending messages.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=why-do-peers-not-connect-or-messages-not-propagate>Why do peers not connect or messages not propagate?<a href=#why-do-peers-not-connect-or-messages-not-propagate class=hash-link aria-label="Direct link to Why do peers not connect or messages not propagate?" title="Direct link to Why do peers not connect or messages not propagate?" translate=no>​</a></h3>
<p>The <code>delivery_preset</code> differs across instances, or delivery has not reached <code>online</code>. All participants must use the same preset (for example <code>logos.test</code>) to share a network, and each instance must report <code>online</code> via <code>delivery_state_changed</code> (or <code>status()</code>) before it can exchange messages.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=why-does-a-read-stall-the-ui>Why does a read stall the UI?<a href=#why-does-a-read-stall-the-ui class=hash-link aria-label="Direct link to Why does a read stall the UI?" title="Direct link to Why does a read stall the UI?" translate=no>​</a></h3>
<p>You issued a synchronous module read (<code>list_conversations</code>, <code>get_messages</code>, <code>status</code>) from inside an event handler. That re-enters the IPC replica while its read notifier is disabled and blocks until the call times out. Defer such reads to the next event-loop turn.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=why-is-a-previously-created-conversation-still-there-after-a-restart>Why is a previously created conversation still there after a restart?<a href=#why-is-a-previously-created-conversation-still-there-after-a-restart class=hash-link aria-label="Direct link to Why is a previously created conversation still there after a restart?" title="Direct link to Why is a previously created conversation still there after a restart?" translate=no>​</a></h3>
<p>Chat state is <strong>persistent</strong>. Identity and history live in the instance directory passed to <code>init()</code> (<code>identity.db</code>, <code>history.json</code>), so restarting against the same directory restores conversations and your identity. Point <code>init()</code> at a fresh directory to start from a clean state.</div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href=https://github.com/logos-co/logos-docs/tree/main/docs/messaging/chat-module/build-logos-module-that-uses-chat-module-api.md target=_blank rel="noopener noreferrer" class=theme-edit-this-page><svg fill=currentColor height=20 width=20 viewBox="0 0 40 40" class=iconEdit_Z9Sw aria-hidden=true><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"/></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href=/messaging/concepts/logos-delivery-and-libp2p><div class=pagination-nav__sublabel>Previous</div><div class=pagination-nav__label>Learn the differences between Logos Delivery and libp2p</div></a><a class="pagination-nav__link pagination-nav__link--next" href=/messaging/chat-module/send-anonymised-messages-over-the-mix-network><div class=pagination-nav__sublabel>Next</div><div class=pagination-nav__label>Send anonymised messages over the mix network</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href=#what-to-expect class="table-of-contents__link toc-highlight">What to expect</a><li><a href=#step-1-scaffold-a-new-logos-module class="table-of-contents__link toc-highlight">Step 1: Scaffold a new Logos module</a><li><a href=#step-2-declare-chat_module-as-a-dependency class="table-of-contents__link toc-highlight">Step 2: Declare <code>chat_module</code> as a dependency</a><li><a href=#step-3-initialise-logosmodules-and-subscribe-to-events class="table-of-contents__link toc-highlight">Step 3: Initialise <code>LogosModules</code> and subscribe to events</a><li><a href=#step-4-drive-the-chat-lifecycle class="table-of-contents__link toc-highlight">Step 4: Drive the chat lifecycle</a><li><a href=#step-5-build-and-run class="table-of-contents__link toc-highlight">Step 5: Build and run</a><li><a href=#step-6-verify-a-two-instance-exchange class="table-of-contents__link toc-highlight">Step 6: Verify a two-instance exchange</a><li><a href=#troubleshooting-the-logos-chat-module class="table-of-contents__link toc-highlight">Troubleshooting the Logos Chat module</a><ul><li><a href=#why-does-a-method-fail class="table-of-contents__link toc-highlight">Why does a method fail?</a><li><a href=#why-do-peers-not-connect-or-messages-not-propagate class="table-of-contents__link toc-highlight">Why do peers not connect or messages not propagate?</a><li><a href=#why-does-a-read-stall-the-ui class="table-of-contents__link toc-highlight">Why does a read stall the UI?</a><li><a href=#why-is-a-previously-created-conversation-still-there-after-a-restart class="table-of-contents__link toc-highlight">Why is a previously created conversation still there after a restart?</a></ul></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Docs</div><ul class="footer__items clean-list"><li class=footer__item><a class=footer__link-item href=/get-started/what-is-logos>Get started</a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Community</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://github.com/logos-co/logos-docs target=_blank rel="noopener noreferrer" class=footer__link-item>GitHub<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div></div><div class="footer__bottom text--center"><div class=footer__copyright>Copyright © 2026 Logos. Built with Docusaurus.</div></div></div></footer></div></body>
Reference in New Issue View Git Blame Copy Permalink