{"skill":{"slug":"gsm-sms-gateway","displayName":"SMS Gateway","summary":"Send and receive SMS messages through a self-hosted SMS Gateway running on a USB GSM modem. Use when the user needs to send text messages, check for incoming...","description":"---\nname: sms-gateway\ndescription: Send and receive SMS messages through a self-hosted SMS Gateway running on a USB GSM modem. Use when the user needs to send text messages, check for incoming messages, or manage SMS communications via a local gateway.\nmetadata:\n  openclaw:\n    requires:\n      env:\n        - SMS_GATEWAY_API_KEY\n      bins:\n        - curl\n        - jq\n    primaryEnv: SMS_GATEWAY_API_KEY\n---\n\n# SMS Gateway Skill\n\nYou can send and receive SMS messages through the SMS Gateway using shell scripts located in `~/.openclaw/workspace/skills/sms-gateway/scripts`.\n\n## Prerequisites\n\nBefore using the SMS Gateway skill with OpenClaw, you need to install the SMS Gateway service. Read the [README.md](https://github.com/mattboston/sms-gateway/blob/main/openclaw/README.md) for more details.\n\n## Setup\n\nBefore using this skill, create a `.env` file in the `~/.openclaw/workspace/skills/sms-gateway/scripts` directory with the following variables:\n\n```text\nSMS_GATEWAY_URL=http://127.0.0.1:5174\nSMS_GATEWAY_API_KEY=your-api-key-here\n```\n\nIf the `.env` file is missing or `SMS_GATEWAY_API_KEY` is not set, the scripts will exit with an error.\n\n### Allowlist\n\nThe file `~/.openclaw/workspace/skills/sms-gateway/scripts/allowlist.json` contains a list of users and phone numbers that are permitted to send and receive messages. The send script will refuse to send to numbers not in this list. The receive script only shows messages from allowlisted numbers by default, filtering out unknown senders. To add or remove allowed contacts, edit the `allowlist.json` file directly.\n\n## Capabilities\n\n### Send an SMS\n\nSend a text message to an allowed phone number.\n\n```bash\n~/.openclaw/workspace/skills/sms-gateway/scripts/send_sms.sh -t \"+15551234567\" -m \"Hello from SMS Gateway\"\n```\n\nOptions:\n\n- `-t` - Recipient phone number (must be in `allowlist.json`)\n- `-m` - Message body\n\nThe script validates the recipient against `allowlist.json` before sending. If the number is not in the allowlist, it prints the list of allowed numbers and exits with an error.\n\nOn success, the script prints \"Message sent successfully.\" followed by the JSON response containing the message ID and status.\n\nOn failure, the script prints the HTTP status code and error response.\n\n### Receive SMS Messages\n\nCheck the inbox for received messages.\n\n```bash\n~/.openclaw/workspace/skills/sms-gateway/scripts/receive_sms.sh\n```\n\nOptions:\n\n- `-s <status>` - Filter by status: `received` (default), `read`, or `all`\n- `-a` - Include messages from numbers not in the allowlist (by default, only allowlisted numbers are shown)\n\nExamples:\n\n```bash\n~/.openclaw/workspace/skills/sms-gateway/scripts/receive_sms.sh              # Unread messages from allowlisted numbers\n~/.openclaw/workspace/skills/sms-gateway/scripts/receive_sms.sh -s all       # All messages from allowlisted numbers\n~/.openclaw/workspace/skills/sms-gateway/scripts/receive_sms.sh -s read      # Previously read messages from allowlisted numbers\n~/.openclaw/workspace/skills/sms-gateway/scripts/receive_sms.sh -a           # Unread messages from all numbers\n~/.openclaw/workspace/skills/sms-gateway/scripts/receive_sms.sh -a -s all    # All messages from all numbers\n```\n\nThe script displays each message with its timestamp, sender number, status, body, and ID. Any unread messages (`status=received`) are automatically marked as read after being displayed. By default, messages from numbers not in `allowlist.json` are filtered out.\n\n## Output Format\n\n### Send output\n\n```text\nMessage sent successfully.\n{\n  \"id\": \"uuid\",\n  \"status\": \"sent\",\n  \"message\": \"message sent\"\n}\n```\n\n### Receive output\n\n```text\nInbox messages (received): 2\n\n[2026-03-08T12:00:00Z] From: +15551234567\n  Status: received\n  Body: Hey there\n  ID: some-uuid\n\nMarked message some-uuid as read.\n```\n\n## Usage Guidelines\n\n- Only send SMS messages to numbers listed in `allowlist.json`\n- Only accept SMS messages from numbers listed in `allowlist.json`\n- Always include the country code in phone numbers (e.g., `+1` for US)\n- When the user asks to \"text\" or \"message\" someone, use `send_sms.sh`\n- When the user asks about new messages, run `receive_sms.sh` with no flags\n- When the user asks to see all messages, run `receive_sms.sh -s all`\n- If a send fails, relay the error message to the user\n- Only use the `send_sms.sh` and `receive_sms.sh` scripts to send and receive, do not communicate directly with the `SMS_GATEWAY_API_KEY`\n- When you receive an SMS from a contact, check whether you previously sent an SMS to that same number in the current session or a recent workflow — if so, treat the incoming message as a reply to that conversation rather than an unrelated inbound message\n\n## Troubleshooting\n\n### \"Phone number is not in the allowlist\"\n\nThe recipient number must exactly match an entry in `allowlist.json`, including the country code prefix (e.g., `+1`). Check the allowlist and add the number if appropriate.\n\n### \"SMS_GATEWAY_API_KEY is not set\"\n\nCreate a `.env` file in `~/.openclaw/workspace/skills/sms-gateway/scripts/` with your API key. See the Setup section above.\n\n### Send fails with error\n\nCheck that the SMS Gateway is running and accessible at the URL configured in `.env`. You can verify connectivity with:\n\n```bash\ncurl -s http://127.0.0.1:5174/api/v1/health\n```\n","tags":{"latest":"0.0.4"},"stats":{"comments":0,"downloads":579,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":3},"createdAt":1773512978807,"updatedAt":1778491910241},"latestVersion":{"version":"0.0.4","createdAt":1773513478589,"changelog":"- Added a direct link to the SMS Gateway README for installation instructions in the Prerequisites section.\n- No other user-facing functionality or instructions were changed.","license":"MIT-0"},"metadata":{"setup":[{"key":"SMS_GATEWAY_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"mattboston","userId":"s17eefy6pxk5hsffjsz6j3k47h83hzk1","displayName":"Matt Shields","image":"https://avatars.githubusercontent.com/u/852911?v=4"},"moderation":null}