Channel-Squad Mapping¶

Channel-Squad Mapping connects incoming messages from external channels (Telegram, Slack, Discord, WhatsApp) to specific Squad container groups. Each chat conversation (JID) is mapped to a group namespace, and messages are routed to the correct group's container session.

How Routing Works¶

flowchart TD
    MSG["Incoming Message\n(chat_jid, sender, content)"]
    AL[Sender Allowlist Check]
    JID["Look up chat_jid\nin group namespace table"]
    GRP[Target Group]
    CONT["Container Session\n(group/session_dir)"]
    RESP[Agent Response]
    CHAN[Send back via channel]

    MSG --> AL
    AL -- allowed --> JID
    AL -- blocked --> DROP[Drop message]
    JID -- found --> GRP
    JID -- not found --> DEFAULT[Use default group or ignore]
    GRP --> CONT
    CONT --> RESP
    RESP --> CHAN

Each message is routed using its chat JID — a unique identifier combining the channel name and chat identifier (e.g., tg:123456789, slack:C01234567).

Group Namespaces¶

A group namespace is a named, isolated context that:

• Has its own session directory (DATA_DIR/sessions/{group}/)
• Can have group-specific instructions (CLAUDE.md)
• Maintains conversation history per chat JID
• Receives messages from one or more mapped chat JIDs

Create a Group Namespace¶

In the squad wizard:

1. Go to the Workspace step of the Create Squad wizard.

2. Click Create New Group next to Group Namespace.

3. Enter a Group Name (e.g., telegram-support, dev-alerts).

4. Optionally add a Description.

5. Click Create New Group under the fields.

Via Management API:

curl -X POST http://localhost:8001/api/v1/container/namespaces \
  -H "Content-Type: application/json" \
  -d '{"name": "telegram-support", "description": "Customer support via Telegram"}'

List Group Namespaces¶

curl http://localhost:8001/api/v1/container/namespaces

Response:

[
  {
    "id": "a1b2c3d4-...",
    "name": "telegram-support",
    "description": "Customer support via Telegram",
    "createdAt": "2026-03-15T10:00:00Z",
    "updatedAt": "2026-03-15T10:00:00Z"
  }
]

Mapping Chat JIDs to Groups¶

The IPC permission model determines which group a container session belongs to. Container sessions inherit their group from the session directory name, which is set when the session is created via IPC.

Main vs. Normal Groups¶

Groups can be designated as main (privileged) or normal:

Only one group can be main at a time. The main group is used for administrative tasks and broadcasting.

IPC Directories¶

When a container session starts, IPC directories are created:

curl -X POST http://localhost:8001/api/v1/container/ipc/directories \
  -H "Content-Type: application/json" \
  -d '{"group": "telegram-support", "sessionId": "session-abc123"}'

This creates:

DATA_DIR/sessions/telegram-support/session-abc123/ipc/
├── input/     # host -> container messages
├── messages/  # container -> host send requests
└── tasks/     # container -> host task requests

Message Format for Squad Processing¶

When a message is routed to a Squad group, it is formatted as XML for the agent:

<external_message>
  <channel>telegram</channel>
  <chat_jid>tg:123456789</chat_jid>
  <sender>user_42</sender>
  <sender_name>Alice</sender_name>
  <content>Can you help me analyze this dataset?</content>
  <timestamp>1741968000</timestamp>
</external_message>

The agent processes this message and generates a reply. The reply is then stripped of any internal XML tags and sent back through the originating channel.

Setting Group Instructions¶

Group-specific instructions (the equivalent of a CLAUDE.md file) are injected into every container session for that group. This allows you to customize agent behavior per channel or use case.

Set Group Instructions¶

curl -X PUT http://localhost:8001/api/v1/container/namespaces/telegram-support/instructions \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You are a customer support agent for Acme Corp. Always be polite and concise. If you cannot resolve an issue, escalate to a human agent by saying [ESCALATE]."}'

Get Group Instructions¶

curl http://localhost:8001/api/v1/container/namespaces/telegram-support/instructions

Global Instructions¶

Global instructions apply to all groups and are merged with group-specific instructions:

# Get global instructions
curl http://localhost:8001/api/v1/container/namespaces/global/instructions

# Set global instructions
curl -X PUT http://localhost:8001/api/v1/container/namespaces/global/instructions \
  -H "Content-Type: application/json" \
  -d '{"instructions": "Always respond in the same language as the user. Be helpful and accurate."}'

Preview Merged Instructions¶

To see how global and group instructions are combined for a specific group:

curl -X POST http://localhost:8001/api/v1/container/namespaces/merge-instructions \
  -H "Content-Type: application/json" \
  -d '{"groupName": "telegram-support"}'

Example: Multi-Group Setup¶

Here's an example of routing different Telegram chats to different groups:

Telegram DM (tg:111)    → group: personal-assistant
Telegram Group (tg:222) → group: team-collaboration
Slack Channel (slack:C01) → group: code-review
Discord DM (discord:333) → group: personal-assistant

Configuration Steps¶

1. Create each group namespace.

2. Set group-specific instructions for each namespace.

3. Run squad container agents for each group (each group gets its own session).

4. Messages from each chat JID are automatically routed to their group's container session.

Troubleshooting¶

Messages are not being routed¶

• Verify the channel is connected: curl http://localhost:8001/api/v1/channels
• Check if the sender is blocked by the allowlist: curl http://localhost:8001/api/v1/channels/sender-allowlist
• Review the container audit log for routing errors: curl http://localhost:8001/api/v1/container/audit-log

Agent responds with the wrong context¶

• Check the merged instructions for the group to ensure they are correct
• Verify the session directory exists and has the correct group assignment

IPC communication fails¶

• Check the IPC directories exist: the session directory should contain ipc/input/, ipc/messages/, and ipc/tasks/
• Review the container logs in the run history
• Verify the container has the correct workspace mount