Chat Interface Configuration Nuances¶
All chat adapters use the same gateway bridge and session model, but each
provider exposes different identifiers, group behavior, and delivery affordances.
Use this page when deciding what to put in instance_config.yaml or when asking
the assistant how to configure a channel.
Three Separate Concepts¶
Do not collapse these fields into one setting:
- Inbound allowlists decide who may talk to the assistant.
delivery.default_targetdecides where proactive messages, reminders, and autonomous notices go./userbinds a real external channel identity to a UA user record.
For app channels, a chat can be allowed for inbound messages but not configured for proactive delivery, or configured for proactive delivery but not allowed to start inbound conversations.
Finding IDs¶
Start the adapter, send a message from the target user or group, and inspect the
gateway log line for user_id, chat_id, and optional thread_id.
Use the exact logged values in configuration:
user_idor sender identity for direct allowlists.chat_idfor chat/channel/group allowlists and proactive delivery.thread_idonly for adapters that support thread/topic scoping.
If the message is rejected, many adapters log an onboarding hint such as
newuser_target=...; prefer that value for /user.
Group Policies¶
Group channels usually need both an allowlist and a policy:
interactive_apps:
plugins:
example.some_channel:
distribution: "example-some-channel"
settings:
enabled: true
allowed_group_ids:
- "GROUP_OR_CHANNEL_ID"
group_policy: "mention"
mention_markers:
- "@assistant"
With group_policy: "mention", unrelated group chatter is ignored unless the
message contains a configured marker or provider-native mention understood by
that adapter. With group_policy: "open", the adapter accepts ordinary text
from allowed groups. Use open only for groups where most messages should go to
the assistant.
Channel Differences¶
| Channel | Direct identity | Group identity | Mention behavior | Proactive target |
|---|---|---|---|---|
| Telegram | Numeric user_id; private chat_id is often the same number |
Group/supergroup chat_id; forum topics may have thread_id |
BotFather group privacy affects whether ordinary mentions reach the bot; configured mention mode filters group text | delivery.default_target.chat_id; optional topic thread_id |
| Discord | Numeric Discord user id | Channel id plus optional thread id | Guild channels use configured channel allowlists and mention/open policy; slash commands are synced separately | Channel id; optional thread id |
Twilio sender identity, usually whatsapp:+15551234567 |
Not a native group adapter path here | No native mention handling in this adapter | Twilio recipient address | |
| Signal | sourceUuid when available, otherwise E.164 phone number |
Signal group id | Configured mention_markers are required in mention mode |
Direct sender id or group id |
| Photon/iMessage | Photon sender.id when available, otherwise emitted iMessage phone/space id |
Photon group/space chat_id |
Text markers such as Nova, @Nova, or nova:; iMessage native mentions are not used by the adapter |
Exact logged Photon chat_id |
Photon/iMessage Group Addressing¶
Photon group chats require allowed_group_ids and, by default,
group_policy: "mention". Configure one or more text markers:
interactive_apps:
plugins:
builtin.photon:
settings:
enabled: true
allowed_group_ids:
- "THE_LOGGED_GROUP_CHAT_ID"
group_policy: "mention"
mention_markers:
- "Nova"
- "@Nova"
- "nova:"
Then address the assistant in the iMessage group with one of those markers:
Nova what is next on my calendar?
@Nova summarize the plan so far.
The marker is stripped before the message is forwarded to the manager.
Proactive Delivery¶
Configure proactive delivery separately from inbound allowlists:
delivery:
default_target:
channel_name: "photon"
chat_id: "THE_LOGGED_CHAT_ID"
thread_id: ""
If chat_id is empty for an app adapter, the gateway does not infer a default
DM target from recent activity.
Verification Checklist¶
- Load the relevant secrets from
team.env, Docker secrets, or--env. - Start
run-app --app <channel>for strict single-adapter troubleshooting, orrun-gatewayfor normal operation. - Send a direct message from an allowed sender.
- Confirm the gateway logs the expected
user_id,chat_id, and session. - If using groups, send a message that satisfies the group policy.
- Confirm the assistant replies in the originating chat.
- Trigger a proactive message only after
delivery.default_targetis set.