Integration - CLI Tool 💻

The SMS Gateway for Android™ offers its own Command Line Interface (CLI), allowing you to integrate it into your processes without writing any code - simply execute CLI commands! 🚀

Installation 📥

The CLI tool can be installed using various methods depending on your operating system and preferences. Choose the installation method that best suits your environment.

curl -LO https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Linux_x86_64.tar.gz
tar -xzf smsgate_Linux_x86_64.tar.gz
chmod +x smsgate
sudo mv smsgate /usr/local/bin/smsgate

curl -LO https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Darwin_arm64.tar.gz
tar -xzf smsgate_Darwin_arm64.tar.gz
chmod +x smsgate
sudo mv smsgate /usr/local/bin/smsgate

Invoke-WebRequest https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Windows_x86_64.zip -OutFile smsgate.zip
Expand-Archive smsgate.zip

go install github.com/android-sms-gateway/cli@latest

docker pull ghcr.io/android-sms-gateway/cli:latest

For a complete list of supported platforms, please refer to the GitHub Releases page.

⚙️ Configuration

The CLI tool can be configured using command-line flags, environment variables, or a .env file in the working directory. This section provides detailed information about configuration options and output formats.

Environment Variables

You can set configuration variables using a .env file:

ASG_ENDPOINT="https://api.sms-gate.app/3rdparty/v1"
ASG_USERNAME="your_username"
ASG_PASSWORD="your_password"

Global Options

The following table summarizes the available command-line options:

Output Formats

The CLI supports three output formats:

1. text: Human-readable text output (default)
2. json: Pretty printed JSON-formatted output
3. raw: One-line JSON-formatted output

🛠️ Usage

smsgate [global options] command [command options] [arguments...]

Commands

The CLI offers three main groups of commands:

• Messages: Commands for sending messages and checking their status.
• Webhooks: Commands for managing webhooks, including creating, updating, and deleting them.
• Logs: Commands for retrieving logs for a specific time range.

For a complete list of available commands, you can run smsgate help or smsgate --help in your terminal.

Exit Codes

The CLI tool uses exit codes to indicate the outcome of operations.

📝 Message Commands

Message commands allow you to send SMS messages and check their status. The following subsections detail each message-related command.

Send a Message

The send command allows you to send a message to one or more phone numbers.

Syntax:

smsgate send [command options] 'Message content'

Options:

Get Message Status

The status command retrieves the status of a message using its ID.

Syntax:

smsgate status 'Message ID'

🔗 Webhook Commands

Webhook commands allow you to manage webhooks for event notifications. The following subsections detail each webhook-related command.

Register Webhook

The register command allows you to register a new webhook.

Syntax:

smsgate webhooks register [options] URL

Options:

List Webhooks

The list command displays all registered webhooks.

Syntax:

smsgate webhooks list

Delete Webhook

The delete command removes a webhook by its ID.

Syntax:

smsgate webhooks delete 'Webhook ID'

📋 Logs Commands

The logs command retrieves logs for a specific time range. Dates should be in RFC3339 format (e.g., 2024-01-15T10:30:00Z).

Syntax:

smsgate logs [options]

Options:

💡 Usage Examples

Sending Messages

# Send a message
smsgate send --phones '+12025550123' 'Hello, Dr. Turk!'

# Send a message to multiple numbers
smsgate send --phones '+12025550123' --phones '+12025550124' 'Hello, doctors!'
# or
smsgate send --phones '+12025550123,+12025550124' 'Hello, doctors!'

Getting Message Status

# Get the status of a sent message
smsgate status zXDYfTmTVf3iMd16zzdBj

Getting Logs

# Get logs for the last 24 hours (default)
smsgate logs

# Get logs for a specific time range
smsgate logs --from '2024-01-15T00:00:00Z' --to '2024-01-15T23:59:59Z'

# Get logs with custom time range and output format
smsgate --format json logs --from '2024-01-15T10:00:00+07:00' --to '2024-01-15T18:00:00+07:00'

Webhook Management

# Register a webhook for received messages
smsgate webhooks register --event 'sms:received' 'https://example.com/webhook'

# List all registered webhooks
smsgate webhooks list

# Delete a webhook
smsgate webhooks delete 'webhook-id'

Using Docker

docker run -it --rm --env-file .env ghcr.io/android-sms-gateway/cli \
  send --phone '+12025550123' 'Hello, Dr. Turk!'

📄 Output Formats

Text

ID: zXDYfTmTVf3iMd16zzdBj
State: Pending
IsHashed: false
IsEncrypted: false
Recipients:
        +12025550123    Pending
        +12025550124    Pending

JSON

{
  "id": "zXDYfTmTVf3iMd16zzdBj",
  "state": "Pending",
  "isHashed": false,
  "isEncrypted": false,
  "recipients": [
    {
      "phoneNumber": "+12025550123",
      "state": "Pending"
    },
    {
      "phoneNumber": "+12025550124",
      "state": "Pending"
    }
  ],
  "states": {}
}

Raw

{"id":"zXDYfTmTVf3iMd16zzdBj","state":"Pending","isHashed":false,"isEncrypted":false,"recipients":[{"phoneNumber":"+12025550123","state":"Pending"},{"phoneNumber":"+12025550124","state":"Pending"}],"states":{}}

📚 See Also

For more information about integrating the SMSGate, explore the following resources:

• CLI Repository
• API Reference