API Reference

1. 1

   Open your app's Settings tab

   Console → Applications → pick an app → Settings.

2. 2

   Generate an API Token

   Shown once, at generation time — copy it somewhere safe. Generating again immediately revokes the old one.

3. 3

   Send it as a header

   Include it as X-Ting-Api-Token on every request below. No "Bearer" prefix, nothing else to log in with.

# Print the response body AND the HTTP status on the last line
curl -sS -X POST <TING_API_URL>/apps/v1/notify \
  -H "X-Ting-Api-Token: $TING_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from curl", "channels": ["TING"]}' \
  -w "\nHTTP %{http_code}\n"

# 200 → {"success":true,"sendLogId":8842}
# 401 → {"error":"INVALID_TOKEN"}
# 400 → {"error":"MESSAGE_REQUIRED" | "MESSAGE_TOO_LONG" | "INVALID_MEDIA_TYPE" | "DUPLICATE_RECIPIENT" | "REPLY_SINGLE_CHANNEL_ONLY" | ...}  (full list in the error table below)

What each language needs

Every language calls the same endpoint, sends the same header (X-Ting-Api-Token) and gets the same JSON back — if yours isn't listed, just make an HTTPS POST with that header using any HTTP library. Always keep the token in a server-side environment variable, never in source code or a client-side app.

POST/apps/v1/notify

The one URL your backend calls, for every app

Headers

Example request

Example 1 — third-party channels (LINE, Telegram …)

Name the channel codes enabled on the app — several at once is fine; everyone subscribed on those channels receives it (omit channels to send to every enabled channel).

curl -X POST <TING_API_URL>/apps/v1/notify \
  -H "X-Ting-Api-Token: tapp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Your order #1042 has shipped!",
    "channels": ["LINE", "TELEGRAM"]
  }'

Example 2 — the Ting Notifications

channels: ["TING"] reaches every follower of this app inside the Ting Notifications (a push on their phone, full-HTML rich messages supported). To target specific followers add recipients: { "TING": ["TNG…"] } with their TNG codes.

curl -X POST <TING_API_URL>/apps/v1/notify \
  -H "X-Ting-Api-Token: tapp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Your order #1042 has shipped! Open the app to track it.",
    "channels": ["TING"]
  }'

Replace <TING_API_URL> with the real URL shown on your app's Settings tab, under "API Endpoints" — it's the same for every request, so copy it once from there.

Body fields

Channel type values

Example response

{
  "success": true,
  "sendLogId": 8842
}

Sends are asynchronous: this call just queues the send and answers immediately (with a sendLogId) — it does not wait for delivery to finish before responding. The actual sending happens entirely in the background. To learn the outcome, ask GET /apps/v1/sends/{id} with that sendLogId (see "Check send status"), or listen for a "message.sent" event on your Ting Events Webhook in real time.

Errors

A free-trial app can send up to the daily limit shown on its Settings tab; a topped-up app sends without limit. A blocked send comes back as success:false with a reason in Detail, per channel or recipient — it never fails the whole request.

POST/apps/{code}/media

multipart/form-data — {code} is the app code shown on the Settings tab

Form fields

Example request

curl -X POST <TING_API_URL>/apps/{code}/media \
  -H "X-Ting-Api-Token: tapp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "type=IMAGE" \
  -F "file=@./promo.jpg"

Example response

{
  "id": 123,
  "url": "<TING_API_URL>/media/123",
  "mediaType": "IMAGE",
  "width": 1200,
  "height": 630,
  "fileSizeBytes": 184320,
  "expiresAt": null
}

Pass the response's url as mediaUrl (with mediaType matching the type you uploaded) in your next /notify call. The same URL can be reused as many times as you like for the life of the file — it lives on the media destination you configured on the Settings tab (e.g. Google Drive or your own storage) and is kept for 1 year from upload (see expiresAt in the response), then deleted automatically, with a console notice 7 days beforehand. Upload again if you still need it after that.

GET/apps/{code}/channels/{channelId}/subscribers

Paginated; searchable by name, id or tag (search=).

