Skip to main content
Python dependency commands on this page use a PM-prepared source checkout. After a dependency change, reactivate the checkout and restart Mibyan. Mibyan connects to SMS through the Twilio API. People text your Twilio phone number and get AI responses back — same conversational experience as Telegram or Discord, but over standard text messages.
Shared CredentialsThe SMS gateway shares credentials with the optional telephony skill. 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 (free trial available)
  • A Twilio phone number with SMS capability
  • A publicly accessible server — Twilio sends webhooks to your server when SMS arrives
  • aiohttp — cd ~/.mibyan/mibyan-agent && python -c "import pm; pm.sync_venv(['sms'], explicit=True)"

​
Step 1: Get Your Twilio Credentials

  1. Go to the Twilio Console
  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 Mibyan

Select SMS (Twilio) from the platform list. The wizard will prompt for your credentials.

​
Manual setup

Add to ~/.mibyan/.env:

​
Step 3: Configure Twilio Webhook

Twilio needs to know where to send incoming messages. In the Twilio Console:
  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
Exposing Your WebhookIf you’re running Mibyan locally, use a tunnel to expose the webhook:
Set the resulting public URL as your Twilio webhook.
Set SMS_WEBHOOK_URL to the same URL you configured in Twilio. This is required for Twilio signature validation — the adapter will refuse to start without it:
The webhook port defaults to 8080. Override with:

​
Step 4: Start the Gateway

You should see:
If you see Refusing to start: SMS_WEBHOOK_URL is required, set SMS_WEBHOOK_URL to the public URL configured in your Twilio Console (see Step 3). Text your Twilio number — Mibyan will respond via SMS.

​
Environment Variables

​
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

​
Webhook signature validation

Mibyan validates that inbound webhooks genuinely originate from Twilio by verifying the X-Twilio-Signature header (HMAC-SHA1). This prevents attackers from injecting forged messages. SMS_WEBHOOK_URL is required. Set it to the public URL configured in your Twilio Console. The adapter will refuse to start without it. For local development without a public URL, you can disable validation:

​
User allowlists

The gateway denies all users by default. Configure an allowlist:
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 Mibyan gateway logs for Twilio API errors

​
Webhook port conflicts

If port 8080 is already in use, change it:
Update the webhook URL in Twilio Console to match.