---
title: Hep.gg SMS API (LLM)
description: Send outbound SMS and read inbound messages through the Hep.gg SMS service, authed with a per-account token.
---

# Hep.gg SMS API

Send outbound SMS and read inbound messages through the Hep.gg SMS service.
Authentication is a per-account token created on the dashboard
(/dashboard/sms/api-keys).

Base URL: https://sms.hep.gg
Auth: Authorization header set to the raw token (no "Bearer " prefix).

## Endpoints

### POST /api/messages
Send a single SMS.

Form-urlencoded body:
  recipient   string   E.164 phone number (e.g. +14155551212).
  content     string   1-799 chars. Longer messages are split into segments
                       (chunk client-side if you need finer control).

Response: 200 with provider metadata on success, 400/401/403/500 on error.

### GET /api/messages
List the received (inbound) messages for the token's account, newest first.

### GET /
Public service stats (totals). No auth.

## Pricing
  - max(1, ceil(content_length / 160)) credits per message (one credit per
    160-char segment, minimum 1).
  - Top up via the dashboard. Free 1000-credit grant on application approval.

## Inbound
Inbound messages are routed to your account by shortcode (the first word of the
text, lowercased) and can be read with GET /api/messages or delivered to a webhook.
Each shortcode has its own webhook. Webhook delivery is a JSON POST to your URL:
  { "sender": "+E164", "auth": "<your secret>", "shortcode": "order", "messageContent": "..." }
The shared secret arrives in the body as "auth" (no Authorization header). Return
any 2xx; no retries. Inbound costs 0 credits.

## Shortcodes (free 1 / premium 5)
Register multiple shortcodes, each routing to its own webhook. Free accounts get 1,
Hep.gg Prime gets 5. If Prime lapses, shortcodes beyond the free limit are
deactivated (still stored, not pushed to their webhook) until resubscribe. Manage
them in the dashboard under SMS > Shortcodes.

## Hep.gg-side dashboard endpoints (cookie auth - not for programmatic use)
Listed for completeness; programmatic callers use the API above directly.
  GET    /api/v1/sms/account
  POST   /api/v1/sms/auth/rotate
  GET    /api/v1/sms/messages
  GET    /api/v1/sms/credits
  GET    /api/v1/sms/credits/history
  GET    /api/v1/sms/shortcodes
  POST   /api/v1/sms/shortcodes
  PATCH  /api/v1/sms/shortcodes/:id
  DELETE /api/v1/sms/shortcodes/:id