android-sms-gateway-local

Android SMS Gateway (Local)

Use this skill when working with the Android SMS Gateway app in Local Server mode. Keep the flow minimal and confirm missing inputs before calling the API.

Gather Inputs

Ask for any missing details:

• Device local IP and port (default port is 8080)
• Local Server username and password
• Action: send SMS, receive SMS (webhook), export inbox, or check status
• For sending: phone numbers, message text, optional deviceId and simNumber
• For receiving: webhook URL and whether HTTPS is available
• For exporting inbox: deviceId and a time window (since, until)

Connect and Validate

• Base URL for Local Server is http://:.
• Local Server supports Basic Auth only; include credentials in every request.
• Validate connectivity first with GET /health, then list devices with GET /devices.

Send SMS

• Use POST /messages with phoneNumbers and textMessage.text (preferred) or dataMessage if requested.
• Include deviceId or simNumber when the user wants to target a specific device or SIM.
• Use withDeliveryReport: true if the user needs delivery confirmation.

Receive SMS

• Register a webhook with POST /webhooks and event: "sms:received" (optionally scope to a deviceId).
• The webhook receiver must support HTTPS for private IPs unless it is http://127.0.0.1.
• To fetch historical inbox messages, call POST /messages/inbox/export after the webhook is registered.

Status Tracking

• Use GET /messages/{id} to read the message state and other fields.
• Consider also registering sms:sent, sms:delivered, and sms:failed webhooks for near-real-time status updates.

References

• Use {baseDir}/references/api.md for endpoint summaries, payload shapes, and event names.

Scripts

• Use {baseDir}/scripts/health.sh and {baseDir}/scripts/list_devices.sh to verify connectivity.
• Use {baseDir}/scripts/send_sms.sh to send a text message.
• Use {baseDir}/scripts/get_message.sh and {baseDir}/scripts/list_messages.sh to check status.
• Use {baseDir}/scripts/register_webhook.sh, {baseDir}/scripts/list_webhooks.sh, and {baseDir}/scripts/delete_webhook.sh to manage webhooks.
• Use {baseDir}/scripts/export_inbox.sh to replay inbox messages.