curl "<TING_API_URL>/apps/{code}/channels/LINE/subscribers?search=nan" \
  -H "X-Ting-Api-Token: tapp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "items": [
    {
      "externalId": "U4af4980629...",
      "displayName": "Nan",
      "sourceType": "user",
      "status": "ACTIVE",
      "tags": ["VIP"],
      "expiresAt": null,
      "isExpired": false
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

GET/apps/{code}/channels/{channelId}/subscribers/{externalId}

Get one subscriber

curl "<TING_API_URL>/apps/{code}/channels/LINE/subscribers/U4af4980629..." \
  -H "X-Ting-Api-Token: tapp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Subscriber fields

PUT/apps/{code}/channels/{channelId}/subscribers/{externalId}

Every field is independently optional — send only what you want to change.

Update request fields

curl -X PUT "<TING_API_URL>/apps/{code}/channels/LINE/subscribers/U4af4980629..." \
  -H "X-Ting-Api-Token: tapp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["VIP"],
    "expiresAt": "2026-12-31T00:00:00Z"
  }'

{
  "externalId": "U4af4980629...",
  "displayName": "Nan",
  "sourceType": "user",
  "status": "ACTIVE",
  "tags": ["VIP"],
  "expiresAt": "2026-12-31T00:00:00Z",
  "isExpired": false
}

Headers on every call Ting makes to you

Event types

Payload shape

{
  "event": "message.received",
  "app": { "code": "M4rZTA260953", "name": "Demo Shop" },
  "channel": { "type": "LINE", "name": "LINE OA หลัก" },
  "platform": null,
  "data": {
    "conversation": { "externalId": "U4af4980629..." },
    "message": {
      "direction": "IN",
      "text": "สวัสดีครับ สินค้าชิ้นนี้ยังมีของไหม",
      "hasMedia": false,
      "mediaUrl": null,
      "answeredBy": null,
      "createdAt": "2026-09-04T07:12:33.000Z"
    }
  },
  "timestamp": "2026-09-04T07:12:33.100Z"
}

{
  "event": "subscriber.joined",
  "app": { "code": "M4rZTA260953", "name": "Demo Shop" },
  "channel": { "type": "TING", "name": "Ting Notifications" },
  "platform": "ANDROID",
  "data": {
    "subscriber": {
      "externalId": "3f0c2c1e-6b8a-4c1f-9c1e-8f2a9d0b7e21",
      "displayName": "Nan",
      "language": "th"
    }
  },
  "timestamp": "2026-09-09T02:15:40.512Z"
}

{
  "event": "subscriber.expired",
  "app": { "code": "M4rZTA260953", "name": "Demo Shop" },
  "channel": { "type": "LINE", "name": "LINE Official" },
  "data": {
    "subscriber": {
      "externalId": "U4af4980629d2c1b7f8e5a3c0b9d1e2f3",
      "displayName": "Nan",
      "expiresAt": "2026-09-08T17:00:00.000Z"
    }
  },
  "timestamp": "2026-09-09T18:00:03.218Z"
}

Example webhook endpoint (signature check + event routing, complete)

The code below is a ready-to-run server on your side: read the raw body → verify the HMAC → branch on the event type. Respond 200 as fast as you can and do the heavy work afterwards. Ting records every delivery on the console's Logs → Event Webhooks page for later inspection.

const express = require('express');
const crypto = require('crypto');

const app = express();
const SECRET = process.env.TING_WEBHOOK_SECRET;   // from Settings → Ting Events Webhook

// express.raw keeps the exact bytes Ting signed — do NOT use express.json() here
app.post('/ting/events', express.raw({ type: '*/*' }), (req, res) => {
  const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const given = req.get('X-Ting-Signature') ?? '';
  if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString('utf8'));
  switch (event.event) {
    case 'message.received':
      console.log(`[${event.channel.type}] ${event.data.conversation.externalId}: ${event.data.message.text}`);
      break;
    case 'message.sent':
      // delivery outcome of a /notify call or a console reply
      break;
    case 'subscriber.joined':
      console.log(`new follower ${event.data.subscriber.displayName} via ${event.channel.type}`);
      break;
  }
  res.sendStatus(200);   // answer quickly — do slow work after responding
});

