Skip to content

Add team chat with translation

This guide gives your game a chat for a party or a match, with every message translated into each player's own language by Claude. It takes about 30 minutes, most of it one-time setup on the server.

Chat is a service otomo already runs: it stores a channel's messages, asks Session or the Matchmaker who is allowed in, and applies your rules (length, banned words, how fast a player may send). What this guide adds is the part a game client talks to, and the translation.

You'll need:

  • the SDK installed and the player signed in (Install the SDK);
  • for translation, an Anthropic API key, and access to the server's deploy/ folder.

What it is

A channel belongs to one party, one match, or the whole instance (global). A player reads and writes only the channels they belong to. A message is stored exactly as the sender wrote it; if translation is on, the server then asks Claude to translate it into your languages and stores those beside it. Each reader gets the text in their language, and can still see what was written.

 Player A (Japanese)                      otomo                          Player B (English)
 ───────────────────                      ─────                          ──────────────────
 SendAsync("ナイスゲーム")  ──────────▶  stored as written
                                          translated: en "good game", ...
                                                                  ◀────  feed: Text = "good game"
                                                                         Body = "ナイスゲーム"

The three routes

The SDK wraps these, but they are plain HTTP behind the gateway, under /api/player/chat/v1, with the player's access token (Authorization: Bearer ...). kind is party, match or global; for global the scope segment is -.

Read a channel, optionally as a long poll:

GET /api/player/chat/v1/channels/party/3f0c1a52-0f7e-4b6a-9a2e-5b8f0f0b8f21/messages?after=40&lang=en-US&wait=20&typing_tag=abc123
{"channel": "party:3f0c1a52-0f7e-4b6a-9a2e-5b8f0f0b8f21",
 "messages": [{"seq": 41, "sender": "9b2a7f30-2f5e-4d3a-8a41-6c9d0e1f2a3b", "body": "boa partida",
               "text": "good game", "lang": "en", "translated": true, "attachment": "",
               "sent_at": "2026-11-20T10:00:00Z"}],
 "typing": ["4c1d8e52-7a3b-4f6e-9d20-1b5a7c3e9f44"],
 "typing_tag": "d41d8cd98f00b204",
 "cursor": 41}

after is the last seq you have (cursor from the previous answer). Leave after out and you get the latest limit messages (default 50), which is what a client joining a busy channel wants; after=0 means from the beginning. lang is the reader's language; en-US and zh-Hans-CN are read as en and zh. wait (0 to 25 seconds) makes the server hold the request until a message arrives, someone starts or stops typing, or the time is up: send the previous typing_tag back with it, and loop. text is the translation for lang when there is one, and the original otherwise; translated says which.

Send a message:

POST /api/player/chat/v1/channels/party/3f0c1a52-0f7e-4b6a-9a2e-5b8f0f0b8f21/messages
{"body": "boa partida", "key": "8f6d0c2e-1b7a-4e53-9a41-2c5d7e9f0a13", "attachment": ""}

It answers 201 with {"message": {...}}. key is yours: send the same key again after a dropped connection and you get 200 with the message already stored, never a second one.

Typing: say the player is typing, or stopped:

POST /api/player/chat/v1/channels/party/3f0c1a52-0f7e-4b6a-9a2e-5b8f0f0b8f21/typing
{"typing": true}

204. It lasts about five seconds, so repeat it while the player types (at most about twice a second); sending a message clears it. Typing is the only thing chat keeps in Valkey and losing it costs nothing but the indicator.

Step 1: Publish the translation rules

Which languages to translate into, and what Claude should know about your game, is part of your game's policy: the translation block of the chat.rules document. Edit it as a config release (Instance policy seeds): Namespaces, chat.rules, edit the draft, add this block, Save draft, Create version, then compose and publish a release.

"translation": {
  "languages": ["en", "zh", "ja", "ko", "ms", "id", "es", "pt", "fr", "de"],
  "kinds": ["party", "match"],
  "context_messages": 12,
  "instructions": "Elemaniacs is a co-op wizard game. Keep player names, spell names and element names (Fire, Water, Nature) unchanged. Translate casually, as teammates talk."
}
  • languages are the targets, at most 16. Every one is Claude output on every message, so list the languages your players actually speak.
  • kinds limits translation to those channels. Leave it out to translate all three.
  • context_messages is how many earlier messages Claude sees to understand a reply ("yes" to what?). They are never translated themselves. 0 sends none.
  • instructions is yours: what the game is, which words to leave alone, the tone.

Without this block, messages are stored and shown as written.

Step 2: Turn team chat on, and the Claude engine

