📄 user-guide/messaging/signal.md

sidebar_position: 6 title: "Signal" description: "Set up Hermes Agent as a Signal messenger bot via signal-cli daemon"

การตั้งค่า Signal

Hermes เชื่อมต่อกับ Signal ผ่าน daemon signal-cli ที่ทำงานในโหมด HTTP ตัว adapter จะสตรีมข้อความแบบ real-time ผ่าน SSE (Server-Sent Events) และส่งการตอบกลับผ่าน JSON-RPC

Signal เป็นแอปพลิเคชันส่งข้อความกระแสหลักที่เน้นความเป็นส่วนตัวมากที่สุด - มีการเข้ารหัสแบบ end-to-end เป็นค่าเริ่มต้น, ใช้โปรโตคอลแบบ open-source, และมีการเก็บ metadata น้อยที่สุด ด้วยคุณสมบัตินี้จึงเหมาะสำหรับ workflow ของ agent ที่ต้องการความปลอดภัยสูง

:::info No New Python Dependencies Signal adapter ใช้ httpx (ซึ่งเป็น dependency หลักของ Hermes อยู่แล้ว) สำหรับการสื่อสารทั้งหมด ไม่จำเป็นต้องติดตั้ง Python packages เพิ่มเติม คุณเพียงแค่ต้องติดตั้ง signal-cli ภายนอกเท่านั้น :::

ข้อกำหนดเบื้องต้น (Prerequisites)

• signal-cli - Signal client ที่ใช้ Java-based (GitHub)
• Java 17+ runtime - จำเป็นสำหรับ signal-cli
• หมายเลขโทรศัพท์ ที่ติดตั้ง Signal (สำหรับการเชื่อมโยงเป็นอุปกรณ์รอง)

การติดตั้ง signal-cli

# macOS
brew install signal-cli

# Linux (ดาวน์โหลด latest release)
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \
  https://github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz"
sudo tar xf "signal-cli-${VERSION}.tar.gz" -C /opt
sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/

:::caution signal-cli ไม่ได้ อยู่ใน apt หรือ snap repositories การติดตั้งบน Linux ข้างต้นจะดาวน์โหลดโดยตรงจาก GitHub releases :::

ขั้นตอนที่ 1: เชื่อมโยงบัญชี Signal ของคุณ

Signal-cli ทำงานในลักษณะของ อุปกรณ์ที่เชื่อมโยง (linked device) - คล้ายกับ WhatsApp Web แต่สำหรับ Signal โทรศัพท์ของคุณยังคงเป็นอุปกรณ์หลัก

# สร้าง linking URI (แสดง QR code หรือลิงก์)
signal-cli link -n "HermesAgent"

1. เปิด Signal บนโทรศัพท์ของคุณ
2. ไปที่ Settings → Linked Devices
3. แตะ Link New Device
4. สแกน QR code หรือป้อน URI

ขั้นตอนที่ 2: เริ่มต้น Daemon ของ signal-cli

# แทนที่ +1234567890 ด้วยหมายเลขโทรศัพท์ Signal ของคุณ (รูปแบบ E.164)
signal-cli --account +1234567890 daemon --http 127.0.0.1:8080

:::tip ให้รันส่วนนี้ไว้ใน background คุณสามารถใช้ systemd, tmux, screen, หรือรันเป็น service ได้ :::

ตรวจสอบว่ากำลังทำงานอยู่หรือไม่:

curl http://127.0.0.1:8080/api/v1/check
# ควรคืนค่า: {"versions":{"signal-cli":...}}

ขั้นตอนที่ 3: กำหนดค่า Hermes

วิธีที่ง่ายที่สุด:

hermes gateway setup

เลือก Signal จากเมนูแพลตฟอร์ม Wizard จะดำเนินการ:

1. ตรวจสอบว่าติดตั้ง signal-cli แล้ว
2. แจ้ง URL สำหรับ HTTP (ค่าเริ่มต้น: http://127.0.0.1:8080)
3. ทดสอบการเชื่อมต่อกับ daemon
4. สอบถามหมายเลขโทรศัพท์บัญชีของคุณ
5. กำหนดค่าผู้ใช้ที่อนุญาตและนโยบายการเข้าถึง

การกำหนดค่าด้วยตนเอง (Manual Configuration)

เพิ่มใน ~/.hermes/.env:

# จำเป็นต้องมี
SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+1234567890

# ความปลอดภัย (แนะนำ)
SIGNAL_ALLOWED_USERS=+1234567890,+0987654321    # หมายเลข E.164 หรือ UUID คั่นด้วยเครื่องหมายจุลภาค

# ทางเลือก
SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2     # เปิดใช้งานกลุ่ม (เว้นว่างเพื่อปิดใช้งาน, * สำหรับทั้งหมด)
SIGNAL_HOME_CHANNEL=+1234567890                  # เป้าหมายการส่งค่าเริ่มต้นสำหรับ cron jobs

จากนั้นเริ่ม gateway:

hermes gateway              # Foreground
hermes gateway install      # ติดตั้งเป็น user service
sudo hermes gateway install --system   # สำหรับ Linux เท่านั้น: system service ที่ทำงานเมื่อบูต

การควบคุมการเข้าถึง (Access Control)

การเข้าถึง DM

การเข้าถึง DM เป็นไปตามรูปแบบเดียวกับแพลตฟอร์ม Hermes อื่นๆ ทั้งหมด:

1. SIGNAL_ALLOWED_USERS ถูกตั้งค่า → เฉพาะผู้ใช้เหล่านั้นเท่านั้นที่สามารถส่งข้อความได้
2. ไม่ได้ตั้งค่า allowlist → ผู้ใช้ที่ไม่ทราบจะได้รับรหัสจับคู่ DM (อนุมัติผ่าน hermes pairing approve signal CODE)
3. SIGNAL_ALLOW_ALL_USERS=true → ใครๆ ก็สามารถส่งข้อความได้ (ควรใช้ด้วยความระมัดระวัง)

การเข้าถึงกลุ่ม (Group Access)

การเข้าถึงกลุ่มถูกควบคุมโดยตัวแปรสภาพแวดล้อม SIGNAL_GROUP_ALLOWED_USERS:

คุณสมบัติ (Features)

ไฟล์แนบ (Attachments)

adapter รองรับการส่งและรับสื่อในทั้งสองทิศทาง

ขาเข้า (Incoming) (ผู้ใช้ → agent):

• รูปภาพ - PNG, JPEG, GIF, WebP (ตรวจจับอัตโนมัติผ่าน magic bytes)
• เสียง - MP3, OGG, WAV, M4A (ข้อความเสียงจะถูกถอดเสียงหากมีการตั้งค่า Whisper)
• เอกสาร - PDF, ZIP, และประเภทไฟล์อื่นๆ

ขาออก (Outgoing) (agent → ผู้ใช้):

agent สามารถส่งไฟล์สื่อผ่านแท็ก MEDIA: ในการตอบกลับได้ รองรับวิธีการส่งมอบดังต่อไปนี้:

• รูปภาพ - send_image_file ส่ง PNG, JPEG, GIF, WebP เป็น Signal attachments แบบ native
• เสียง - send_voice ส่งไฟล์เสียง (OGG, MP3, WAV, M4A, AAC) เป็น attachments
• วิดีโอ - send_video ส่งไฟล์วิดีโอ MP4
• เอกสาร - send_document ส่งไฟล์ประเภทใดก็ได้ (PDF, ZIP, ฯลฯ)

สื่อขาออกทั้งหมดจะผ่าน Signal's standard attachment API ต่างจากแพลตฟอร์มบางแห่ง Signal ไม่ได้แยกความแตกต่างระหว่างข้อความเสียงกับไฟล์แนบในระดับโปรโตคอล

ขีดจำกัดขนาดไฟล์แนบ: 100 MB (ทั้งสองทิศทาง)

ตัวบ่งชี้การพิมพ์ (Typing Indicators)

บอทจะส่งตัวบ่งชี้การพิมพ์ขณะประมวลผลข้อความ โดยจะรีเฟรชทุก 8 วินาที

การปกปิดหมายเลขโทรศัพท์ (Phone Number Redaction)

หมายเลขโทรศัพท์ทั้งหมดจะถูกปกปิดโดยอัตโนมัติใน log:

• +15551234567 → +155****4567
• สิ่งนี้ใช้ได้ทั้งใน log ของ Hermes gateway และระบบการปกปิดทั่วโลก

หมายเหตุถึงตัวเอง (Note to Self - Single-Number Setup)

หากคุณรัน signal-cli เป็น อุปกรณ์รองที่เชื่อมโยง (linked secondary device) ด้วยหมายเลขโทรศัพท์ของคุณเอง (แทนที่จะเป็นหมายเลขบอทแยก) คุณสามารถโต้ตอบกับ Hermes ผ่านฟีเจอร์ "Note to Self" ของ Signal ได้

เพียงแค่ส่งข้อความถึงตัวคุณเองจากโทรศัพท์ของคุณ - signal-cli จะรับข้อความนั้นและ Hermes จะตอบกลับในบทสนทนาเดียวกัน

วิธีการทำงาน:

• ข้อความ "Note to Self" จะมาถึงในรูปแบบ syncMessage.sentMessage envelopes
• adapter จะตรวจจับเมื่อข้อความเหล่านี้ถูกส่งถึงบัญชีของบอทเอง และประมวลผลเป็นข้อความขาเข้าปกติ
• การป้องกันการสะท้อนกลับ (echo-back protection) (การติดตาม sent-timestamp) ป้องกันลูปไม่รู้จบ - การตอบกลับของบอทเองจะถูกกรองออกโดยอัตโนมัติ

ไม่ต้องตั้งค่าเพิ่มเติม สิ่งนี้จะทำงานโดยอัตโนมัติตราบใดที่ SIGNAL_ACCOUNT ตรงกับหมายเลขโทรศัพท์ของคุณ

การตรวจสอบสถานะ (Health Monitoring)

adapter จะตรวจสอบการเชื่อมต่อ SSE และจะเชื่อมต่อใหม่โดยอัตโนมัติหาก:

• การเชื่อมต่อหลุด (พร้อม exponential backoff: 2s → 60s)
• ไม่มีการใช้งานเป็นเวลา 120 วินาที (ping signal-cli เพื่อตรวจสอบ)

การแก้ไขปัญหา (Troubleshooting)

ความปลอดภัย (Security)

:::warning ต้องกำหนดค่าการควบคุมการเข้าถึงเสมอ โดยค่าเริ่มต้น บอทมีสิทธิ์เข้าถึง terminal เสมอ หากไม่มี SIGNAL_ALLOWED_USERS หรือ DM pairing gateway จะปฏิเสธข้อความขาเข้าทั้งหมดเพื่อความปลอดภัย :::

• หมายเลขโทรศัพท์จะถูกปกปิดใน log output ทั้งหมด
• ใช้ DM pairing หรือ allowlist อย่างชัดเจนสำหรับการเริ่มต้นใช้งานผู้ใช้ใหม่ที่ปลอดภัย
• ปิดใช้งานกลุ่ม เว้นแต่คุณต้องการการรองรับกลุ่มโดยเฉพาะ หรือจำกัดเฉพาะกลุ่มที่คุณเชื่อถือเท่านั้น
• การเข้ารหัส end-to-end ของ Signal ปกป้องเนื้อหาข้อความระหว่างการส่ง
• ข้อมูลเซสชัน signal-cli ใน ~/.local/share/signal-cli/ มี credentials ของบัญชี - โปรดปกป้องมันเหมือนรหัสผ่าน

อ้างอิงตัวแปรสภาพแวดล้อม (Environment Variables Reference)

📄 user-guide/messaging/slack.md

sidebar_position: 4 title: "Slack" description: "Set up Hermes Agent as a Slack bot using Socket Mode"

การตั้งค่า Slack

เชื่อมต่อ Hermes Agent เข้ากับ Slack ในรูปแบบ bot โดยใช้ Socket Mode Socket Mode ใช้ WebSockets แทนการใช้ public HTTP endpoints ดังนั้น instance ของ Hermes ของคุณจึงไม่จำเป็นต้องเข้าถึงได้จากภายนอก (publicly accessible) - มันสามารถทำงานได้เบื้องหลัง firewall, บนแล็ปท็อปของคุณ, หรือบน private server

:::warning Classic Slack Apps Deprecated แอป Slack แบบ Classic (ที่ใช้ RTM API) ถูก ยกเลิกการใช้งานโดยสมบูรณ์แล้วในเดือนมีนาคม 2025 Hermes ใช้ Bolt SDK ที่ทันสมัยพร้อม Socket Mode หากคุณมีแอปแบบ classic เก่า คุณต้องสร้างแอปใหม่โดยทำตามขั้นตอนด้านล่างนี้ :::

ภาพรวม (Overview)

ขั้นตอนที่ 1: สร้าง Slack App

1. ไปที่ https://api.slack.com/apps
2. คลิก Create New App
3. เลือก From scratch
4. ป้อนชื่อแอป (เช่น "Hermes Agent") และเลือก workspace ของคุณ
5. คลิก Create App

คุณจะถูกนำไปยังหน้า Basic Information ของแอป

ขั้นตอนที่ 2: กำหนดขอบเขต Bot Token (Configure Bot Token Scopes)

ไปที่ Features → OAuth & Permissions ในแถบด้านข้าง เลื่อนลงไปที่ Scopes → Bot Token Scopes และเพิ่มรายการต่อไปนี้:

:::caution Missing scopes = missing features หากไม่มี channels:history และ groups:history bot จะไม่รับข้อความในช่อง (channels) - มันจะทำงานได้เฉพาะใน DM เท่านั้น นี่คือขอบเขตที่มักถูกมองข้ามมากที่สุด :::

Optional scopes:

ขั้นตอนที่ 3: เปิดใช้งาน Socket Mode

Socket Mode ช่วยให้ bot สามารถเชื่อมต่อผ่าน WebSocket แทนการต้องใช้ public URL

1. ในแถบด้านข้าง ไปที่ Settings → Socket Mode
2. เปิด Enable Socket Mode เป็น ON
3. คุณจะถูกแจ้งให้สร้าง App-Level Token:
   • ตั้งชื่อเป็นอะไรก็ได้ เช่น hermes-socket (ชื่อไม่สำคัญ)
   • เพิ่ม scope connections:write
   • คลิก Generate
4. คัดลอก token - มันจะขึ้นต้นด้วย xapp- นี่คือ SLACK_APP_TOKEN ของคุณ

:::tip คุณสามารถค้นหาหรือสร้าง app-level tokens ใหม่ได้เสมอภายใต้ Settings → Basic Information → App-Level Tokens. :::

ขั้นตอนที่ 4: สมัครรับ Event (Subscribe to Events)

ขั้นตอนนี้สำคัญมาก - เพราะมันควบคุมว่า bot จะเห็นข้อความอะไรได้บ้าง

1. ในแถบด้านข้าง ไปที่ Features → Event Subscriptions
2. เปิด Enable Events เป็น ON
3. ขยาย Subscribe to bot events และเพิ่ม:

1. คลิก Save Changes ที่ด้านล่างของหน้า

:::danger Missing event subscriptions is the #1 setup issue หาก bot ทำงานได้ใน DM แต่ ไม่ทำงานในช่อง (channels) คุณเกือบจะแน่ใจว่าลืมเพิ่ม message.channels (สำหรับช่องสาธารณะ) และ/หรือ message.groups (สำหรับช่องส่วนตัว) โดยไม่มี event เหล่านี้ Slack จะไม่ส่งข้อความในช่องมาให้ bot เลย :::

ขั้นตอนที่ 5: เปิดใช้งานแท็บ Messages (Enable the Messages Tab)

ขั้นตอนนี้เปิดใช้งานการส่งข้อความส่วนตัว (direct messages) ไปยัง bot หากไม่มีขั้นตอนนี้ ผู้ใช้จะเห็นข้อความว่า "Sending messages to this app has been turned off" เมื่อพยายาม DM bot

1. ในแถบด้านข้าง ไปที่ Features → App Home
2. เลื่อนลงไปที่ Show Tabs
3. เปิด Messages Tab เป็น ON
4. ติ๊ก "Allow users to send Slash commands and messages from the messages tab"

:::danger Without this step, DMs are completely blocked แม้จะมี scope และ event subscriptions ที่ถูกต้องทั้งหมด แต่ Slack จะไม่อนุญาตให้ผู้ใช้ส่ง direct messages ไปยัง bot เว้นแต่จะเปิดใช้งาน Messages Tab นี่คือข้อกำหนดของแพลตฟอร์ม Slack ไม่ใช่ปัญหาการตั้งค่าของ Hermes :::

ขั้นตอนที่ 6: ติดตั้ง App เข้ากับ Workspace (Install App to Workspace)

1. ในแถบด้านข้าง ไปที่ Settings → Install App
2. คลิก Install to Workspace
3. ตรวจสอบสิทธิ์และคลิก Allow
4. หลังจากอนุญาตแล้ว คุณจะเห็น Bot User OAuth Token ที่ขึ้นต้นด้วย xoxb-
5. คัดลอก token นี้ - นี่คือ SLACK_BOT_TOKEN ของคุณ

:::tip หากคุณเปลี่ยน scopes หรือ event subscriptions ในภายหลัง คุณ ต้องติดตั้งแอปใหม่ เพื่อให้การเปลี่ยนแปลงมีผล หน้า Install App จะแสดงแบนเนอร์แจ้งให้คุณทำเช่นนั้น :::

ขั้นตอนที่ 7: ค้นหา User IDs สำหรับ Allowlist

Hermes ใช้ Member IDs ของ Slack (ไม่ใช่ชื่อผู้ใช้หรือชื่อที่แสดง) สำหรับ allowlist

วิธีค้นหา Member ID:

1. ใน Slack คลิกที่ชื่อหรือ avatar ของผู้ใช้
2. คลิก View full profile
3. คลิกปุ่ม ⋮ (more)
4. เลือก Copy member ID

Member IDs มีลักษณะคล้าย U01ABC2DEF3 อย่างน้อยคุณต้องมี Member ID ของตัวเอง

ขั้นตอนที่ 8: กำหนดค่า Hermes

เพิ่มรายการต่อไปนี้ในไฟล์ ~/.hermes/.env ของคุณ:

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Member IDs ที่คั่นด้วยเครื่องหมายจุลภาค

# Optional
SLACK_HOME_CHANNEL=C01234567890              # ช่องเริ่มต้นสำหรับข้อความ cron/scheduled messages
SLACK_HOME_CHANNEL_NAME=general              # ชื่อที่อ่านได้สำหรับช่องเริ่มต้น (optional)

หรือรันการตั้งค่าแบบโต้ตอบ (interactive setup):

hermes gateway setup    # เลือก Slack เมื่อถูกแจ้ง

จากนั้นเริ่ม gateway:

hermes gateway              # สำหรับ foreground
hermes gateway install      # ติดตั้งเป็น user service
sudo hermes gateway install --system   # สำหรับ Linux เท่านั้น: system service ที่ boot-time

ขั้นตอนที่ 9: เชิญ Bot เข้าสู่ Channels

หลังจากเริ่ม gateway แล้ว คุณต้อง เชิญ bot เข้าไปยังช่องใดๆ ที่คุณต้องการให้มันตอบ:

/invite @Hermes Agent

bot จะ ไม่ เข้าสู่ช่องโดยอัตโนมัติ คุณต้องเชิญมันเข้าสู่แต่ละช่องด้วยตนเอง

วิธีที่ Bot ตอบสนอง (How the Bot Responds)

การทำความเข้าใจว่า Hermes มีพฤติกรรมอย่างไรในบริบทที่แตกต่างกัน:

:::tip ในช่อง (channels) ให้ @mention bot เสมอเพื่อเริ่มบทสนทนา เมื่อ bot ทำงานอยู่ใน thread แล้ว คุณสามารถตอบกลับใน thread นั้นได้โดยไม่ต้อง mention นอกเหนือจาก thread ข้อความที่ไม่มี @mention จะถูกละเลยเพื่อป้องกันความวุ่นวายในช่องที่ยุ่งมาก :::

ตัวเลือกการกำหนดค่า (Configuration Options)

นอกเหนือจาก environment variables ที่จำเป็นในขั้นตอนที่ 8 คุณสามารถปรับแต่งพฤติกรรมของ Slack bot ผ่าน ~/.hermes/config.yaml

Thread & Reply Behavior

platforms:
  slack:
    # ควบคุมว่าการตอบกลับหลายส่วน (multi-part responses) จะถูก thread อย่างไร
    # "off"   - ไม่เคย thread การตอบกลับไปยังข้อความต้นฉบับ
    # "first" - ส่วนแรกจะ thread ไปยังข้อความของผู้ใช้ (ค่าเริ่มต้น)
    # "all"   - ทุกส่วนจะ thread ไปยังข้อความของผู้ใช้
    reply_to_mode: "first"

    extra:
      # ว่าจะตอบกลับใน thread หรือไม่ (ค่าเริ่มต้น: true).
      # เมื่อเป็น false ข้อความในช่องจะได้รับ direct channel replies แทน
      # การใช้ thread ข้อความที่อยู่ใน thread ที่มีอยู่ยังคงตอบกลับใน thread
      reply_in_thread: true

      # ส่ง thread replies ไปยัง main channel ด้วยหรือไม่
      # (ฟีเจอร์ "Also send to channel" ของ Slack).
      # มีเพียงส่วนแรกของ reply แรกเท่านั้นที่จะถูก broadcast.
      reply_broadcast: false

Session Isolation

# Global setting - ใช้ได้กับ Slack และแพลตฟอร์มอื่นทั้งหมด
group_sessions_per_user: true

เมื่อเป็น true (ค่าเริ่มต้น) ผู้ใช้แต่ละคนในช่องที่แชร์จะได้รับ session การสนทนาที่แยกจากกัน สองคนที่คุยกับ Hermes ใน #general จะมีประวัติและบริบทที่แยกจากกัน

ตั้งค่าเป็น false หากคุณต้องการโหมดทำงานร่วมกันที่ทั้งช่องแชร์ session การสนทนาเดียว โปรดทราบว่านี่หมายความว่าผู้ใช้แชร์การเติบโตของบริบทและค่าใช้จ่าย token และการใช้ /reset ของผู้ใช้คนหนึ่งจะล้าง session สำหรับทุกคน

Mention & Trigger Behavior

slack:
  # กำหนดให้ต้อง @mention ในช่อง (นี่คือพฤติกรรมเริ่มต้น;
  # ตัว adapter ของ Slack บังคับใช้ @mention gating ในช่องโดยไม่คำนึงถึง,
  # แต่คุณสามารถตั้งค่าสิ่งนี้อย่างชัดเจนเพื่อให้สอดคล้องกับแพลตฟอร์มอื่น)
  require_mention: true

  # รูปแบบ mention ที่กำหนดเองที่กระตุ้น bot
  # (นอกเหนือจากการตรวจจับ @mention โดยค่าเริ่มต้น)
  mention_patterns:
    - "hey hermes"
    - "hermes,"

  # ข้อความที่เติมไว้ด้านหน้าทุกข้อความที่ส่งออก
  reply_prefix: ""

:::info Slack รองรับทั้ง patterns: โดยค่าเริ่มต้นต้อง @mention เพื่อเริ่มบทสนทนา แต่คุณสามารถยกเว้นช่องเฉพาะได้ผ่าน SLACK_FREE_RESPONSE_CHANNELS (channel IDs ที่คั่นด้วยเครื่องหมายจุลภาค) หรือ slack.free_response_channels ใน config.yaml เมื่อ bot มี session ที่ใช้งานอยู่ใน thread แล้ว การตอบกลับใน thread ครั้งต่อไปไม่จำเป็นต้อง mention ใน DM bot จะตอบสนองเสมอโดยไม่จำเป็นต้อง mention :::

Unauthorized User Handling

slack:
  # จะเกิดอะไรขึ้นเมื่อผู้ใช้ที่ไม่ได้รับอนุญาต (ไม่ได้อยู่ใน SLACK_ALLOWED_USERS) DM bot
  # "pair"   - แจ้งให้พวกเขาขอ pairing code (ค่าเริ่มต้น)
  # "ignore" - ละทิ้งข้อความอย่างเงียบๆ
  unauthorized_dm_behavior: "pair"

คุณยังสามารถตั้งค่าสิ่งนี้ได้ทั่วโลกสำหรับทุกแพลตฟอร์ม:

unauthorized_dm_behavior: "pair"

การตั้งค่าเฉพาะแพลตฟอร์มภายใต้ slack: จะมีลำดับความสำคัญเหนือการตั้งค่าทั่วโลก

Voice Transcription

# Global setting - เปิด/ปิดการถอดเสียงอัตโนมัติของข้อความเสียงที่เข้ามา
stt_enabled: true

เมื่อเป็น true (ค่าเริ่มต้น) ข้อความเสียงที่เข้ามาจะถูกถอดเสียงโดยอัตโนมัติโดยใช้ STT provider ที่กำหนดค่าไว้ก่อนที่จะถูกประมวลผลโดย agent

Full Example

# Global gateway settings
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Slack-specific settings
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Platform config
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

Home Channel

ตั้งค่า SLACK_HOME_CHANNEL เป็น Channel ID ที่ Hermes จะส่งข้อความที่กำหนดเวลา (scheduled messages), ผลลัพธ์ cron job, และการแจ้งเตือนเชิงรุกอื่นๆ วิธีค้นหา Channel ID:

1. คลิกขวาที่ชื่อช่องใน Slack
2. คลิก View channel details
3. เลื่อนลงไปด้านล่าง - Channel ID จะแสดงอยู่ที่นั่น

SLACK_HOME_CHANNEL=C01234567890

ตรวจสอบให้แน่ใจว่า bot ได้รับ เชิญเข้าช่อง (/invite @Hermes Agent) แล้ว

Multi-Workspace Support

Hermes สามารถเชื่อมต่อกับ multiple Slack workspaces ได้พร้อมกันโดยใช้ gateway instance เดียว Workspace แต่ละแห่งจะได้รับการยืนยันตัวตนอย่างอิสระด้วย bot user ID ของตัวเอง

Configuration

ระบุ bot tokens หลายตัวเป็น รายการที่คั่นด้วยเครื่องหมายจุลภาค ใน SLACK_BOT_TOKEN:

# Multiple bot tokens - ตัวละ workspace
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# ยังคงใช้ app-level token เดียวสำหรับ Socket Mode
SLACK_APP_TOKEN=xapp-your-app-token

หรือใน ~/.hermes/config.yaml:

platforms:
  slack:
    token: "xoxb-workspace1-token,xoxb-workspace2-token"

OAuth Token File

นอกเหนือจาก tokens ใน environment หรือ config แล้ว Hermes ยังโหลด tokens จาก OAuth token file ที่:

~/.hermes/slack_tokens.json

ไฟล์นี้เป็น JSON object ที่แมป team IDs กับรายการ token:

{
  "T01ABC2DEF3": {
    "token": "xoxb-workspace-token-here",
    "team_name": "My Workspace"
  }
}

Tokens จากไฟล์นี้จะถูกรวมกับ tokens ใดๆ ที่ระบุผ่าน SLACK_BOT_TOKEN Tokens ที่ซ้ำกันจะถูกลบออกโดยอัตโนมัติ

How it works

• token แรก ในรายการคือ primary token ซึ่งใช้สำหรับการเชื่อมต่อ Socket Mode (AsyncApp)
• แต่ละ token จะได้รับการยืนยันตัวตนผ่าน auth.test เมื่อเริ่มต้น gateway จะแมปแต่ละ team_id ไปยัง WebClient และ bot_user_id ของตัวเอง
• เมื่อมีข้อความเข้ามา Hermes จะใช้ client เฉพาะ workspace ที่ถูกต้องเพื่อตอบกลับ
• bot_user_id หลัก (จาก token แรก) ถูกใช้เพื่อความเข้ากันได้กับคุณสมบัติที่คาดหวัง bot identity เดียว

Voice Messages

Hermes รองรับ voice บน Slack:

• Incoming: ข้อความเสียง/audio จะถูกถอดเสียงโดยอัตโนมัติโดยใช้ STT provider ที่กำหนดค่าไว้: local faster-whisper, Groq Whisper (GROQ_API_KEY), หรือ OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
• Outgoing: การตอบกลับ TTS จะถูกส่งเป็นไฟล์แนบ audio

Per-Channel Prompts

กำหนด ephemeral system prompts ให้กับ Slack channels เฉพาะ Prompt จะถูกแทรกใน runtime ในทุกรอบ - ไม่เคยถูกบันทึกใน transcript history - ดังนั้นการเปลี่ยนแปลงจึงมีผลทันที

slack:
  channel_prompts:
    "C01RESEARCH": |
      คุณเป็นผู้ช่วยวิจัย มุ่งเน้นที่แหล่งข้อมูลทางวิชาการ,
      การอ้างอิง, และการสังเคราะห์ที่กระชับ
    "C02ENGINEERING": |
      โหมด Code review ต้องแม่นยำเกี่ยวกับ edge cases และ
      ผลกระทบด้านประสิทธิภาพ

Keys คือ Slack channel IDs (ค้นหาได้จาก channel details → "About" → เลื่อนลงไปด้านล่าง) ข้อความทั้งหมดในช่องที่ตรงกันจะได้รับ prompt ที่ถูกแทรกเป็น ephemeral system instruction

Troubleshooting

Quick Checklist

หาก bot ไม่ทำงานในช่อง (channels) ให้ตรวจสอบ ทั้งหมด เหล่านี้:

1. ✅ event message.channels ถูก subscribe แล้ว (สำหรับช่องสาธารณะ)
2. ✅ event message.groups ถูก subscribe แล้ว (สำหรับช่องส่วนตัว)
3. ✅ event app_mention ถูก subscribe แล้ว
4. ✅ scope channels:history ถูกเพิ่มแล้ว (สำหรับช่องสาธารณะ)
5. ✅ scope groups:history ถูกเพิ่มแล้ว (สำหรับช่องส่วนตัว)
6. ✅ แอปได้รับการ ติดตั้งใหม่ หลังจากเพิ่ม scopes/events
7. ✅ Bot ได้รับ เชิญ เข้าช่องแล้ว (/invite @Hermes Agent)
8. ✅ คุณกำลัง @mention bot ในข้อความของคุณ

Security

:::warning ต้องตั้งค่า SLACK_ALLOWED_USERS เสมอ ด้วย Member IDs ของผู้ใช้ที่ได้รับอนุญาต หากไม่มีการตั้งค่านี้ gateway จะ ปฏิเสธข้อความทั้งหมด โดยค่าเริ่มต้นเพื่อความปลอดภัย ห้ามแชร์ bot tokens ของคุณ - ให้ถือว่ามันเป็นรหัสผ่าน :::

• Tokens ควรถูกเก็บไว้ใน ~/.hermes/.env (สิทธิ์ไฟล์ 600)
• หมุนเวียน tokens เป็นระยะผ่านการตั้งค่าแอป Slack
• ตรวจสอบว่าใครมีสิทธิ์เข้าถึง directory config ของ Hermes ของคุณ
• Socket Mode หมายความว่าไม่มี public endpoint ถูกเปิดเผย - ลดพื้นที่ผิวการโจมตีลงได้อีกจุด

📄 user-guide/messaging/sms.md

sidebar_position: 8 sidebar_label: "SMS (Twilio)" title: "SMS (Twilio)" description: "Set up Hermes Agent as an SMS chatbot via Twilio"

การตั้งค่า SMS (Twilio)

Hermes เชื่อมต่อกับ SMS ผ่าน Twilio API ผู้คนสามารถส่งข้อความ (text) ไปยังหมายเลขโทรศัพท์ Twilio ของคุณ และรับการตอบกลับจาก AI ได้ ประสบการณ์การสนทนาเหมือนกับ Telegram หรือ Discord แต่ใช้ข้อความธรรมดาแทน

:::info ข้อมูลรับรองที่ใช้ร่วมกัน (Shared Credentials) เกตเวย์ SMS ใช้ข้อมูลรับรองร่วมกับ telephony skill ที่เป็นทางเลือก หากคุณได้ตั้งค่า Twilio สำหรับการโทรด้วยเสียงหรือ SMS แบบครั้งเดียวแล้ว เกตเวย์จะใช้ TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, และ TWILIO_PHONE_NUMBER ชุดเดียวกัน :::

ข้อกำหนดเบื้องต้น

• บัญชี Twilio - ลงทะเบียนที่ twilio.com (มี free trial ให้ใช้)
• หมายเลขโทรศัพท์ Twilio ที่รองรับ SMS
• เซิร์ฟเวอร์ที่เข้าถึงได้แบบสาธารณะ - Twilio จะส่ง webhooks ไปยังเซิร์ฟเวอร์ของคุณเมื่อมี SMS เข้ามา
• aiohttp - pip install 'hermes-agent[sms]'

ขั้นตอนที่ 1: รับข้อมูลรับรอง Twilio ของคุณ

1. ไปที่ Twilio Console
2. คัดลอก Account SID และ Auth Token ของคุณจากหน้าแดชบอร์ด
3. ไปที่ Phone Numbers → Manage → Active Numbers - จดหมายเลขโทรศัพท์ของคุณในรูปแบบ E.164 (เช่น +15551234567)

ขั้นตอนที่ 2: กำหนดค่า Hermes

การตั้งค่าแบบโต้ตอบ (แนะนำ)

hermes gateway setup

เลือก SMS (Twilio) จากรายการแพลตฟอร์ม ตัวช่วย (wizard) จะแจ้งให้คุณป้อนข้อมูลรับรอง

การตั้งค่าแบบแมนนวล

เพิ่มใน ~/.hermes/.env:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

# Security: restrict to specific phone numbers (recommended)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Optional: set a home channel for cron job delivery
SMS_HOME_CHANNEL=+15559876543

ขั้นตอนที่ 3: กำหนดค่า Twilio Webhook

Twilio จำเป็นต้องรู้ว่าจะส่งข้อความขาเข้าที่ใด ใน Twilio Console:

1. ไปที่ Phone Numbers → Manage → Active Numbers
2. คลิกที่หมายเลขโทรศัพท์ของคุณ
3. ใต้ Messaging → A MESSAGE COMES IN, ให้ตั้งค่า:
   • Webhook: https://your-server:8080/webhooks/twilio
   • HTTP Method: POST

:::tip การเปิดเผย Webhook ของคุณ หากคุณกำลังรัน Hermes ในเครื่อง (locally) ให้ใช้ tunnel เพื่อเปิดเผย webhook:

# Using cloudflared
cloudflared tunnel --url http://localhost:8080

# Using ngrok
ngrok http 8080

ตั้งค่า URL สาธารณะที่ได้เป็น Twilio webhook ของคุณ :::

ตั้งค่า SMS_WEBHOOK_URL ให้เป็น URL เดียวกับที่คุณกำหนดค่าใน Twilio สิ่งนี้จำเป็นสำหรับการตรวจสอบลายเซ็น (signature validation) ของ Twilio - adapter จะปฏิเสธที่จะเริ่มทำงานหากไม่มีค่านี้:

# Must match the webhook URL in your Twilio Console
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

พอร์ต webhook จะตั้งค่าเริ่มต้นที่ 8080 หากต้องการเปลี่ยน ให้ใช้:

SMS_WEBHOOK_PORT=3000

ขั้นตอนที่ 4: เริ่มต้นใช้งาน Gateway

hermes gateway

คุณควรเห็นข้อความ:

[sms] Twilio webhook server listening on 0.0.0.0:8080, from: +1555***4567

หากคุณเห็นข้อความ Refusing to start: SMS_WEBHOOK_URL is required ให้ตั้งค่า SMS_WEBHOOK_URL เป็น URL สาธารณะที่กำหนดค่าใน Twilio Console ของคุณ (ดูขั้นตอนที่ 3)

ส่งข้อความไปยังหมายเลข Twilio ของคุณ - Hermes จะตอบกลับทาง SMS

Environment Variables

พฤติกรรมเฉพาะ SMS

• Plain text only - Markdown จะถูกลบโดยอัตโนมัติเนื่องจาก SMS แสดงผลเป็นตัวอักษรตามตัวอักษร
• 1600 character limit - การตอบกลับที่ยาวกว่าจะถูกแบ่งออกเป็นหลายข้อความที่ขอบเขตตามธรรมชาติ (ขึ้นบรรทัดใหม่, จากนั้นเว้นวรรค)
• Echo prevention - ข้อความจากหมายเลข Twilio ของคุณเองจะถูกเพิกเฉยเพื่อป้องกันการวนซ้ำ (loops)
• Phone number redaction - หมายเลขโทรศัพท์จะถูกลบ (redacted) ใน logs เพื่อความเป็นส่วนตัว

ความปลอดภัย

การตรวจสอบลายเซ็น Webhook

Hermes จะตรวจสอบว่า webhook ที่เข้ามามีต้นทางมาจาก Twilio จริงหรือไม่ โดยการตรวจสอบ header X-Twilio-Signature (HMAC-SHA1) สิ่งนี้ป้องกันไม่ให้ผู้โจมตีแทรกข้อความปลอมได้

SMS_WEBHOOK_URL เป็นสิ่งที่จำเป็น ต้องตั้งค่าให้เป็น URL สาธารณะที่กำหนดค่าใน Twilio Console ของคุณ adapter จะปฏิเสธที่จะเริ่มทำงานหากไม่มีค่านี้

สำหรับการพัฒนาในเครื่อง (local development) โดยไม่มี URL สาธารณะ คุณสามารถปิดการตรวจสอบได้:

# Local dev only — NOT for production
SMS_INSECURE_NO_SIGNATURE=true

รายชื่อผู้ใช้ที่อนุญาต (User allowlists)

โดยค่าเริ่มต้น gateway จะปฏิเสธผู้ใช้ทุกคน ให้กำหนดค่า allowlist:

# Recommended: restrict to specific phone numbers
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Or allow all (NOT recommended for bots with terminal access)
SMS_ALLOW_ALL_USERS=true

:::warning SMS ไม่มีระบบการเข้ารหัสในตัว (built-in encryption) อย่าใช้ SMS สำหรับการดำเนินการที่ละเอียดอ่อน เว้นแต่คุณจะเข้าใจถึงผลกระทบด้านความปลอดภัย สำหรับกรณีการใช้งานที่ละเอียดอ่อน ให้เลือกใช้ Signal หรือ Telegram :::

การแก้ไขปัญหา (Troubleshooting)

ข้อความไม่มาถึง

1. ตรวจสอบว่า Twilio webhook URL ของคุณถูกต้องและสามารถเข้าถึงได้แบบสาธารณะ
2. ตรวจสอบว่า TWILIO_ACCOUNT_SID และ TWILIO_AUTH_TOKEN ถูกต้อง
3. ตรวจสอบ Twilio Console → Monitor → Logs → Messaging เพื่อดูข้อผิดพลาดในการส่ง
4. ตรวจสอบให้แน่ใจว่าหมายเลขโทรศัพท์ของคุณอยู่ใน SMS_ALLOWED_USERS (หรือ SMS_ALLOW_ALL_USERS=true)

การตอบกลับไม่ถูกส่ง

1. ตรวจสอบว่า TWILIO_PHONE_NUMBER ถูกตั้งค่าอย่างถูกต้อง (รูปแบบ E.164 พร้อมเครื่องหมาย +)
2. ตรวจสอบว่าบัญชี Twilio ของคุณมีหมายเลขที่รองรับ SMS
3. ตรวจสอบ logs ของ Hermes gateway สำหรับข้อผิดพลาดของ Twilio API

Webhook port conflicts

หากพอร์ต 8080 ถูกใช้งานอยู่แล้ว ให้เปลี่ยนพอร์ต:

SMS_WEBHOOK_PORT=3001

อัปเดต webhook URL ใน Twilio Console ให้ตรงกัน

📄 user-guide/messaging/telegram.md

sidebar_position: 1 title: "Telegram" description: "Set up Hermes Agent as a Telegram bot"

การตั้งค่า Telegram

Hermes Agent ทำงานร่วมกับ Telegram ในรูปแบบของ conversational bot ที่มีฟีเจอร์ครบครัน เมื่อเชื่อมต่อแล้ว คุณสามารถแชทกับ agent ของคุณได้จากทุกอุปกรณ์ ส่ง voice memos ที่จะถูก auto-transcribe, รับผลลัพธ์ของ scheduled task, และใช้ agent ใน group chats การเชื่อมต่อนี้สร้างขึ้นบน python-telegram-bot และรองรับ text, voice, images, และ file attachments

ขั้นตอนที่ 1: สร้าง Bot ผ่าน BotFather

บอท Telegram ทุกตัวจำเป็นต้องมี API token ที่ออกโดย @BotFather ซึ่งเป็นเครื่องมือจัดการบอทอย่างเป็นทางการของ Telegram

1. เปิด Telegram และค้นหา @BotFather หรือเยี่ยมชม t.me/BotFather
2. ส่ง /newbot
3. เลือก display name (เช่น "Hermes Agent") - ส่วนนี้สามารถเป็นอะไรก็ได้
4. เลือก username - ส่วนนี้ต้องเป็นเอกลักษณ์และต้องลงท้ายด้วย bot (เช่น my_hermes_bot)
5. BotFather จะตอบกลับด้วย API token ของคุณ ซึ่งมีลักษณะดังนี้:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

:::warning เก็บ bot token ของคุณเป็นความลับ ใครก็ตามที่มี token นี้สามารถควบคุมบอทของคุณได้ หากมีการรั่วไหล ให้ยกเลิกทันทีผ่าน /revoke ใน BotFather :::

ขั้นตอนที่ 2: ปรับแต่ง Bot ของคุณ (ทางเลือก)

คำสั่งเหล่านี้ของ BotFather ช่วยปรับปรุงประสบการณ์ผู้ใช้ คุณสามารถส่งข้อความถึง @BotFather และใช้คำสั่งเหล่านี้:

:::tip สำหรับ /setcommands ชุดคำสั่งเริ่มต้นที่เป็นประโยชน์:

help - แสดงข้อมูลช่วยเหลือ
new - เริ่มการสนทนาใหม่
sethome - กำหนดแชทนี้เป็น home channel

:::

ขั้นตอนที่ 3: โหมดความเป็นส่วนตัว (สำคัญสำหรับกลุ่ม)

บอท Telegram มี โหมดความเป็นส่วนตัว (privacy mode) ซึ่ง เปิดใช้งานโดยค่าเริ่มต้น นี่คือสาเหตุที่พบบ่อยที่สุดของความสับสนเมื่อใช้บอทในกลุ่ม

เมื่อโหมดความเป็นส่วนตัวเปิดอยู่ (ON) บอทของคุณจะเห็นได้เฉพาะ:

• ข้อความที่ขึ้นต้นด้วยคำสั่ง /
• การตอบกลับโดยตรงไปยังข้อความของบอทเอง
• ข้อความบริการ (สมาชิกเข้าร่วม/ออกจากกลุ่ม, ข้อความปักหมุด, ฯลฯ)
• ข้อความในช่อง (channels) ที่บอทเป็นผู้ดูแล (admin)

เมื่อโหมดความเป็นส่วนตัวปิดอยู่ (OFF) บอทจะได้รับทุกข้อความในกลุ่ม

วิธีปิดโหมดความเป็นส่วนตัว

1. ส่งข้อความถึง @BotFather
2. ส่ง /mybots
3. เลือกบอทของคุณ
4. ไปที่ Bot Settings → Group Privacy → Turn off

:::warning คุณต้องลบและเพิ่มบอทกลับเข้าไปในกลุ่มใหม่ หลังจากเปลี่ยนการตั้งค่าความเป็นส่วนตัว Telegram จะแคชสถานะความเป็นส่วนตัวเมื่อบอทเข้าร่วมกลุ่ม และจะไม่อัปเดตจนกว่าบอทจะถูกลบและเพิ่มกลับเข้าไปใหม่ :::

:::tip ทางเลือกในการปิดโหมดความเป็นส่วนตัว: เลื่อนสถานะบอทเป็น group admin บอทที่เป็น admin จะได้รับทุกข้อความเสมอ ไม่ว่าการตั้งค่าความเป็นส่วนตัวจะเป็นอย่างไร และวิธีนี้ช่วยให้คุณไม่ต้องสลับโหมดความเป็นส่วนตัวทั่วโลก :::

ขั้นตอนที่ 4: ค้นหา User ID ของคุณ

Hermes Agent ใช้ Telegram user IDs แบบตัวเลขเพื่อควบคุมการเข้าถึง User ID ของคุณ ไม่ใช่ username ของคุณ - มันเป็นตัวเลขเช่น 123456789

วิธีที่ 1 (แนะนำ): ส่งข้อความถึง @userinfobot - บอทจะตอบกลับด้วย user ID ของคุณทันที

วิธีที่ 2: ส่งข้อความถึง @get_id_bot - เป็นอีกทางเลือกที่เชื่อถือได้

บันทึกตัวเลขนี้ไว้ คุณจะต้องใช้มันสำหรับขั้นตอนต่อไป

ขั้นตอนที่ 5: กำหนดค่า Hermes

Option A: การตั้งค่าแบบโต้ตอบ (แนะนำ)

hermes gateway setup

เมื่อระบบแจ้งให้เลือก ให้เลือก Telegram ตัวช่วย (wizard) จะขอ bot token และ user IDs ที่อนุญาต จากนั้นจะเขียนการตั้งค่าให้คุณ

Option B: การตั้งค่าด้วยตนเอง

เพิ่มสิ่งต่อไปนี้ใน ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # คั่นด้วยเครื่องหมายจุลภาคสำหรับผู้ใช้หลายคน

เริ่มต้น Gateway

hermes gateway

บอทควรจะออนไลน์ภายในไม่กี่วินาที ส่งข้อความถึงบอทบน Telegram เพื่อตรวจสอบ

การส่งไฟล์ที่สร้างขึ้นจาก Terminals ที่ใช้ Docker-backed

หาก backend terminal ของคุณคือ docker โปรดทราบว่าไฟล์แนบของ Telegram จะถูกส่งโดย gateway process ไม่ใช่จากภายใน container นั่นหมายความว่า path สุดท้าย MEDIA:/... จะต้องสามารถอ่านได้บน host ที่ gateway กำลังทำงานอยู่

ข้อผิดพลาดที่พบบ่อย:

• agent เขียนไฟล์ภายใน Docker ไปที่ /workspace/report.txt
• model ปล่อย MEDIA:/workspace/report.txt
• การส่งมอบของ Telegram ล้มเหลวเนื่องจาก /workspace/report.txt มีอยู่ภายใน container เท่านั้น ไม่ได้อยู่บน host

รูปแบบที่แนะนำ:

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

จากนั้น:

• เขียนไฟล์ภายใน Docker ไปที่ /output/...
• ปล่อย path ที่ มองเห็นได้จาก host ใน MEDIA:, ตัวอย่างเช่น: MEDIA:/home/user/.hermes/cache/documents/report.txt

หากคุณมีส่วน docker_volumes: อยู่แล้ว ให้เพิ่ม mount ใหม่ในรายการเดียวกัน YAML duplicate keys จะเขียนทับค่าก่อนหน้าโดยไม่แจ้งเตือน

Webhook Mode

โดยค่าเริ่มต้น Hermes เชื่อมต่อกับ Telegram โดยใช้ long polling - gateway จะทำการร้องขอขาออกไปยังเซิร์ฟเวอร์ของ Telegram เพื่อดึงข้อมูลอัปเดตใหม่ วิธีนี้ทำงานได้ดีสำหรับการติดตั้งแบบ local และ always-on

สำหรับ cloud deployments (Fly.io, Railway, Render, ฯลฯ) webhook mode จะมีประสิทธิภาพด้านต้นทุนมากกว่า แพลตฟอร์มเหล่านี้สามารถปลุกเครื่องที่หยุดทำงานด้วยตนเองได้เมื่อมี inbound HTTP traffic แต่ไม่สามารถทำได้สำหรับการเชื่อมต่อขาออก เนื่องจาก polling เป็นขาออก บอทที่ใช้ polling จึงไม่สามารถเข้าสู่โหมด sleep ได้เลย Webhook mode จะเปลี่ยนทิศทาง - Telegram จะผลักดันการอัปเดตไปยัง HTTPS URL ของบอทของคุณ ทำให้สามารถใช้งานแบบ sleep-when-idle ได้

การตั้งค่า

เพิ่มสิ่งต่อไปนี้ใน ~/.hermes/.env:

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
# TELEGRAM_WEBHOOK_PORT=8443        # optional, default 8443
# TELEGRAM_WEBHOOK_SECRET=mysecret  # optional, recommended

เมื่อตั้งค่า TELEGRAM_WEBHOOK_URL แล้ว gateway จะเริ่ม webhook server แบบ HTTP แทนการ polling เมื่อไม่ได้ตั้งค่า จะใช้โหมด polling - ไม่มีพฤติกรรมเปลี่ยนแปลงจากเวอร์ชันก่อนหน้า

ตัวอย่างการติดตั้งบน Cloud (Fly.io)

1. เพิ่ม env vars ไปยัง Fly.io app secrets ของคุณ:

fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)