app.listen(3000);

Verifying: compute an HMAC-SHA256 of the exact raw request body using your webhook secret, hex-encode it (lowercase), and compare to X-Ting-Signature in constant time — don't re-serialize the JSON first, since that can change the byte-for-byte body the signature was computed over.

1. 1

   Create a page in the console

   App → "Pages" tab → "New page": give it a name and a slug (the tail of the link — a-z, 0-9 and - only), then write the code in the editor. It must be a complete HTML document with CSS/JS in the same file; three templates (blank / form / confirm-cancel buttons) get you started and the live preview updates as you type.

2. 2

   Attach it to a Command

   "Command Ting" tab → Add command → under "What happens when a follower taps it" pick "Send page: <your page>" — no endpoint to fill in and no params to ask for before the tap, because the page is the form.

3. 3

   A follower taps the command

   Ting sends the page into that follower's room as an iframe card right away, with the tapping follower's userCode and the command name attached to the page's query string.

4. 4

   The page posts to you

   JavaScript inside the page reads the query string and fetches your own server directly — Ting never receives or stores what was typed.

With Command Ting (no server needed)

The easy way: pick the page from the dropdown on the command form — Ting sets the endpoint to one of its own (of the form /api/pages/{appCode}/{slug}/send) and handles everything. Configuring through the API instead? Use the commandEndpoint value returned by the page management API (below) as the command's endpoint.

Pick "Custom" instead and it's a regular Command Ting (section 12): Ting POSTs to your endpoint with the params the follower filled in, and your endpoint can then send a page back via /notify (below) if it wants to.

What the page receives (query string)

Whenever Ting sends a page to someone, the link in the card is filled in for that person:

<TING_API_URL>/p/AbC123xyz/order-form?userCode=TNG3049182&command=confirmOrder&ts=1789540329&sig=9f2c1e…a41b

Read them in the page's JavaScript and post the filled form to your own server:

const params = new URLSearchParams(location.search);
const userCode = params.get('userCode');   // "TNG3049182"
const command  = params.get('command');    // "confirmOrder"
const ts       = params.get('ts');         // "1789540329"  (unix seconds, when Ting issued the link)
const sig      = params.get('sig');        // HMAC-SHA256 hex — verified on YOUR server, never here

document.getElementById('form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const data = Object.fromEntries(new FormData(e.target).entries());
  await fetch('https://your-server.com/api/submit', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userCode, command, ts, sig, ...data }),
  });
});

The page runs on a sandboxed origin (the browser sends Origin: null) — your server must allow it via CORS (e.g. Access-Control-Allow-Origin: *) or the browser blocks the fetch.

Close the page and return to the app

When the user is finished on your page (form submitted, order confirmed, and so on), link to tingapp://close. The Ting App closes the page and drops them back in the conversation they came from, instead of leaving them to find the back arrow. In an ordinary browser the link does nothing, so it's always safe to include.

<a href="tingapp://close">ปิด</a>

Sending a page yourself via /notify

For sends that aren't a reaction to a tap — no card HTML to write, just name the page and Ting composes the iframe card, filling in each recipient's userCode. Every other /notify field (delaySeconds, includeExpired, ...) works as usual.

POST <TING_API_URL>/apps/v1/notify
X-Ting-Api-Token: tapp_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "page": "order-form",
  "message": "กรุณากรอกฟอร์มยืนยันคำสั่งซื้อ",
  "pageHeight": 420,
  "channels": ["TING"],
  "recipients": { "TING": ["TNG3049182"] }
}

Writing the card yourself (advanced)

If your endpoint composes the card HTML itself, these placeholders are filled in per recipient at send time (Ting Notifications channel only); the values are HTML-encoded.

<div data-ting-height="420" style="background:#fff;border-radius:16px;padding:8px;">
  <iframe src="<TING_API_URL>/p/AbC123xyz/order-form?userCode={{userCode}}&command={{command}}&ts={{ts}}&sig={{signature}}"
          style="display:block;width:100%;height:400px;border:0;border-radius:12px;"></iframe>
