httpsms README

The project's README from github.com/NdoleStudio/httpsms. As one markdown file: README.md.

httpSMS

Web API GitHub contributors GitHub license Contributor Covenant Scrutinizer Code Quality Better Stack Badge Greptile: The War on Bugs Sponsors Discord

httpSMS is a service that lets you use your Android phone as an SMS Gateway to send and receive SMS messages. You make a request to a simple HTTP API and it triggers your Android phone to send an SMS. SMS messages received on your android phone can also be forwarded to your webhook endpoint.

Quick Start Guide 👉 https://docs.httpsms.com

header

Table Of Contents

Why?

I'm originally from Cameroon and I wanted an automated way to send and receive SMS messages using an API. Unfortunately many countries don't support the ability to buy virtual phone numbers, and I could not find a good ready-made solution that could help me send/receive SMS messages using a mobile phone using an intuitive http API.

Web UI

The web interface https://httpsms.com is built using Nuxt and Vuetify. It is hosted as a single page application on firebase. The source code is in the web directory

API

The API https://api.httpsms.com is built using Fiber, Go and CockroachDB for the database. It runs as a serverless application on Google Cloud Run. The API documentation can be found here https://api.httpsms.com/index.html

// Sending an SMS Message using Go
client := htpsms.New(htpsms.WithAPIKey(/* API Key from https://httpsms.com/settings */))

client.Messages.Send(context.Background(), &httpsms.MessageSendParams{
    Content: "This is a sample text message",
    From:    "+18005550199",
    To:      "+18005550100",
})

Android App

The Android App is a native application built using Kotlin with material design principles. This app must be installed on an Android phone before you can start sending and receiving SMS messages.

Get it on GitHub

Chat/forum

There are a few ways to get in touch with me and/or the rest of the community. Feel free to use any of these methods. Whatever works best for you:

Features

End-to-end Encryption

You can encrypt your messages end-to-end using the military grade AES-256 encryption algorithm. Your encryption key is stored only on our mobile phone so the even the server won't have any way to view the content of your SMS messages which are sent and received on your Android phone.

Webhook

If you want to build advanced integrations, we support webhooks. The httpSMS platform can forward SMS messages received on the android phone to your server using a callback URL which you provide.

Back Pressure

In-order not to abuse the SMS API on android, you can set a rate limit e.g 3 messages per minute. Such that even if you call the API to send messages to 100 people, It will only send the messages at a rate of 3 messages per minute.

Message Expiration

Sometimes it happens that the phone doesn't get the push notification in time and I can't send the SMS message. It is possible to set a timeout for which a message is valid and if a message becomes expired after the timeout elapses, you will be notified.

API Clients

Flows

Sending an SMS Message

sequenceDiagram
User->>+httpSMS API: Call /v1/messages/send API
httpSMS API-->>+Push Queue: Schedule notification about new message
httpSMS API-->>-User: Respond with 202 (Accepted)
Push Queue-->>+httpSMS API: [Async] Send notification request
httpSMS API-->>-Android App: Send push notification about new message
Android App-->>httpSMS API: [Async] Fetch message
Android App-->>Android App: Send Message using Android SMS API
Android App-->>httpSMS API: [Async] Send result of sending SMS
Android App-->>httpSMS API: [Async] Send Delivery Report

Self Host Setup - Docker

1. Setup Firebase

const firebaseConfig = {
  apiKey: "AIzaSyAKqPvj51igvvNNcRtxxxxx",
  authDomain: "httpsms-docker.firebaseapp.com",
  projectId: "httpsms-docker",
  storageBucket: "httpsms-docker.appspot.com",
  messagingSenderId: "668063041624",
  appId: "1:668063041624:web:29b9e3b702796xxxx",
  measurementId: "G-18VRYL2xxxx",
};

2. Setup SMTP Email service

The httpSMS application uses SMTP to send emails to users e.g. when your Android phone has been offline for a long period of time. You can use a service like mailtrap to create an SMTP server for development purposes.

3. Setup Cloudflare Turnstile

The message search route (/v1/messages/search) is protected by a Cloudflare Turnstile captcha to prevent abuse. You need to set up a Turnstile widget for the search messages feature to work.

  1. Go to the Cloudflare dashboard and navigate to Turnstile.
  2. Add a new site and configure it for your self-hosted domain (e.g., localhost for local development).
  3. Note down the Site Key and Secret Key — you will need them for the frontend and backend environment variables respectively.

4. Download the code

Clone the httpSMS GitHub repository

git clone https://github.com/NdoleStudio/httpsms.git

5. Setup the environment variables

cp web/.env.docker web/.env

