# intouch api
base    https://api.in-touch.cc
auth    X-API-Key: itk_<64 hex>   one key per user, no expiry, no scopes
docs    https://docs.in-touch.cc
format  every response is JSON and carries "success"

# embed
Put inTouch on any website with one tag. Public, no account, no key.

Script: https://web.in-touch.cc/embed.js
Studio: https://web.in-touch.cc/studio
Theme reference: https://docs.in-touch.cc/embed-theme.txt
Event/command API: https://docs.in-touch.cc/embed-api.txt

# quickstart
<script src="https://web.in-touch.cc/embed.js" async></script>

<intouch-chat style="height:620px">
  <script type="application/json">
  { "colorScheme": "light",
    "colors": { "accent": "#b4541f", "bubbleOut": "#b4541f", "panel": "#fffdf9" },
    "radius": { "bubble": 14 },
    "typography": { "fontFamily": "Georgia, serif" } }
  </script>
</intouch-chat>

# who
The VISITOR links their own account by QR and talks to their own contacts.
The embedding site is frame and design only. There is no mode in which the
site owner reads along.

# ways
1. Web component (default): readable theme, live updates, events, dark-mode sync.
2. Plain iframe: for CMSs that forbid <script>.
   <iframe src="https://web.in-touch.cc/embed?theme=<url-encoded json>"
           style="width:100%;height:620px;border:0"
           allow="camera; microphone; clipboard-write"></iframe>
3. Hosted theme id: <intouch-chat theme="t_9fb2c1a4e803"></intouch-chat>

# hosting
POST https://web.in-touch.cc/embed/theme  body: the theme JSON
-> { id, reused, bytes, url, snippet }
GET  https://web.in-touch.cc/embed/theme/<id>  -> the theme JSON, immutable, cacheable forever

The id is the first 12 hex characters of SHA-256 over the canonical JSON.
Same theme = same id. An id is never overwritten. No account needed.
Limits: 32 KB, 400 fields, 60 new themes per hour and IP.

# scope
Changeable: every visual property (159 documented fields) plus customCss.
NOT changeable: behaviour. No field removes a feature. An embedded chat can do
everything the full one can.
Layout options move elements, never orphan them: layout.rail "hidden" moves
theme switch, language and sign-out into the sidebar menu automatically.

# single
layout.mode = "conversation" shows ONE conversation instead of list + chat.
Which one: the visitor's last opened chat, else their most recent.
The chat list stays reachable through a button in the header - an embedded
chat never cuts the visitor off from their own conversations.

# peer
<intouch-chat peer="+4915112345678"> names the counterpart (phone number,
international form). The frame opens that conversation.

If the chat exists, it opens. If not, NOTHING is created: the visitor sees the
header, an empty history and a line naming who they are about to write to. The
chat is created when they SEND - never because a page loaded.

Resolving requires a linked session and is rate limited (an open lookup would
be a directory oracle). The embedding page is not told the outcome. On failure:
intouch:error with code "peer_not_found" or "peer_rate_limited", and the
visitor gets their normal chat list.

# privacy
The chat runs in an iframe on the inTouch origin. The visitor's session token
and private end-to-end key live in THAT origin, not in the embedding page.
A script-in-your-origin widget would expose both to the page and to any XSS
on it. That is why styling goes through the theme schema and not through your
CSS.

The embedding page learns exactly three things: that somebody is linked, how
many unread chats there are, and whether a chat is open. No names, no chat ids,
no message content. The list is exhaustive.

# trust
While the QR code is shown, the frame names the real domain the visitor is on.
Position and colour are configurable; presence is not. The domain is read from
the browser (location.ancestorOrigins), not from a parameter.

# abuse
The embed is public on purpose; a phishing site can put the real linking screen
into a convincing facade. Two defences:

1. The linking notice always names the domain the visitor is actually on, read
   from the browser. It cannot be removed; CSS that hides it costs the site its
   entire custom styling (the frame verifies visibility after applying).
2. A site can be blocked. Report it with the URL and a screenshot; the
   reporting address is set up before this goes public and will be named here.
   A blocked site gets no QR code - the frame shows an explanation
   and a way to open inTouch Web directly. Blocking is keyed to the embedding
   origin read from the browser, not from a header the site controls.

Blocking is a last resort, never a reaction to design. Themes are not moderated.

# storage
Browsers partition storage per embedding site.
  Chrome/Edge: partitioned, works. Linking applies per website.
  Firefox:     partitioned (dFPI), works.
  Safari:      partitioned, cleared after ~7 days idle -> occasional re-linking.
Not configurable away. If storage is unavailable the frame shows a button that
calls requestStorageAccess(); the page is told via intouch:error
{ code: "storage_blocked" }.

# pages
/                  overview, capability list
/quickstart        get a key, first request
/authentication    key format, rotation, failure modes
/conventions       envelope, status codes, limits, dates
/recipes           recipes capability
/vocabulary        vocabulary capability
/roadmap           capability anatomy, what is planned
every page is also plain text: append .txt  (e.g. https://docs.in-touch.cc/vocabulary.txt)
all pages at once: /llms.txt (index) and /llms-full.txt (everything)

# for agents
- Use only the endpoints listed here; do not invent paths, fields or values.
- Check "success" in the body, not just the HTTP status.
- Error strings are German and developer-facing; branch on the status code.
- Batches are accepted partially: read "rejected" and "errors[].index".
- Dates are UTC. Calendar days are YYYY-MM-DD, timestamps are ISO 8601.
- The API key is a credential: never log it, never pass it to a third party.
- Ask the user before writing content into their app for the first time.