</div>

Verifying it came from Ting

Every page link Ting sends out carries ts and sig. Have the page forward userCode, command, ts and sig along with the form data, and recompute the HMAC on your server with the app's signing secret (the same one X-Ting-Signature uses — app details → Settings → Ting Events Webhook). A match proves Ting issued this link for that follower, rather than someone guessing the URL:

sig = HMAC-SHA256( secret, userCode + "|" + command + "|" + ts )   → lowercase hex

secret   = Signing secret ของแอป (Settings → Ting Events Webhook — ตัวเดียวกับที่ใช้ตรวจ X-Ting-Signature)
example  = HMAC-SHA256( secret, "TNG3049182|confirmOrder|1789540329" )

const crypto = require('crypto');

function verifyTingPage({ userCode, command, ts, sig }, secret, maxAgeSeconds = 3600) {
  const expected = crypto.createHmac('sha256', secret)
    .update(`${userCode}|${command}|${ts}`)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= maxAgeSeconds;
  return fresh && sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
}

app.post('/api/submit', (req, res) => {
  if (!verifyTingPage(req.body, process.env.TING_SIGNING_SECRET)) {
    return res.status(401).json({ error: 'not from Ting' });
  }
  // req.body.userCode is now trusted — save the form
  res.json({ ok: true });
});

Verify on your server only — never put the secret in page code (pages are public) — and cap the age via ts (e.g. 1 hour) so an old link can't be replayed. An app that has no signing secret yet (an older app that never set one) gets an empty sig — open the app's Settings once and the system generates it.

Good to know

• Pages are served under a sandbox isolated from Ting: JavaScript, forms and popups work, but Ting's tokens/data are out of reach and localStorage is unavailable (keep state in JS variables or on your server).
• Pages are public — anyone with the link can open one. Never put secrets (API keys, passwords) in page code; always authorize on your own server.
• userCode alone only identifies the follower — the trust comes from checking sig on your server (above); reject form data that arrives without a sig or with one that doesn't match.
• Set a meaningful <title> in the page — the Ting app uses it as the screen title when a user opens the page full-screen (the domain is never shown).

Command Ting → reply with a card

Check server status from one button in the app

A follower taps "Check server status" in the Ting Notifications → Ting POSTs to your endpoint → the endpoint checks its own systems and pushes a status card (HTML) back to that one follower via /notify — all within a few seconds, without the follower typing anything.

1. 1

   Configure the command in the console

   App → "Commands" tab → add a command named "Check server status" with the URL of the endpoint below. No parameters needed.

2. 2

   The endpoint receives the payload

   You get userCode (the tapping follower's TNG code), appName and language in the body.

3. 3

   Run your checks, push the card back

   Call /notify with channels: ["TING"] and recipients.TING: [userCode] — the TNG code works directly, no lookup needed.

4. 4

   Answer "ok" to Ting

   That short text shows as a toast for the follower; the real card lands in the app's chat immediately.

Actual screen in the Ting Notifications

Your endpoint's code

Node.js PHP Python C# Java Go Ruby

Copy

const express = require('express');

const app = express();
app.use(express.json());

const TING_API = '<TING_API_URL>';
const TING_TOKEN = process.env.TING_API_TOKEN;   // tapp_...

app.post('/ting/commands/check-status', async (req, res) => {
  const { userCode, appName, language, values } = req.body;

  // 1. Run your own checks
  const dbOk = await checkDatabase();
  const uptimeMin = Math.floor(process.uptime() / 60);

  // 2. Push a rich status card back to the follower who tapped the command
  const ok = dbOk;
  const title = language === 'en'
    ? (ok ? 'All systems normal' : 'Problem detected')
    : (ok ? 'ระบบทำงานปกติ' : 'ระบบมีปัญหา');
  const card = `
<div data-ting-height="230" style="padding:20px;border-radius:16px;background:#fff;font-family:sans-serif;text-align:center;">
  <span style="padding:6px 16px;border-radius:999px;font-weight:700;background:${ok ? '#dcfce7' : '#fee2e2'};color:${ok ? '#16a34a' : '#dc2626'};">${title}</span>
  <h3 style="margin:16px 0 4px;">${appName}</h3>
  <p style="margin:0;color:#64748b;font-size:14px;">Database: ${dbOk ? 'OK' : 'DOWN'} · Uptime: ${uptimeMin} min</p>
</div>`;

  await fetch(`${TING_API}/apps/v1/notify`, {
    method: 'POST',
    headers: { 'X-Ting-Api-Token': TING_TOKEN, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: card,
      channels: ['TING'],
      recipients: { TING: [userCode] },
    }),
  });

  // 3. Short acknowledgement — shown to the follower as a toast (max 500 chars)
  res.type('text/plain').send('ok');
});

