Receiving messages

How inbound SMS is routed by shortcode and the exact JSON payload your webhook receives.

Receiving messages#

When someone sends an SMS to the Hep.gg number, the message is routed to your account by a shortcode and stored. If you have configured a webhook, the message is also pushed to your server in real time. To read stored inbound messages over the API instead, see Listing inbound messages.

Shortcode routing#

The first word of every inbound text is treated as the shortcode (lowercased) and selects which account the message belongs to. The remaining words become the message content.

ORDER large pepperoni
└─┬─┘ └───────┬───────┘
shortcode   content ("large pepperoni")

• The shortcode match is case-insensitive (the first word is lowercased before lookup).
• A message that is only a shortcode with no following words is valid; the content is then empty.
• If the shortcode does not match any account, the sender receives an automatic reply: The shortcode <code> does not exist. Please include it as the first word of your message. The message is still stored, but with no owner.

Multiple shortcodes#

You can register more than one shortcode, and each routes to its own webhook, so a single account can run separate inbound flows (for example order and support) side by side.

• Free accounts get 1 shortcode. Hep.gg Prime raises the limit to 5.
• Each shortcode has its own webhook URL and auth secret.
• If a Prime subscription lapses, shortcodes beyond the free limit are deactivated: inbound messages to them are still stored, but they are no longer pushed to their webhook until you resubscribe or remove the extras.

You claim shortcodes and set each webhook in the dashboard under SMS, Shortcodes at hep.gg.

Webhook payload#

If you set a webhook URL for your shortcode, Hep.gg sends a POST to that URL for each matching inbound message.

The request is Content-Type: application/json. There is no Authorization header; the shared secret you configured is delivered inside the JSON body as the auth field. Compare auth against your expected secret to verify the call.

{
  "sender": "+447700900000",
  "auth": "your-configured-webhook-secret",
  "shortcode": "order",
  "messageContent": "large pepperoni"
}

Responding#

Return any 2xx status. Hep.gg records the HTTP status code it receives from your server (visible later on the inbound record as webhook_status) but does not retry on failure and does not require a specific response body. If no webhook is configured for the shortcode, no callback is made and the message is simply stored for you to read via the listing endpoint.

Example receiver#

curl -X POST https://your-server.example.com/sms-webhook \
  -H "Content-Type: application/json" \
  -d '{"sender":"+447700900000","auth":"your-secret","shortcode":"order","messageContent":"large pepperoni"}'

app.post("/sms-webhook", express.json(), (req, res) => {
  const { sender, auth, shortcode, messageContent } = req.body;
 
  if (auth !== process.env.SMS_WEBHOOK_SECRET) {
    return res.status(401).end();
  }
 
  console.log(`[${shortcode}] ${sender}: ${messageContent}`);
  res.sendStatus(200);
});

Inbound messages cost 0 credits.