> For the complete documentation index, see [llms.txt](https://docs.stopbot.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stopbot.net/v2/service-guides/stopbot-v2/smarturls.md).

# SmartURLs

SmartURLs lets you run short, trackable redirect URLs that can apply STOPBOT visitor analysis before sending a visitor to the final destination.

Use this guide when you want to host your own SmartURLs redirect domain, for example:

```
https://links.example.com/swWV8j
```

The public visitor URL uses your own domain and the SmartURLs `keyname`. Your server-side SmartURLs client then sends the visitor context to STOPBOT V2.

### Recommended Integration

Use one of the official SmartURLs V2 clients:

| Client     | Recommended for                                                                   | Repository                                                                          |
| ---------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Go client  | Production servers, VPS, reverse proxy deployments, high traffic redirect domains | [Stopbot-SmartURLs-V2-Go](https://github.com/stopbot-net/Stopbot-SmartURLs-V2-Go)   |
| PHP client | Shared hosting, Apache/PHP hosting, existing PHP environments                     | [Stopbot-SmartURLs-V2-PHP](https://github.com/stopbot-net/Stopbot-SmartURLs-V2-PHP) |

The Go client is recommended for most production deployments.

### Endpoint Used By The Clients

Both clients call:

```
GET https://api.stopbot.net/services/shorterlink
```

You normally do not need to call this endpoint directly from frontend code. Keep the STOPBOT API key on your server.

### How SmartURLs Works

1. Create a SmartURLs `keyname` in the STOPBOT panel.
2. Deploy the Go or PHP SmartURLs client on your redirect domain.
3. A visitor opens `https://your-domain.example/{keyname}`.
4. The client sends the visitor IP, user agent, URL, and `keyname` to STOPBOT V2.
5. STOPBOT returns a redirect decision.
6. The client redirects the visitor, shows a local error page, or runs JavaScript browser verification first.

### Create A SmartURLs Keyname

1. Sign in to [panel.stopbot.net](https://panel.stopbot.net).
2. Open the SmartURLs or Shortlink section.
3. Create a new SmartURLs key, or open an existing one.
4. Configure the destination URL and protection rules.
5. Copy the SmartURLs `keyname`.

If the panel shows:

```
https://panel.stopbot.net/shortlink-swWV8j
```

the `keyname` is:

```
swWV8j
```

Your public visitor URL becomes:

```
https://your-domain.example/swWV8j
```

Allowed `keyname` characters:

```
A-Z a-z 0-9 . _ -
```

The maximum length is 64 characters.

### Go Client Setup

Clone the Go client:

```bash
git clone https://github.com/stopbot-net/Stopbot-SmartURLs-V2-Go.git
cd Stopbot-SmartURLs-V2-Go
```

Copy the environment example:

```bash
cp .env.example .env
```

Configure `.env`:

```env
STOPBOT_API_KEY=your_api_key
SMARTURLS_ADDR=127.0.0.1:8080
STOPBOT_API_ENDPOINT=https://api.stopbot.net/services/shorterlink
SMARTURLS_SIGNING_KEY=change_this_to_a_long_random_secret_value
SMARTURLS_TRUST_PROXY_HEADERS=true
```

`SMARTURLS_SIGNING_KEY` is a private local secret used to protect browser verification tokens. It is not your STOPBOT API key and does not need to be configured in the STOPBOT panel.

Recommended signing key characters:

```
A-Z a-z 0-9 _ - . @ # %
```

Use at least 32 characters. Avoid spaces and quotes.

Build and run:

```bash
go test ./...
go build -o smarturls .
./smarturls
```

On Windows:

```powershell
go test ./...
go build -o smarturls.exe .
.\smarturls.exe
```

The Go binary embeds the local message template. Rebuild the binary after editing `template/message.html`.

### Go Client With Nginx

Nginx is the recommended reverse proxy for the Go client.

Example Nginx server block:

```nginx
server {
    listen 80;
    server_name your-domain.example;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Use:

```env
SMARTURLS_TRUST_PROXY_HEADERS=true
```

only when the Go application is always behind a trusted reverse proxy and cannot be accessed directly from the internet.

### PHP Client Setup

Clone or download the PHP client:

```bash
git clone https://github.com/stopbot-net/Stopbot-SmartURLs-V2-PHP.git
```

Upload the PHP client files to your SmartURLs domain.

Set the API key through an environment variable:

```bash
STOPBOT_API_KEY=your_api_key
```

Or create `config.local.php` next to `config.php`:

```php
<?php
$StopbotApiKey = 'your_api_key';
$SmartUrlsSigningKey = 'change_this_random_secret';
$SmartUrlsTrustProxyHeaders = true;
```

Do not commit `config.local.php`.

#### Apache

The PHP client includes `.htaccess` rules. A request like:

```
https://your-domain.example/swWV8j
```

is routed internally to:

```
index.php?q=swWV8j
```

#### Nginx

Nginx does not read `.htaccess`, so add a rewrite rule:

```nginx
server {
    listen 80;
    server_name your-domain.example;

    root /var/www/smarturls;
    index index.php;

    location / {
        try_files $uri $uri/ @smarturls;
    }

    location @smarturls {
        rewrite ^/(.*)$ /index.php?q=$1&$args last;
    }

    location ~ \.php$ {
        try_files $fastcgi_script_name =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}
```

Adjust `root` and `fastcgi_pass` for your server.

### Redirect Decision Handling

The SmartURLs clients handle common STOPBOT redirect decisions:

| API value              | Client behavior                  |
| ---------------------- | -------------------------------- |
| valid `redirectTo` URL | Redirects the visitor            |
| `STOPBOTNET 403`       | Shows the local 403 message page |
| `STOPBOTNET 404`       | Shows the local 404 message page |
| empty `redirectTo`     | Shows the local 404 message page |
| `SERVER NOT RESPOND`   | Shows the local 503 message page |
| invalid redirect value | Shows the local 502 message page |

The local message page is included in the client template and can be customized.

The final redirect action must come from `blockAccess` and `redirectTo`, not from `isBot`. `isBot` is only a visitor classification signal. A SmartURLs visitor can be human/non-bot and still receive the blocked redirect when your keyname configuration blocks that request.

Example country restriction response:

```json
{
  "isBot": 0,
  "blockAccess": 1,
  "detectActivity": "BLOCK BY COUNTRY."
}
```

### JavaScript Verification Flow

When JavaScript verification is enabled for a SmartURLs keyname, STOPBOT V2 returns:

```json
{
  "redirectTo": "https://example.com",
  "jsResponse": 1,
  "uniqueCode": "abc123def456"
}
```

The current Go and PHP clients do not expose the API key to the browser. They create a local signed token and render a browser check page.

The browser calls the local client:

```
/rsc/rjs.json?token=...
```

The server verifies the local token, then calls STOPBOT V2 with:

```
apikey={API_KEY}
ip={VISITOR_IP}
keyname={KEYNAME}
js=1
code={uniqueCode}
```

Example API verification request:

```
https://api.stopbot.net/services/shorterlink?apikey={API_KEY}&ip=1.1.1.1&keyname={KEYNAME}&js=1&code={UNIQUE_CODE}
```

Successful verification response:

```json
{
  "AddVisitorStatus": 1,
  "status": "success"
}
```

After verification succeeds, the client redirects the visitor to the destination URL.

### Important Security Notes

* Keep the STOPBOT API key on the server.
* Do not place the API key in browser JavaScript.
* Do not commit `.env` or `config.local.php`.
* Use a long random signing key for browser verification tokens.
* Enable proxy header trust only behind a trusted reverse proxy.
* Make sure the API key belongs to the same STOPBOT account that owns the SmartURLs `keyname`.

### Test Checklist

* Open `https://your-domain.example/{keyname}`.
* Confirm the visitor reaches the expected destination URL.
* Confirm blocked traffic shows the local message page or follows the configured redirect behavior.
* If JavaScript verification is enabled, confirm `/rsc/rjs.json?token=...` returns a successful verification response.
* Check SmartURLs statistics in the STOPBOT panel.
* Confirm the API key is not visible in browser page source or network calls.

### V1 Difference

Legacy SmartURLs V1 used keyname-based JavaScript tracking.

Current SmartURLs V2 uses a `uniqueCode` verification flow:

```
js=1&keyname={KEYNAME}&code={uniqueCode}
```

Use the current Go or PHP V2 client for new integrations.