44d02f35d2
Major reorganization of the documentation site for better discoverability and navigation. 94 pages across 8 top-level sections (was 5). Structural changes: - Promote Features from 3-level-deep subcategory to top-level section with new Overview hub page categorizing all 26 feature pages - Promote Messaging Platforms from User Guide subcategory to top-level section, add platform comparison matrix (13 platforms x 7 features) - Create new Integrations section with hub page, grouping MCP, ACP, API Server, Honcho, Provider Routing, Fallback Providers - Extract AI provider content (626 lines) from configuration.md into dedicated integrations/providers.md — configuration.md drops from 1803 to 1178 lines - Subcategorize Developer Guide into Architecture, Extending, Internals - Rename "User Guide" to "Using Hermes" for top-level items Orphan fixes (7 pages now reachable via sidebar): - build-a-hermes-plugin.md added to Guides - sms.md added to Messaging Platforms - context-references.md added to Features > Core - plugins.md added to Features > Core - git-worktrees.md added to Using Hermes - checkpoints-and-rollback.md added to Using Hermes - checkpoints.md (30-line stub) deleted, superseded by checkpoints-and-rollback.md (203 lines) New files: - integrations/index.md — Integrations hub page - integrations/providers.md — AI provider setup (extracted) - user-guide/features/overview.md — Features hub page Broken link fixes: - quickstart.md, faq.md: update context-length-detection anchors - configuration.md: update checkpoints link - overview.md: fix checkpoint link path Docusaurus build verified clean (zero broken links/anchors).
177 lines
5.1 KiB
Markdown
177 lines
5.1 KiB
Markdown
---
|
|
sidebar_position: 8
|
|
sidebar_label: "SMS (Twilio)"
|
|
title: "SMS (Twilio)"
|
|
description: "Set up Hermes Agent as an SMS chatbot via Twilio"
|
|
---
|
|
|
|
# SMS Setup (Twilio)
|
|
|
|
Hermes connects to SMS through the [Twilio](https://www.twilio.com/) API. People text your Twilio phone number and get AI responses back — same conversational experience as Telegram or Discord, but over standard text messages.
|
|
|
|
:::info Shared Credentials
|
|
The SMS gateway shares credentials with the optional [telephony skill](/docs/reference/skills-catalog). If you've already set up Twilio for voice calls or one-off SMS, the gateway works with the same `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and `TWILIO_PHONE_NUMBER`.
|
|
:::
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- **Twilio account** — [Sign up at twilio.com](https://www.twilio.com/try-twilio) (free trial available)
|
|
- **A Twilio phone number** with SMS capability
|
|
- **A publicly accessible server** — Twilio sends webhooks to your server when SMS arrives
|
|
- **aiohttp** — `pip install 'hermes-agent[sms]'`
|
|
|
|
---
|
|
|
|
## Step 1: Get Your Twilio Credentials
|
|
|
|
1. Go to the [Twilio Console](https://console.twilio.com/)
|
|
2. Copy your **Account SID** and **Auth Token** from the dashboard
|
|
3. Go to **Phone Numbers → Manage → Active Numbers** — note your phone number in E.164 format (e.g., `+15551234567`)
|
|
|
|
---
|
|
|
|
## Step 2: Configure Hermes
|
|
|
|
### Interactive setup (recommended)
|
|
|
|
```bash
|
|
hermes gateway setup
|
|
```
|
|
|
|
Select **SMS (Twilio)** from the platform list. The wizard will prompt for your credentials.
|
|
|
|
### Manual setup
|
|
|
|
Add to `~/.hermes/.env`:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## Step 3: Configure Twilio Webhook
|
|
|
|
Twilio needs to know where to send incoming messages. In the [Twilio Console](https://console.twilio.com/):
|
|
|
|
1. Go to **Phone Numbers → Manage → Active Numbers**
|
|
2. Click your phone number
|
|
3. Under **Messaging → A MESSAGE COMES IN**, set:
|
|
- **Webhook**: `https://your-server:8080/webhooks/twilio`
|
|
- **HTTP Method**: `POST`
|
|
|
|
:::tip Exposing Your Webhook
|
|
If you're running Hermes locally, use a tunnel to expose the webhook:
|
|
|
|
```bash
|
|
# Using cloudflared
|
|
cloudflared tunnel --url http://localhost:8080
|
|
|
|
# Using ngrok
|
|
ngrok http 8080
|
|
```
|
|
|
|
Set the resulting public URL as your Twilio webhook.
|
|
:::
|
|
|
|
The webhook port defaults to `8080`. Override with:
|
|
|
|
```bash
|
|
SMS_WEBHOOK_PORT=3000
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4: Start the Gateway
|
|
|
|
```bash
|
|
hermes gateway
|
|
```
|
|
|
|
You should see:
|
|
|
|
```
|
|
[sms] Twilio webhook server listening on port 8080, from: +1555***4567
|
|
```
|
|
|
|
Text your Twilio number — Hermes will respond via SMS.
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `TWILIO_ACCOUNT_SID` | Yes | Twilio Account SID (starts with `AC`) |
|
|
| `TWILIO_AUTH_TOKEN` | Yes | Twilio Auth Token |
|
|
| `TWILIO_PHONE_NUMBER` | Yes | Your Twilio phone number (E.164 format) |
|
|
| `SMS_WEBHOOK_PORT` | No | Webhook listener port (default: `8080`) |
|
|
| `SMS_ALLOWED_USERS` | No | Comma-separated E.164 phone numbers allowed to chat |
|
|
| `SMS_ALLOW_ALL_USERS` | No | Set to `true` to allow anyone (not recommended) |
|
|
| `SMS_HOME_CHANNEL` | No | Phone number for cron job / notification delivery |
|
|
| `SMS_HOME_CHANNEL_NAME` | No | Display name for the home channel (default: `Home`) |
|
|
|
|
---
|
|
|
|
## SMS-Specific Behavior
|
|
|
|
- **Plain text only** — Markdown is automatically stripped since SMS renders it as literal characters
|
|
- **1600 character limit** — Longer responses are split across multiple messages at natural boundaries (newlines, then spaces)
|
|
- **Echo prevention** — Messages from your own Twilio number are ignored to prevent loops
|
|
- **Phone number redaction** — Phone numbers are redacted in logs for privacy
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
**The gateway denies all users by default.** Configure an allowlist:
|
|
|
|
```bash
|
|
# 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 has no built-in encryption. Don't use SMS for sensitive operations unless you understand the security implications. For sensitive use cases, prefer Signal or Telegram.
|
|
:::
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Messages not arriving
|
|
|
|
1. Check your Twilio webhook URL is correct and publicly accessible
|
|
2. Verify `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` are correct
|
|
3. Check the Twilio Console → **Monitor → Logs → Messaging** for delivery errors
|
|
4. Ensure your phone number is in `SMS_ALLOWED_USERS` (or `SMS_ALLOW_ALL_USERS=true`)
|
|
|
|
### Replies not sending
|
|
|
|
1. Check `TWILIO_PHONE_NUMBER` is set correctly (E.164 format with `+`)
|
|
2. Verify your Twilio account has SMS-capable numbers
|
|
3. Check Hermes gateway logs for Twilio API errors
|
|
|
|
### Webhook port conflicts
|
|
|
|
If port 8080 is already in use, change it:
|
|
|
|
```bash
|
|
SMS_WEBHOOK_PORT=3001
|
|
```
|
|
|
|
Update the webhook URL in Twilio Console to match.
|