Team chat is off by default: until you opt in, the server starts no player listener and nothing about your instance changes. Both the listener and the engine are deployment choices, so they are in the server's environment, never in the document.

  1. In deploy/.env, turn the player listener on:

    CHAT_PLAYER_ADDR=:8080
    

    Players can use party and match channels. The global channel is not reachable until you add it with CHAT_PLAYER_KINDS=party,match,global: it is open to every signed-in player, its typing list shows every typer's id, and translating it is a paid call per message. Choose it deliberately.

  2. Put the API key in a file, and nothing else in it:

    cd deploy
    mkdir -p secrets/chat_translation
    printf '%s' 'sk-ant-...' > secrets/chat_translation/anthropic_api_key
    chmod 600 secrets/chat_translation/anthropic_api_key
    
  3. Also in deploy/.env:

    CHAT_TRANSLATION_PROVIDER=anthropic
    CHAT_TRANSLATION_MODEL=claude-sonnet-5-5
    CHAT_TRANSLATION_KEY_FILE=/run/secrets/chat_translation/anthropic_api_key
    
  4. Restart chat, from the repository root: docker compose --env-file deploy/.env -f deploy/compose.yaml up -d chat.

The model has no default: chat refuses to start without CHAT_TRANSLATION_MODEL. The gateway's chat upstream is already set in compose.yaml (a gateway without one answers 404 not_found for chat paths). Optional knobs: CHAT_PLAYER_HOLD (how long another player's message may wait for its translation, 2.5 s), CHAT_PLAYER_TYPING_TTL (5 s), CHAT_TRANSLATION_TIMEOUT and CHAT_TRANSLATION_MAX_OUTPUT_TOKENS (services/chat/README.md lists them all).

Privacy. With an engine on, the text of each message and the few messages before it (without player ids or names) are sent to the engine's operator, here Anthropic, to be translated. Say so in your game's privacy text.

Step 3: Show it in the game

using OtomoSdk.Chat;

public override void _Ready()
{
    // Opens a live feed of the party's channel in the player's language and starts it.
    Otomo.Instance.ChatMessageReceived += OnMessage;
    Otomo.Instance.ChatTypingChanged += OnTyping;
    Otomo.Instance.ChatFeedEnded += (channel, code) => GD.Print($"chat closed: {code}");
    _feed = Otomo.Instance.OpenChatFeed(ChatKind.Party, partyId, OS.GetLocale());   // "ja_JP" is read as "ja"
}

void OnMessage(string channel, long seq, string sender, string body, string text, string lang,
               bool translated, string attachment, long sentAtUnixMs)
{
    AddLine(sender, text);              // text is already in this player's language
    if (translated) ShowOriginalOnHover(body);
}

async void SendPressed(string line)
{
    try { await Otomo.Instance.Client.Chat.SendAsync(ChatKind.Party, partyId, line, Guid.NewGuid().ToString()); }
    catch (OtomoError e) { ShowWhy(e.Code); }   // too_long, refused_words, rate_limited, not_a_member ...
}

Call SetTypingAsync(ChatKind.Party, partyId, true) while the player types in the box. When the party changes or a match ends, await _feed.StopAsync() and open the next channel's feed; feeds also stop on logout. The SDK reference lists every member.

When translation does not work

A player never loses a message and never sees a half-translated one. The translation is a step after the message is stored, so any failure leaves the message as written:

What goes wrong What the player sees
Claude is slow, busy (429, 5xx) or unreachable The message arrives as written, after at most CHAT_PLAYER_HOLD (2.5 s); chat retries once first
Claude declines to translate it, or the answer is cut off or not usable The message as written
The key is wrong or revoked, or the model name is wrong Every message as written; chat logs the engine's refusal
The queue of messages waiting for Claude is full That message as written, at once
The message is only emoji, digits or punctuation As written: it is never sent to Claude
A language is not in languages, or the translation equals the original Text is Body, Translated is false
Valkey is down No "typing" indicator, and long polls re-read every few seconds; messages are unaffected
The player is not in the party or match not_a_member; the feed ends and raises ChatFeedEnded

A message another player wrote is held back for up to 2.5 seconds while its translation is pending (the sender shows as typing meanwhile), so the translated text normally arrives with the message; after that it is delivered as written and stays as written for that reader.

Sending can be refused, with a code the game can show: too_long, refused_words (the banned-word list), rate_limited (wait Retry-After seconds), empty_message, not_a_member, channel_expired (a quiet channel is deleted after its lifetime), not_configured (no chat.rules is published yet) and membership_unavailable (Session could not answer; try again).