HailMe Platform docsOpen cabinet →

Message templates

The TEST cabinet lets a project owner publish SMS, push and TEST Telegram templates. A template binds message text, recipient language, required string parameters and optional push data to an immutable ID. Your backend supplies that ID and parameter values.

Create and publish

  1. Open a TEST project, choose Options and enable Templates.
  2. Open Templates and choose a versioned ID, channel and locale, for example order.approaching.v1 and es-AR.
  3. Write Tu pedido {{orderId}} está cerca.. Set the parameter meaning, maximum length and fictional preview value.
  4. For Telegram, use plain body text and no countries, title or push data. For SMS, set allowed destination ISO country codes. For push, set the title and an optional JSON object of string data, for example {"event":"order.approaching","orderId":"{{orderId}}","schemaVersion":"1"}.
  5. Preview without sending. Check the actual body, data and signature. Publish the immutable TEST version.

Copying an existing template proposes a new ID. Publishing an existing ID with identical content is safe to retry; changing published content returns TEMPLATE_IMMUTABLE. Create a new version instead. Locale selection is exact: publish each translation; there is no silent translation or fallback. Changing a template or policy does not rewrite queued messages.

API and existing JVM SDK

Use POST /v1/notifications with notifications:write. Keep the same idempotency key and identical request after a lost response. Replays preserve the accepted rendered payload, price and notification ID, even after a policy change or template disablement, within the configured idempotency retention period. New sends recheck current permissions, budgets and template availability.

{
  "channel": "SMS",
  "templateId": "order.approaching.v1",
  "locale": "es-AR",
  "recipient": {"phone": "<TEST E.164 phone in an allowed country>"},
  "parameters": {"orderId": "demo-123"},
  "expiresAt": "<UTC instant within 24 hours>",
  "clientReference": "order-demo-123"
}

The published JVM SDK 0.1.0-dev.3 already supports this contract through CreateSmsNotification / CreatePushNotification. Use client.createSms(request, persistedIdempotencyKey) or client.createPush(...). No ZIP or new SDK version is needed for template parameters. A push recipient uses {"installationId":"<TEST UUID>"}. Never put backend service keys in a mobile app.

GET /v1/templates (templates:read) lists enabled IDs, locale, channel, variables, bounded parameter schema and push payload keys. It does not reveal message bodies or credentials. The project owner's TEST editor can see complete definitions. Published schema is string-only; numeric values such as ETA are passed as strings. There is no expression evaluation, recursion, arbitrary provider headers or arbitrary JSON construction.

Plan signature and cost

Platform owners can select a TEST plan policy: CUSTOM and STANDARD have no default signature; STARTER requires it. Affiliated projects inherit no signature. The platform owner can explicitly require or remove it for a project. This policy is independent of platform-fee waivers; customer owners cannot change it.

The signature follows the requested template language: EN, ES, PT, RU, UK and HE; other languages use English. It is appended to the visible body before size validation, SMS encoding/segment estimation, budget checks and balance reservation. It may increase SMS segment count or change encoding. Preview reports STANDARD_V1 segmentation; the active route profile and TEST price at admission are authoritative. Push title and custom data are not branded.

Limits and boundaries

At most 16 required parameters, 1–512 characters per parameter, 16 push data keys, 200 rendered title characters, 2,000 push body characters and a conservative 3,000-byte rendered title/body/data envelope. SMS is limited to 1,600 rendered characters. Provider-reserved keys are rejected. Extra/missing parameters, unsupported countries and oversized values fail before queue reservation. Template preview has no charge, queue job or provider call.

This editor and policy are TEST-only. Existing HailMe relay, mobile push protocol and phone authentication are separate; their payloads are unchanged. OTP must use Verify and must not be represented by an ordinary message template. LIVE promotion requires a separate release. No real payment is enabled by publishing a template.