app.listen(3000);

Webhook → greeting

Greet every new follower automatically (Thai + English)

Every time someone follows your app for the first time, Ting sends a "subscriber.joined" event to your webhook — the code below sends a bilingual welcome back to that one person, on the channel they joined through (an HTML card from the Ting Notifications, plain text from LINE/Telegram/others).

1. 1

   Set up the Ting Events Webhook

   App Settings tab → enter your endpoint URL and generate a secret.

2. 2

   Handle the subscriber.joined event

   Verify the signature as in the "Receive webhooks" example, then branch on event === "subscriber.joined".

3. 3

   Send the greeting back

   Call /notify with channels: [channel.type] and recipients: { [channel.type]: [externalId] } from the payload — so only the person who just joined gets it.

The push arrives the moment they follow

Actual screen in the Ting Notifications

The greeting function (called from the handler in "Receive webhooks")

Node.js PHP Python C# Java Go Ruby

Copy

const TING_API = '<TING_API_URL>';
const TING_TOKEN = process.env.TING_API_TOKEN;   // tapp_...

function greeting(appName, name, richHtml) {
  const who = name ? ` คุณ${name}` : '';
  const whoEn = name ? `, ${name},` : '';
  const th = `ยินดีต้อนรับ${who} สู่ ${appName}! ขอบคุณที่กดติดตามนะ 🎉 ตั้งแต่นี้เราจะส่งการแจ้งเตือนและข่าวสารสำคัญมาหาคุณที่นี่`;
  const en = `Welcome${whoEn} to ${appName}! Thanks for following 🎉 We'll keep you posted with important updates right here from now on.`;
  if (!richHtml) return `${th}\n\n${en}`;   // LINE/Telegram/...: plain text
  return `
<div data-ting-height="360" style="padding:24px;border-radius:20px;background:#fff;font-family:sans-serif;text-align:center;">
  <span style="padding:8px 18px;border-radius:999px;font-weight:700;background:#ede9fe;color:#7c3aed;">🎉 ยินดีต้อนรับ · Welcome</span>
  <h3 style="margin:18px 0 12px;">${appName}</h3>
  <p style="text-align:left;font-size:14px;line-height:1.6;margin:0 0 10px;">${th}</p>
  <p style="text-align:left;font-size:13px;line-height:1.6;margin:0;color:#64748b;border-top:1px solid #e2e8f0;padding-top:10px;">${en}</p>
</div>`;
}

// call this from the 'subscriber.joined' branch of your /ting/events handler
async function sendWelcome(event) {
  const { type } = event.channel;
  const { externalId, displayName } = event.data.subscriber;

  await fetch(`${TING_API}/apps/v1/notify`, {
    method: 'POST',
    headers: { 'X-Ting-Api-Token': TING_TOKEN, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: greeting(event.app.name, displayName, type === 'TING'),
      channels: [type],
      recipients: { [type]: [externalId] },   // only the person who just joined
    }),
  });
}

Caution: whatever your endpoint returns to Ting (Command Ting and webhooks alike) is never shown to followers beyond a short toast, but still never put URLs, tokens or internal details in it — keep your Ting token in a server-side environment variable only, never in a mobile app or a web page users can reach.