1. เปิดเผย webhook port ใน fly.toml ของคุณ:

[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

1. Deploy:

fly deploy

log ของ gateway ควรแสดง: [telegram] Connected to Telegram (webhook mode)

Proxy Support

หาก API ของ Telegram ถูกบล็อก หรือคุณต้องการส่งทราฟฟิกผ่าน proxy ให้ตั้งค่า proxy URL เฉพาะสำหรับ Telegram สิ่งนี้จะมีความสำคัญกว่า env vars ทั่วไปอย่าง HTTPS_PROXY / HTTP_PROXY

Option 1: config.yaml (แนะนำ)

telegram:
  proxy_url: "socks5://127.0.0.1:1080"

Option 2: environment variable

TELEGRAM_PROXY=socks5://127.0.0.1:1080

Scheme ที่รองรับ: http://, https://, socks5://

Proxy จะใช้ได้กับทั้งการเชื่อมต่อ Telegram หลักและการขนส่ง IP fallback หากไม่ได้ตั้งค่า proxy เฉพาะสำหรับ Telegram, gateway จะใช้ HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (หรือการตรวจจับ proxy อัตโนมัติของระบบ macOS)

Home Channel

ใช้คำสั่ง /sethome ในแชท Telegram ใดๆ (DM หรือกลุ่ม) เพื่อกำหนดให้เป็น home channel scheduled tasks (cron jobs) จะส่งผลลัพธ์ไปยังช่องนี้

คุณยังสามารถตั้งค่าด้วยตนเองใน ~/.hermes/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

:::tip Group chat IDs เป็นตัวเลขติดลบ (เช่น -1001234567890) ส่วนแชท DM ส่วนตัวของคุณมี ID เดียวกับ user ID ของคุณ :::

Voice Messages

Incoming Voice (Speech-to-Text)

ข้อความเสียงที่คุณส่งบน Telegram จะถูก transcriber โดย STT provider ที่กำหนดค่าไว้ของ Hermes และถูกแทรกเป็นข้อความในบทสนทนา

• local ใช้ faster-whisper บนเครื่องที่รัน Hermes - ไม่ต้องใช้ API key
• groq ใช้ Groq Whisper และต้องใช้ GROQ_API_KEY
• openai ใช้ OpenAI Whisper และต้องใช้ VOICE_TOOLS_OPENAI_KEY

Outgoing Voice (Text-to-Speech)

เมื่อ agent สร้างเสียงผ่าน TTS จะถูกส่งเป็น voice bubbles ของ Telegram แบบ native - คือแบบวงกลมที่เล่นได้ในบรรทัดเดียว

• OpenAI และ ElevenLabs สร้าง Opus แบบ native - ไม่ต้องตั้งค่าเพิ่มเติม
• Edge TTS (provider ฟรีค่าเริ่มต้น) ส่งออก MP3 และต้องใช้ ffmpeg เพื่อแปลงเป็น Opus:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

หากไม่มี ffmpeg เสียงจาก Edge TTS จะถูกส่งเป็นไฟล์เสียงปกติ (ยังเล่นได้ แต่ใช้ player รูปสี่เหลี่ยมแทน voice bubble)

กำหนดค่า TTS provider ใน config.yaml ภายใต้คีย์ tts.provider

Group Chat Usage

Hermes Agent ทำงานใน group chats ของ Telegram โดยมีข้อควรพิจารณาเล็กน้อย:

• Privacy mode กำหนดว่าบอทสามารถเห็นข้อความใดได้ (ดู Step 3)
• TELEGRAM_ALLOWED_USERS ยังคงใช้ได้ — เฉพาะผู้ใช้ที่ได้รับอนุญาตเท่านั้นที่สามารถกระตุ้นบอทได้ แม้ในกลุ่ม
• คุณสามารถป้องกันไม่ให้บอทตอบสนองต่อการพูดคุยทั่วไปในกลุ่มได้ด้วย telegram.require_mention: true
• เมื่อใช้ telegram.require_mention: true, ข้อความในกลุ่มจะถูกยอมรับเมื่อ:
  • เป็น slash commands
  • การตอบกลับไปยังข้อความของบอท
  • การกล่าวถึง @botusername
  • ตรงกับ regex wake words ที่คุณกำหนดไว้ใน telegram.mention_patterns
• ใช้ telegram.ignored_threads เพื่อให้ Hermes เงียบในหัวข้อฟอรัม (forum topics) เฉพาะของ Telegram แม้ว่ากลุ่มจะอนุญาตให้ตอบกลับได้อิสระหรือตอบกลับจากการกล่าวถึงก็ตาม
• หาก telegram.require_mention ไม่ได้ถูกตั้งค่าหรือเป็น false, Hermes จะคงพฤติกรรม open-group เดิมและตอบสนองต่อข้อความกลุ่มปกติที่มันมองเห็น

ตัวอย่างการกำหนดค่าการกระตุ้นในกลุ่ม

เพิ่มสิ่งนี้ใน ~/.hermes/config.yaml:

telegram:
  require_mention: true
  mention_patterns:
    - "^\\s*chompy\\b"
  ignored_threads:
    - 31
    - "42"

ตัวอย่างนี้อนุญาตให้มีการกระตุ้นแบบตรงตามปกติทั้งหมด รวมถึงข้อความที่ขึ้นต้นด้วย chompy แม้ว่าข้อความนั้นจะไม่ได้ใช้ @mention ก็ตาม ข้อความในหัวข้อ Telegram 31 และ 42 จะถูกละเว้นเสมอก่อนที่การตรวจสอบ mention และ free-response จะทำงาน

หมายเหตุเกี่ยวกับ mention_patterns

• Patterns ใช้ Python regular expressions
• การจับคู่ไม่คำนึงถึงตัวพิมพ์เล็ก-ใหญ่ (case-insensitive)
• Patterns จะถูกตรวจสอบกับทั้งข้อความและคำบรรยายของสื่อ (media captions)
• รูปแบบ regex ที่ไม่ถูกต้องจะถูกละเว้นพร้อมคำเตือนใน gateway logs แทนที่จะทำให้บอทล่ม
• หากคุณต้องการให้ pattern จับคู่เฉพาะตอนต้นของข้อความ ให้ใช้ ^ เป็นตัวยึด (anchor)

Private Chat Topics (Bot API 9.4)

Telegram Bot API 9.4 (กุมภาพันธ์ 2026) ได้แนะนำ Private Chat Topics - บอทสามารถสร้างหัวข้อแบบฟอรัม (forum-style topic threads) ได้โดยตรงในแชท DM แบบ 1-on-1 ไม่จำเป็นต้องเป็น supergroup สิ่งนี้ช่วยให้คุณสามารถรัน workspace ที่แยกกันหลายส่วนภายใน DM ที่มีอยู่กับ Hermes

Use case

หากคุณทำงานในหลายโปรเจกต์ที่ต้องใช้เวลานาน หัวข้อจะรักษาบริบทของตัวเอง:

• Topic "Website" - ทำงานกับบริการเว็บ production ของคุณ
• Topic "Research" - ทบทวนวรรณกรรมและการสำรวจเอกสาร
• Topic "General" - งานทั่วไปและคำถามสั้นๆ

แต่ละหัวข้อจะได้รับ session, history, และ context ของตัวเอง - แยกออกจากส่วนอื่นโดยสมบูรณ์

Configuration

:::caution Prerequisites ก่อนเพิ่มหัวข้อใน config, ผู้ใช้ต้อง เปิดใช้งาน Topics mode ในแชท DM กับบอท:

1. เปิดแชทส่วนตัวของคุณกับบอท Hermes ใน Telegram
2. แตะที่ชื่อบอทด้านบนเพื่อเปิดข้อมูลแชท
3. เปิดใช้งาน Topics (สวิตช์เพื่อเปลี่ยนแชทให้เป็นฟอรัม)

หากไม่ทำเช่นนี้ Hermes จะบันทึก The chat is not a forum เมื่อเริ่มต้น และข้ามการสร้างหัวข้อ นี่คือการตั้งค่าฝั่ง client ของ Telegram - บอทไม่สามารถเปิดใช้งานได้ด้วยโปรแกรม

เพิ่มหัวข้อภายใต้ platforms.telegram.extra.dm_topics ใน ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # User ID ของ Telegram ของคุณ
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              # โหลด skill อัตโนมัติในหัวข้อนี้

Fields:

How it works

1. เมื่อ gateway เริ่มต้น, Hermes จะเรียกใช้ createForumTopic สำหรับแต่ละหัวข้อที่ยังไม่มี thread_id
2. thread_id จะถูกบันทึกกลับไปยัง config.yaml โดยอัตโนมัติ - การรีสตาร์ทครั้งต่อไปจะข้าม API call นี้
3. แต่ละหัวข้อจะแมปกับ session key ที่แยกกัน: agent:main:telegram:dm:{chat_id}:{thread_id}
4. ข้อความในแต่ละหัวข้อมี history, memory flush, และ context ของตัวเอง

Skill binding

หัวข้อที่มีฟิลด์ skill จะโหลด skill นั้นโดยอัตโนมัติเมื่อเริ่ม session ใหม่ในหัวข้อนี้ วิธีนี้ทำงานเหมือนกับการพิมพ์ /skill-name ตั้งแต่ต้นการสนทนา - เนื้อหาของ skill จะถูกแทรกในข้อความแรก และข้อความถัดไปจะเห็นมันใน history ของการสนทนา

ตัวอย่างเช่น หัวข้อที่มี skill: arxiv จะมี arxiv skill โหลดไว้ล่วงหน้าทุกครั้งที่ session ของมันรีเซ็ต (เนื่องจาก idle timeout, daily reset, หรือ /reset ด้วยตนเอง)

:::tip หัวข้อที่สร้างภายนอก config (เช่น การเรียก Telegram API ด้วยตนเอง) จะถูกค้นพบโดยอัตโนมัติเมื่อมี service message forum_topic_created เข้ามา คุณยังสามารถเพิ่มหัวข้อใน config ขณะที่ gateway กำลังทำงานอยู่ - มันจะถูกรับใน cache miss ครั้งถัดไป :::

Group Forum Topic Skill Binding

Supergroups ที่เปิดใช้งาน Topics mode (หรือที่เรียกว่า "forum topics") มีการแยก session ต่อหัวข้ออยู่แล้ว - แต่คุณอาจต้องการ auto-load a skill เมื่อมีข้อความเข้ามาในหัวข้อกลุ่มเฉพาะ เหมือนกับที่การผูก skill ของหัวข้อ DM ทำงาน

Use case

Supergroup ของทีมที่มีหัวข้อฟอรัมสำหรับสายงานที่แตกต่างกัน:

• หัวข้อ Engineering → โหลด software-development skill อัตโนมัติ
• หัวข้อ Research → โหลด arxiv skill อัตโนมัติ
• หัวข้อ General → ไม่มี skill, ผู้ช่วยทั่วไป

Configuration

เพิ่ม topic bindings ภายใต้ platforms.telegram.extra.group_topics ใน ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890       # Supergroup ID
        topics:
        - name: Engineering
          thread_id: 5
          skill: software-development
        - name: Research
          thread_id: 12
          skill: arxiv
        - name: General
          thread_id: 1
          # ไม่มี skill — วัตถุประสงค์ทั่วไป

Fields:

How it works

1. เมื่อมีข้อความเข้ามาใน group topic ที่แมปไว้, Hermes จะค้นหา chat_id และ thread_id ใน group_topics config
2. หากรายการที่ตรงกันมีฟิลด์ skill, skill นั้นจะถูกโหลดอัตโนมัติสำหรับ session - เหมือนกับการผูก skill ของหัวข้อ DM
3. หัวข้อที่ไม่มีคีย์ skill จะมีการแยก session เท่านั้น (พฤติกรรมเดิม, ไม่เปลี่ยนแปลง)
4. ค่า thread_id หรือ chat_id ที่ไม่ได้แมปจะถูกละเว้นอย่างเงียบๆ - ไม่มี error, ไม่มี skill

Differences from DM Topics

:::tip ในการค้นหา thread_id ของหัวข้อ, เปิดหัวข้อใน Telegram Web หรือ Desktop และดูที่ URL: https://t.me/c/1234567890/5 - ตัวเลขสุดท้าย (5) คือ thread_id สำหรับ supergroups, chat_id คือ group ID ที่ขึ้นต้นด้วย -100 (เช่น group 1234567890 กลายเป็น -1001234567890) :::

Recent Bot API Features

• Bot API 9.4 (ก.พ. 2026): Private Chat Topics - บอทสามารถสร้างหัวข้อฟอรัมในแชท DM แบบ 1-on-1 ผ่าน createForumTopic ดู Private Chat Topics ด้านบน
• Privacy policy: Telegram กำหนดให้บอทต้องมีนโยบายความเป็นส่วนตัวแล้ว ตั้งค่าผ่าน BotFather ด้วย /setprivacy_policy หรือ Telegram อาจสร้าง placeholder อัตโนมัติ สิ่งนี้สำคัญเป็นพิเศษหากบอทของคุณเป็นสาธารณะ
• Message streaming: Bot API 9.x เพิ่มการรองรับการ stream การตอบกลับที่ยาวนาน ซึ่งสามารถปรับปรุง perceived latency สำหรับการตอบกลับของ agent ที่ยาวนาน

Interactive Model Picker

เมื่อคุณส่ง /model โดยไม่มี argument ในแชท Telegram, Hermes จะแสดง inline keyboard แบบโต้ตอบสำหรับการสลับ models:

1. Provider selection - ปุ่มที่แสดงผู้ให้บริการแต่ละรายพร้อมจำนวน models (เช่น "OpenAI (15)", "✓ Anthropic (12)" สำหรับ provider ปัจจุบัน)
2. Model selection - รายการ models แบบ paginated พร้อมการนำทาง Prev/Next, ปุ่ม Back เพื่อกลับไปยัง providers, และ Cancel

model และ provider ปัจจุบันจะแสดงที่ด้านบน การนำทางทั้งหมดเกิดขึ้นโดยการแก้ไขข้อความเดียวกันในที่เดิม (ไม่มีความยุ่งเหยิงในแชท)

:::tip หากคุณทราบชื่อ model ที่แน่นอน, ให้พิมพ์ /model <name> โดยตรงเพื่อข้าม picker คุณยังสามารถพิมพ์ /model <name> --global เพื่อคงการเปลี่ยนแปลงข้าม session ได้ :::

DNS-over-HTTPS Fallback IPs

ในเครือข่ายที่จำกัดบางแห่ง, api.telegram.org อาจ resolve ไปยัง IP ที่ไม่สามารถเข้าถึงได้ ตัว adapter ของ Telegram มีกลไก fallback IP ที่พยายามเชื่อมต่อกับ IP ทางเลือกโดยอัตโนมัติโดยยังคงรักษา hostname และ SNI ของ TLS ที่ถูกต้อง

How it works

1. หากตั้งค่า TELEGRAM_FALLBACK_IPS, IP เหล่านั้นจะถูกใช้โดยตรง
2. มิฉะนั้น, adapter จะสอบถาม Google DNS และ Cloudflare DNS โดยอัตโนมัติผ่าน DNS-over-HTTPS (DoH) เพื่อค้นหา IP ทางเลือกสำหรับ api.telegram.org
3. IP ที่ส่งคืนโดย DoH ที่แตกต่างจากผลลัพธ์ DNS ของระบบจะถูกใช้เป็น fallback
4. หาก DoH ถูกบล็อกด้วย, IP seed ที่กำหนดไว้ล่วงหน้า (149.154.167.220) จะถูกใช้เป็นทางเลือกสุดท้าย
5. เมื่อ fallback IP สำเร็จ, มันจะกลายเป็น "sticky" - การร้องขอครั้งต่อไปจะใช้มันโดยตรงโดยไม่ต้องพยายามเส้นทางหลักก่อน

Configuration

# Explicit fallback IPs (comma-separated)
TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221

หรือใน ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      fallback_ips:
        - "149.154.167.220"

:::tip โดยปกติคุณไม่จำเป็นต้องกำหนดค่านี้ด้วยตนเอง การค้นหาอัตโนมัติผ่าน DoH จัดการสถานการณ์เครือข่ายที่จำกัดส่วนใหญ่แล้ว env var TELEGRAM_FALLBACK_IPS จำเป็นเฉพาะเมื่อ DoH ถูกบล็อกในเครือข่ายของคุณเท่านั้น :::

Proxy Support

หากเครือข่ายของคุณต้องการ HTTP proxy เพื่อเข้าถึงอินเทอร์เน็ต (พบบ่อยในสภาพแวดล้อมองค์กร), ตัว Telegram adapter จะอ่านตัวแปร environment proxy มาตรฐานและกำหนดเส้นทางการเชื่อมต่อทั้งหมดผ่าน proxy

Supported variables

adapter จะตรวจสอบตัวแปร environment เหล่านี้ตามลำดับ โดยใช้ตัวแรกที่ถูกตั้งค่า:

1. HTTPS_PROXY
2. HTTP_PROXY
3. ALL_PROXY
4. https_proxy / http_proxy / all_proxy (variants ตัวพิมพ์เล็ก)

Configuration

ตั้งค่า proxy ใน environment ของคุณก่อนเริ่ม gateway:

export HTTPS_PROXY=http://proxy.example.com:8080
hermes gateway

หรือเพิ่มใน ~/.hermes/.env:

HTTPS_PROXY=http://proxy.example.com:8080

Proxy จะใช้ได้กับทั้ง primary transport และ all fallback IP transports ไม่จำเป็นต้องมีการตั้งค่า Hermes เพิ่มเติม - หาก env variable ถูกตั้งค่า, มันจะถูกใช้โดยอัตโนมัติ

:::note ส่วนนี้ครอบคลุมชั้นการขนส่ง fallback ที่กำหนดเองที่ Hermes ใช้สำหรับการเชื่อมต่อ Telegram client มาตรฐาน httpx ที่ใช้ในส่วนอื่น ๆ อยู่แล้วเคารพ proxy env vars โดยธรรมชาติ :::

Message Reactions

บอทสามารถเพิ่ม emoji reactions ให้กับข้อความเพื่อเป็น feedback การประมวลผลด้วยภาพ:

• 👀 เมื่อบอทเริ่มประมวลผลข้อความของคุณ
• ✅ เมื่อการตอบกลับถูกส่งมอบสำเร็จ
• ❌ หากเกิดข้อผิดพลาดระหว่างการประมวลผล

Reactions ถูกปิดใช้งานโดยค่าเริ่มต้น เปิดใช้งานใน config.yaml:

telegram:
  reactions: true

หรือผ่าน environment variable:

TELEGRAM_REACTIONS=true

:::note ต่างจาก Discord (ที่ reactions เป็นแบบ additive), Telegram's Bot API จะแทนที่ reactions ทั้งหมดของบอทในการเรียกครั้งเดียว การเปลี่ยนจาก 👀 เป็น ✅/❌ เกิดขึ้นแบบ atomic - คุณจะไม่เห็นทั้งสองอย่างพร้อมกัน :::

:::tip หากบอทไม่มีสิทธิ์ในการเพิ่ม reactions ในกลุ่ม, การเรียก reaction จะล้มเหลวอย่างเงียบๆ และการประมวลผลข้อความจะดำเนินต่อไปตามปกติ :::

Per-Channel Prompts

กำหนด system prompts ชั่วคราวให้กับกลุ่มหรือหัวข้อฟอรัม Telegram เฉพาะ Prompt จะถูกแทรกใน runtime ในทุกรอบ - ไม่เคยถูกบันทึกใน transcript history - ดังนั้นการเปลี่ยนแปลงจึงมีผลทันที

telegram:
  channel_prompts:
    "-1001234567890": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "42":  |
      This topic is for creative writing feedback. Be warm and
      constructive.

Keys คือ chat IDs (กลุ่ม/supergroups) หรือ forum topic IDs สำหรับกลุ่มฟอรัม, topic-level prompts จะแทนที่ group-level prompt:

• ข้อความใน topic 42 ภายในกลุ่ม -1001234567890 → ใช้ prompt ของ topic 42
• ข้อความใน topic 99 (ไม่มีรายการชัดเจน) → ย้อนกลับไปใช้ prompt ของกลุ่ม -1001234567890
• ข้อความในกลุ่มที่ไม่มีรายการ → ไม่มีการใช้ channel prompt

Numeric YAML keys จะถูก normalize เป็น strings โดยอัตโนมัติ

Troubleshooting

Exec Approval

เมื่อ agent พยายามรันคำสั่งที่อาจเป็นอันตราย, มันจะขอการอนุมัติจากคุณในแชท:

⚠️ คำสั่งนี้อาจเป็นอันตราย (recursive delete). ตอบ "yes" เพื่ออนุมัติ

ตอบ "yes"/"y" เพื่ออนุมัติ หรือ "no"/"n" เพื่อปฏิเสธ

Security

:::warning ควรตั้งค่า TELEGRAM_ALLOWED_USERS เสมอ เพื่อจำกัดว่าใครสามารถโต้ตอบกับบอทของคุณได้ หากไม่มีสิ่งนี้, gateway จะปฏิเสธผู้ใช้ทั้งหมดโดยค่าเริ่มต้นเพื่อความปลอดภัย :::

ห้ามแชร์ bot token ของคุณสู่สาธารณะเด็ดขาด หากถูกบุกรุก, ให้ยกเลิกทันทีผ่านคำสั่ง /revoke ของ BotFather

สำหรับรายละเอียดเพิ่มเติม, ดู Security documentation คุณยังสามารถใช้ DM pairing สำหรับแนวทางที่ยืดหยุ่นกว่าในการอนุญาตผู้ใช้