FIREBASE_API_KEY=
FIREBASE_AUTH_DOMAIN=
FIREBASE_PROJECT_ID=
FIREBASE_STORAGE_BUCKET=
FIREBASE_MESSAGING_SENDER_ID=
FIREBASE_APP_ID=
FIREBASE_MEASUREMENT_ID=

# Cloudflare Turnstile site key from step 3
CLOUDFLARE_TURNSTILE_SITE_KEY=

cp api/.env.docker api/.env

# SMTP email server settings
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_HOST=
SMTP_PORT=

# Firebase service account credentials
FIREBASE_CREDENTIALS=

# This is the `projectId` from your firebase web config
GCP_PROJECT_ID=

# Cloudflare Turnstile secret key from step 3
CLOUDFLARE_TURNSTILE_SECRET_KEY=

6. Build and Run

docker compose up --build

7. Create the System User

[!IMPORTANT] Restart your API docker container after modifying EVENTS_QUEUE_USER_ID, and EVENTS_QUEUE_USER_API_KEY in your .env file so that the httpSMS API can pick up the changes.

8. Build the Android App.

Integration Testing

The project includes end-to-end integration tests that validate the complete SMS send/receive lifecycle. Tests run the full stack (API, PostgreSQL, Redis) in Docker alongside a phone emulator that simulates an Android device.

📖 Full documentation: tests/README.md

Quick run:

cd tests
bash generate-firebase-credentials.sh
export FIREBASE_CREDENTIALS=$(jq -c . firebase-credentials.json)
docker compose up -d --build --wait
docker compose wait seed && sleep 2
go test -v -timeout 120s ./...
docker compose down -v

Integration tests also run automatically in CI on every push/PR to main.

License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3 - see the LICENSE file for details

httpsms (NdoleStudio/httpsms)

Searching Database…

6K ·GitHub
Httpsms
Что это?httpSMS превращает телефон на Android в SMS-шлюз: вы вызываете простой HTTP API, и он заставляет телефон отправить сообщение, а входящие SMS на телефоне можно пересылать на ваш webhook.
Это облачный сервис или то, что я размещаю сам?Это стек для самостоятельного размещения (API на Go, веб-интерфейс, Postgres, Redis), запускаемый через Docker Compose, плюс Android-приложение, которое непосредственно отправляет SMS.
Как запустить self-hosted-версию?Склонируйте репозиторий, настройте Firebase (для push-уведомлений на телефон), SMTP-службу и Cloudflare Turnstile, заполните файлы .env для каталогов web и api, затем запустите docker-compose.yml, создайте системного пользователя в базе и напоследок соберите Android-приложение в Android Studio со своим google-services.json.
Какие внешние сервисы нужны перед самостоятельным размещением?Нужны проект Firebase (для push-уведомлений Cloud Messaging и аутентификации), SMTP-сервер для транзакционных писем и сайт Cloudflare Turnstile для капчи на эндпоинте поиска.
Телефон всегда отправляет сообщения сразу?Нет — доставка зависит от того, получит ли телефон push-уведомление вовремя, поэтому README рекомендует задать таймаут истечения сообщения, чтобы узнать о сбое, а не ждать вечно.
Видит ли сервер содержимое моих сообщений?Если включить сквозное шифрование, сообщения шифруются AES-256, а ключ остаётся только на вашем телефоне, поэтому сервер не может прочитать содержимое SMS.
Можно ли управлять скоростью отправки SMS?Да, можно задать ограничение скорости, например 3 сообщения в минуту (back pressure), тогда даже массовые API-вызовы на 100 получателей будут урезаны до этого темпа.
Есть ли клиентские библиотеки для вызова API?Да, официальные API-клиенты есть для Go и JavaScript/TypeScript.
Куда попадают данные полученных SMS?Входящие SMS на Android-телефоне можно пересылать на webhook/callback URL, настроенный на вашем собственном сервере.
Можно ли протестировать весь цикл отправки/получения перед развёртыванием?Да, в проекте есть сквозные интеграционные тесты, которые поднимают полный стек API, PostgreSQL и Redis в Docker вместе с эмулятором телефона; в CI они тоже запускаются автоматически.
What are similar projects?rankme.fast, goclaw, sentio, open-im-server, centrifugo, taskview-community, casdoor, appwrite
Which topics is it in?sms-api, sms, firebase, end-to-end-encryption, webhooks, messaging, android-app, redis, encryption, agpl, postgresql, docker-compose
Creator
NdoleStudio
Size
42.9 MB
Stars
6K
Updated
CommitOct 06Releasev1.2.1Aug 23
Age
4y
Commits · 90 Days