DEV Community: unifyport

Telegram Bot Receives DMs but Not Group Messages? Debug Privacy Mode First

unifyport — Wed, 16 Sep 2026 09:14:34 +0000

Your Telegram bot receives private messages without a problem.

In a group, it receives /help@your_bot and replies directed at it—but ordinary messages never reach your application.

The first instinct is often to rebuild the webhook, switch to getUpdates, or promote the bot to administrator.

Those changes may be unnecessary.

Telegram enables Privacy Mode for bots by default. A privacy-enabled bot does not receive a complete stream of ordinary group conversation.

The important distinction is:

Group-message visibility and update delivery are separate layers.

A working webhook cannot deliver a message Telegram does not expose to the bot. Disabling Privacy Mode also cannot repair a broken webhook, an incorrect bot token, or an application filter that discards message updates.

Diagnose the layers independently.

Start with the observed behavior

Different symptoms point to different parts of the system.

Observation	Likely area to inspect
Private messages arrive, but ordinary group text does not	Privacy Mode and group role
Addressed group commands arrive, but ordinary text does not	Broad group visibility
Neither private messages nor addressed commands arrive	Bot identity, active receiver and update filters
Telegram update reaches the HTTP endpoint, but the app shows nothing	Application filtering or queue processing
Privacy Mode was disabled, but behavior did not change	Remove and re-add the bot, then retest
Only one group is affected	Membership and role in that specific group

Treat these as diagnostic hypotheses rather than guaranteed conclusions.

Before changing settings, record which test messages reached the raw receiver.

What Privacy Mode controls

Privacy Mode controls which group messages Telegram makes available to a bot.

With Privacy Mode enabled, a bot can receive interactions relevant to it, including commands explicitly addressed to its username and replies to the bot’s messages.

For example:

/help@support_example_bot

An ordinary group message such as:

Has anyone received their order?

may not be exposed to a privacy-enabled, non-admin bot.

That behavior is different from private chat, where the user is communicating directly with the bot.

A successful private-message test therefore proves only that:

the bot token can identify a bot;
at least one receiving path works;
the application can process that private update.

It does not prove that the bot is entitled to receive ordinary conversation from a particular group.

Visibility and delivery are different layers

Think of the system as a pipeline:

User sends a group message
        ↓
Telegram evaluates bot visibility
        ↓
Telegram creates an eligible update
        ↓
getUpdates or setWebhook delivers it
        ↓
Application filters the update
        ↓
Business logic processes it

A failure at each layer looks different.

Visibility failure

Telegram never exposes the ordinary group message to the bot.

Changing webhook code does not fix this.

Delivery failure

The bot is eligible to receive the update, but the configured polling or webhook receiver does not deliver it correctly.

Privacy settings do not fix this.

Application-filtering failure

The update reaches your endpoint, but your code ignores it.

Changing the bot’s permissions does not fix this.

Good troubleshooting identifies the failed layer before modifying the next one.

Step 1: confirm the bot identity

A surprisingly common cause is deploying the wrong bot token.

Use getMe from a trusted environment:

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getMe"

Do not paste the bot token into:

screenshots;
shared shell logs;
support tickets;
source code;
chat messages.

Check the returned bot identity against the username added to the affected group.

A staging bot and a production bot may have similar names while using completely different tokens and privacy settings.

Check `can_read_all_group_messages`

The getMe response may include:

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "Support Bot",
    "username": "support_example_bot",
    "can_join_groups": true,
    "can_read_all_group_messages": false
  }
}

The relevant field is:

can_read_all_group_messages

According to the Telegram Bot API, true means Privacy Mode is disabled.

This field describes the bot’s Privacy Mode status. It is not a report of the bot’s role in every group.

You must still inspect its membership and permissions in the affected group.

Step 2: run a controlled group test

Use a dedicated test group with informed participants.

Send new messages from a human Telegram account in this order:

A private text message to the bot.
A command addressed to the bot’s exact username.
A reply to a message previously sent by the bot.
An ordinary group text message.
A new ordinary message after any approved configuration change.

Example test messages:

Private chat:
privacy-test-private-001

Group:
 /status@support_example_bot

Reply to bot:
privacy-test-reply-001

Ordinary group text:
privacy-test-group-001

Use distinct values so you can search logs and queue records unambiguously.

Do not use historical messages as the test. Changing permissions does not imply recovery of messages that were never delivered.

Also avoid using another bot as the sender. Bot-to-bot behavior introduces a different set of rules.

Step 3: inspect the raw receiver

Before investigating business logic, determine whether the Telegram update reached your receiving boundary.

For a webhook-based service, temporarily record safe metadata:

app.post("/telegram/webhook", async (req, res) => {
  const update = req.body;

  console.info("telegram_update_received", {
    updateId: update.update_id,
    hasMessage: Boolean(update.message),
    chatId: update.message?.chat?.id,
    chatType: update.message?.chat?.type,
  });

  await storeUpdateIfAbsent(update);

  return res.status(200).end();
});

Do not log the bot token or unnecessary message content.

If the update exists in raw storage but not in the product UI, Privacy Mode is not the immediate cause. The problem is now inside the application.

Inspect:

event-type conditions;
chat-type filters;
queue insertion;
duplicate detection;
worker failures;
database transactions;
downstream routing.

Step 4: audit application filters

A handler may accidentally accept only private chats:

if (update.message?.chat?.type !== "private") {
  return;
}

Or it may accept only commands:

if (!update.message?.text?.startsWith("/")) {
  return;
}

A more explicit router makes the boundary easier to inspect:

function classifyTelegramUpdate(update) {
  const message = update.message;

  if (!message) {
    return { kind: "unsupported_update" };
  }

  switch (message.chat.type) {
    case "private":
      return {
        kind: "private_message",
        message,
      };

    case "group":
    case "supergroup":
      return {
        kind: "group_message",
        message,
      };

    default:
      return {
        kind: "unsupported_chat_type",
        message,
      };
  }
}

The application should make its supported chat types visible rather than silently discarding them.

Step 5: check `allowed_updates`

Telegram’s allowed_updates parameter controls which update types are delivered through the Bot API receiver.

For a group text-message test, the configuration must allow:

message

A conceptual configuration looks like this:

{
  "allowed_updates": [
    "message"
  ]
}

Privacy Mode and allowed_updates solve different problems:

Privacy Mode:
Is the bot eligible to see this group message?

allowed_updates:
Should this eligible update type be delivered to the receiver?

Broader group visibility cannot fix an allowed_updates configuration that excludes message.

Similarly, adding message cannot grant visibility that Telegram has not given the bot.

Telegram also documents that omitting allowed_updates can preserve the previous configuration. Do not assume omission resets it to every update type.

Audit the configuration used by the currently active receiver.

Step 6: verify the receiving mode

Telegram Bot API supports two mutually exclusive receiving modes:

getUpdates
setWebhook

If private messages and addressed commands arrive through the same receiver, transport is probably not the first problem to change.

If nothing arrives at all, inspect the active receiver with:

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

A non-empty webhook URL means a webhook is configured.

Do not switch between polling and webhook delivery merely to test Privacy Mode. Delivery transport does not expand group visibility.

Diagnose transport separately using a controlled migration runbook.

Step 7: choose the minimum required access

Before disabling Privacy Mode, ask whether the bot truly needs every ordinary group message.

A command-driven bot may need only:

/help@bot
/status@bot
/assign@bot

A reply-based workflow may need only messages explicitly directed at the bot.

In those cases, keeping Privacy Mode enabled reduces unnecessary data collection.

Consider disabling it only when the product genuinely needs broad group observation, for example:

support triage across all group conversation;
moderation of ordinary user messages;
group analytics with informed participants;
workflows triggered by non-command text.

Treat broader visibility as a privacy and access decision, not as a performance optimization.

Do not promote the bot to administrator just for testing

Administrator status carries permissions and responsibilities beyond receiving messages.

Promoting the bot may change behavior, but it also changes the security model.

Do not combine all these changes in one experiment:

Disable Privacy Mode
Promote bot to administrator
Replace webhook
Change allowed_updates
Deploy new handler

If the test starts working, you will not know which change mattered.

Change one layer at a time:

1. Confirm identity
2. Record baseline tests
3. Check Privacy Mode
4. Check group role
5. Check allowed_updates
6. Inspect raw delivery
7. Inspect application filters

This preserves causal evidence.

Disabling Privacy Mode safely

If ordinary group conversation is required:

Confirm the correct bot with getMe.
Explain the broader collection scope to group owners.
Change Privacy Mode through BotFather using /setprivacy.
Remove the bot from the test group.
Re-add the bot to the group.
Verify its intended role.
Send a new human-authored test message.
Inspect the raw receiver before application output.

Telegram documents that the bot must be re-added to the group after Privacy Mode is disabled for the change to take effect.

Do not skip the re-add step and conclude that the setting failed.

Build an acceptance-test matrix

Record results instead of relying on memory.

Test	Privacy enabled	Privacy disabled and bot re-added
Private text	Expected	Expected
Addressed command	Expected	Expected
Reply to bot message	Expected	Expected
Ordinary human group text	Restricted by Privacy Mode	Expected when other configuration is correct
Message visible in raw receiver	Record result	Record result
Message processed by application	Record result	Record result

The rightmost column is not a guarantee that every application will work. The receiving mode, update filters, group role and handler must still be correct.

Preserve updates idempotently

Once a message reaches the application, use update_id as the delivery-level idempotency key.

async function storeUpdateIfAbsent(update) {
  const inserted = await database.telegramUpdates.insertIfAbsent({
    updateId: update.update_id,
    payload: update,
    receivedAt: new Date(),
  });

  if (!inserted) {
    return false;
  }

  await enqueueTelegramUpdate(update.update_id);
  return true;
}

This prevents webhook retries or polling restarts from creating duplicate downstream work.

Business operations may need their own idempotency keys:

support-ticket:{botId}:{updateId}
moderation-action:{botId}:{updateId}
notification:{botId}:{updateId}

Receiving the same update twice should not create two tickets or apply the same moderation action twice.

A compact diagnostic function

You can turn the troubleshooting logic into an internal checklist:

function diagnoseGroupVisibility({
  privateMessageReceived,
  addressedCommandReceived,
  ordinaryGroupMessageReceived,
  rawUpdateReceived,
  privacyDisabled,
  botReadded,
  messageAllowed,
}) {
  if (!privateMessageReceived && !addressedCommandReceived) {
    return "Check bot identity, receiver mode and allowed_updates";
  }

  if (
    addressedCommandReceived &&
    !ordinaryGroupMessageReceived &&
    !privacyDisabled
  ) {
    return "Behavior is consistent with Privacy Mode";
  }

  if (privacyDisabled && !botReadded) {
    return "Remove and re-add the bot, then send a new test message";
  }

  if (!messageAllowed) {
    return "Update configuration must include message";
  }

  if (rawUpdateReceived && !ordinaryGroupMessageReceived) {
    return "Inspect application filtering and downstream processing";
  }

  return "Inspect group role and compare raw updates with application records";
}

This does not replace Telegram’s documentation, but it stops incident responders from making unrelated changes simultaneously.

Bot identity versus account-based intake

This guide concerns Telegram Bot API bots.

A bot is the right model when users should interact with a bot identity through commands, replies and bot-specific workflows.

An account-based intake system solves a different problem:

Existing Telegram account
        ↓
Authorized account connection
        ↓
Normalized inbound events
        ↓
Shared multi-channel queue

UnifyPort’s unofficial interface can connect a Telegram account and emit normalized message.received events alongside WhatsApp, LINE, TikTok, Zalo and X.

That architecture is not a way to change BotFather settings or repair a Bot API webhook.

It also does not grant access to arbitrary groups or guarantee recovery of historical messages.

Choose based on the required identity:

Users should talk to a bot
    → Telegram Bot API

Team needs intake from an authorized existing account
    → Evaluate an account-based integration

Production checklist

Before declaring the issue fixed, verify:

[ ] getMe returns the expected bot identity.
[ ] can_read_all_group_messages matches the intended Privacy Mode.
[ ] The bot belongs to the affected group.
[ ] Its group role is intentional.
[ ] The test uses a human sender.
[ ] The command includes the correct bot username.
[ ] allowed_updates includes message.
[ ] The intended receiver is active.
[ ] New tests reach raw update storage.
[ ] Application filters accept group and supergroup where required.
[ ] Update IDs are stored idempotently.
[ ] The bot was re-added after disabling Privacy Mode.
[ ] Broader access was approved by the group owner.
[ ] Logs exclude the bot token and unnecessary message content.

Takeaway

When a Telegram bot receives private messages but misses ordinary group conversation, do not rebuild the webhook first.

Diagnose the pipeline in order:

Bot identity
    ↓
Privacy Mode
    ↓
Group role
    ↓
allowed_updates
    ↓
Delivery transport
    ↓
Application filters

An addressed command arriving while ordinary group text does not is strong evidence that the receiver works for at least one eligible group interaction.

Decide whether broader visibility is actually required. If it is, disable Privacy Mode deliberately, re-add the bot, and retest with new human-authored messages.

Change permissions, transport and application code separately so each test tells you something useful.

References

This article was adapted from an original UnifyPort technical guide with AI-assisted editing.

Telegram getUpdates vs setWebhook: A Safe Migration Runbook

unifyport — Wed, 09 Sep 2026 07:52:50 +0000

Your Telegram bot worked yesterday.

After a deployment, one of these things happens:

getUpdates returns no messages;
the webhook endpoint receives nothing;
old updates suddenly arrive in a flood;
the application processes some messages twice;
both teams insist their receiver is configured correctly.

The underlying rule is simple:

Telegram Bot API polling with getUpdates and push delivery with setWebhook are mutually exclusive for the same bot.

They are two alternative delivery modes—not two layers that should run in parallel.

A safe migration therefore requires four things:

Inspect the current mode
        ↓
Stop the current receiver
        ↓
Choose what happens to pending updates
        ↓
Start and verify the new receiver

This runbook covers both migration directions.

The two receiving modes

Telegram bots can receive updates through polling or webhooks.

Long polling with `getUpdates`

Your application repeatedly asks Telegram for new updates:

Application → Telegram: Do you have updates?
Telegram → Application: Here are the updates

Example:

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getUpdates?timeout=30"

Polling is often convenient for:

local development;
small bot deployments;
workers without a public HTTPS endpoint;
simple single-process applications.

Your worker owns the delivery loop and must advance the update offset correctly.

Push delivery with `setWebhook`

Telegram sends each update to your HTTPS endpoint:

Telegram → Application: Here is an update
Application → Telegram: HTTP 2xx

Example:

curl -X POST \
  "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -d "url=https://support.example.com/telegram/bot-webhook"

Webhooks are often a better fit for:

production HTTP services;
horizontally scalable consumers;
low-latency processing;
infrastructure that already receives external events.

The endpoint should acknowledge requests quickly and move slow work to a queue.

Why the conflict happens

When a webhook is configured, Telegram does not allow the same bot to receive updates through getUpdates.

A polling worker may still be running, but it is no longer the active Telegram delivery path.

This creates a confusing operational state:

Polling process: healthy and still running
Telegram webhook: configured
getUpdates: unable to receive updates

From an infrastructure dashboard, the polling worker looks healthy. From the bot’s perspective, it is no longer receiving anything.

The reverse migration can also fail when a team deploys a webhook receiver but forgets to stop or retire the previous polling deployment.

Even when Telegram itself has one active delivery mode, multiple application instances may still compete inside your infrastructure and create duplicate downstream processing.

First step: inspect the active mode

Before changing a deployment flag, call getWebhookInfo:

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

Keep BOT_TOKEN in an environment variable. Do not paste it into shell history, tickets, screenshots or application logs.

The most important field for this diagnosis is url.

url is non-empty → a Telegram Bot API webhook is configured
url is empty     → no Bot API webhook is configured

Do not guess the active mode from:

which service is currently deployed;
which process is running;
what the environment variable says;
what the previous release was supposed to do.

Telegram’s current webhook configuration is the state that matters.

Diagnose common symptoms

Symptom	Likely explanation	First check
`getUpdates` stopped returning messages	A webhook is still configured	Call `getWebhookInfo`
Webhook receives nothing	Webhook was not set correctly or points to the wrong endpoint	Inspect `getWebhookInfo`
Old updates arrive after switching	Pending updates were retained	Review the backlog policy
Updates are processed twice internally	Multiple application consumers or non-idempotent storage	Check worker ownership and update IDs
Test messages disappear	Pending updates may have been dropped during cutover	Check the migration command and logs

Treat the receiving mode and your internal processing topology as separate problems.

Telegram may have only one active delivery mode while your backend still has two consumers reading the same internal queue.

Migration rule: one receiver owns the bot

Before switching, define one owner for the bot:

telegram-receiver-mode = polling

or:

telegram-receiver-mode = webhook

Do not leave both production deployments enabled and rely on timing.

A useful deployment invariant is:

At every point in the migration, exactly one system is designated to process new Telegram updates.

A brief period with no active application receiver is safer than an uncontrolled period in which multiple consumers can create duplicate side effects.

Pending updates must then be handled according to an explicit policy.

Switching from webhook to `getUpdates`

Use this direction when returning to polling.

Step 1: pause downstream changes

Temporarily prevent bot updates from triggering irreversible side effects during the cutover.

Examples include:

sending duplicate replies;
creating duplicate support tickets;
charging a customer twice;
applying the same moderation action twice.

Your update processing should already be idempotent, but the migration is a good time to verify that assumption.

Step 2: inspect the webhook

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

Confirm which URL is configured before deleting it.

This avoids removing an unexpected production receiver based on a stale deployment assumption.

Step 3: choose the pending-update policy

Remove the webhook using deleteWebhook:

curl -X POST \
  "https://api.telegram.org/bot$BOT_TOKEN/deleteWebhook" \
  -d "drop_pending_updates=false"

The critical parameter is:

drop_pending_updates

Use false when pending messages still matter.

Use true only when the backlog can be discarded deliberately.

Situation	Suggested choice
Production support messages	`false`
Customer orders or requests	`false`
Moderation events	Usually `false`
Disposable test traffic	Possibly `true`
Corrupted or unsafe backlog	Make an explicit incident decision
Clean non-production reset	Possibly `true`

Do not use true merely because it makes the migration easier.

Dropping pending updates is a business-data decision, not just a technical cleanup option.

Step 4: verify webhook removal

Call getWebhookInfo again:

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

Confirm that the webhook url is empty.

Do this before starting the polling worker.

Step 5: start exactly one polling worker

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getUpdates?timeout=30"

In production, only one logical polling owner should fetch updates for that bot.

If several application replicas all start polling independently, your deployment becomes difficult to reason about even though no webhook is configured.

Step 6: advance the offset

After processing a response, advance offset beyond the highest processed update_id.

A simplified worker looks like this:

let offset = 0;

async function pollTelegram() {
  while (true) {
    const query = new URLSearchParams({
      timeout: "30",
      offset: String(offset),
    });

    const response = await fetch(
      `https://api.telegram.org/bot${process.env.BOT_TOKEN}/getUpdates?${query}`,
    );

    if (!response.ok) {
      throw new Error(`getUpdates failed: ${response.status}`);
    }

    const body = await response.json();

    for (const update of body.result) {
      await processUpdateIdempotently(update);
      offset = Math.max(offset, update.update_id + 1);
    }
  }
}

For a durable production implementation, do not keep the confirmed offset only in process memory.

If the worker restarts after performing a side effect but before persisting progress, the same update may be processed again.

Store update IDs and processing state durably.

Switching from `getUpdates` to `setWebhook`

Use this direction when moving from polling to push delivery.

Step 1: stop the polling worker

Stop or scale down the polling deployment first.

Confirm that:

no polling process is still running;
no scheduled job calls getUpdates;
no developer machine uses the production bot token;
no old deployment remains active in another region.

Stopping the visible worker is not enough if another automation still polls the same bot.

Step 2: finish or checkpoint current work

Allow in-flight updates to complete or store them durably before terminating the worker.

The polling application should record which update_id values were accepted so the webhook receiver can continue processing idempotently.

Step 3: deploy the webhook endpoint

The endpoint should be ready before you register it with Telegram.

A minimal Express receiver might look like this:

app.post("/telegram/bot-webhook", async (req, res) => {
  const update = req.body;

  const inserted = await storeUpdateIfAbsent({
    updateId: update.update_id,
    payload: update,
  });

  res.status(200).end();

  if (inserted) {
    await enqueueTelegramUpdate(update.update_id);
  }
});

In a production implementation, separate the HTTP acknowledgment from slow CRM, database-enrichment or AI operations.

The reliable pattern is:

Receive
  ↓
Validate
  ↓
Store idempotently
  ↓
Return success
  ↓
Process asynchronously

Step 4: configure the webhook

curl -X POST \
  "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -d "url=https://support.example.com/telegram/bot-webhook"

Use a production HTTPS endpoint controlled by your team.

Do not point a production bot at:

a developer laptop;
a temporary tunnel with an unknown lifetime;
a staging endpoint;
an endpoint that performs slow work before responding.

Step 5: verify the configured URL

curl \
  "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

Confirm that the returned URL is exactly the endpoint you intended to configure.

This catches:

environment mix-ups;
incorrect paths;
staging URLs;
accidental trailing route differences;
deployment-variable mistakes.

Step 6: send a controlled test message

Send one identifiable test message to the bot.

Verify the entire path:

Telegram accepted message
        ↓
Webhook received update
        ↓
Update stored once
        ↓
Queue job created
        ↓
Downstream handler processed it once

A successful setWebhook call alone does not prove that your application is receiving and processing updates correctly.

Handle pending updates deliberately

Telegram stores pending updates temporarily, so a migration should not be left half-finished.

Before switching, decide:

Are pending messages business-critical?
Can the new receiver process old updates idempotently?
Is the backlog entirely disposable test traffic?
Does processing old commands after deployment create risk?
Who is authorized to approve dropping the backlog?

Document the decision in the deployment record:

Pending update policy: retain and drain
Approved by: support operations
Receiver before: webhook
Receiver after: polling
Cutover time: 2026-09-09T10:00:00Z

Never record the bot token in the deployment record.

Make both modes idempotent

Regardless of the delivery method, store each Telegram update_id once.

A conceptual database table could be:

CREATE TABLE telegram_updates (
  bot_id TEXT NOT NULL,
  update_id BIGINT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL,
  received_at TIMESTAMPTZ NOT NULL,
  processed_at TIMESTAMPTZ,
  PRIMARY KEY (bot_id, update_id)
);

The unique key prevents a repeated update from creating another business action.

A handler can then claim stored work atomically:

async function processUpdateIdempotently(update) {
  const inserted = await insertUpdateIfAbsent(update);

  if (!inserted) {
    return;
  }

  await enqueueUpdate(update.update_id);
}

Idempotency should be based on Telegram’s stable update identifier, not message text or arrival time.

Avoid duplicate side effects

Even with unique update storage, downstream operations may still need their own idempotency keys.

Examples include:

telegram-reply:{botId}:{updateId}
support-ticket:{botId}:{updateId}
moderation-action:{botId}:{updateId}

If the worker crashes after creating a support ticket but before marking the update complete, a retry should find the existing ticket instead of creating a second one.

Delivery deduplication and business-operation deduplication are related but separate safeguards.

A migration checklist

Before switching

[ ] Confirm the bot token belongs to the expected bot.
[ ] Call getWebhookInfo.
[ ] Record the active receiving mode.
[ ] Identify every polling worker and webhook deployment.
[ ] Decide whether pending updates must be retained.
[ ] Verify update processing is idempotent.
[ ] Prepare the destination receiver.
[ ] Keep the bot token out of logs.

Webhook to polling

[ ] Call deleteWebhook.
[ ] Set drop_pending_updates deliberately.
[ ] Confirm the webhook URL is empty.
[ ] Start exactly one polling owner.
[ ] Persist processed update IDs.
[ ] Advance the polling offset.
[ ] Drain retained updates.
[ ] Test one new message.

Polling to webhook

[ ] Stop every polling worker.
[ ] Finish or checkpoint in-flight work.
[ ] Deploy the webhook receiver.
[ ] Configure the production webhook URL.
[ ] Verify it with getWebhookInfo.
[ ] Send a controlled test message.
[ ] Confirm the update was stored once.
[ ] Confirm downstream processing occurred once.

When the Bot API is the right model

Use Telegram’s official Bot API when:

users should interact with a bot identity;
the Telegram Update object is the right event contract;
bot commands are central to the product;
the integration is intentionally Telegram-specific;
polling or Telegram-native webhooks fit your infrastructure.

In that case, choose either getUpdates or setWebhook and operate it clearly.

When a unified inbound webhook fits better

The Bot API runbook solves delivery for one Telegram bot.

It does not:

connect an ordinary Telegram user account;
normalize WhatsApp, LINE, TikTok, Zalo or X;
create a shared cross-channel inbox contract.

If your actual requirement is:

Receive customer messages from several existing accounts
        ↓
Store them in one event model
        ↓
Route them to the same support queue

then a normalized inbound webhook may be a cleaner architecture.

A Telegram event delivered through UnifyPort can use the same envelope as other connected providers:

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-09-09T12:37:00Z",
  "data": {
    "conversation": {
      "id": "5005",
      "type": "user"
    },
    "sender": {
      "id": "4004",
      "type": "user",
      "name": "Jordan Lee"
    },
    "message": {
      "id": "3003",
      "direction": "inbound",
      "sent_at": "2026-09-09T12:37:00Z",
      "text": "Can you check my order?"
    },
    "event": {
      "kind": "message_received"
    }
  }
}

Use the Bot API when the identity should be a Telegram bot.

Use an account-based inbound interface when an existing messaging account or cross-platform support queue is the real requirement.

These are different product models, not interchangeable transport settings.

Takeaway

When a Telegram bot stops receiving updates after a deployment, start with one question:

What does getWebhookInfo say?

Then follow a controlled migration:

Inspect
  ↓
Stop the old receiver
  ↓
Choose the pending-update policy
  ↓
Start the new receiver
  ↓
Verify one end-to-end message

Never treat getUpdates and setWebhook as parallel delivery layers.

Pick one owner, store updates idempotently, and make the pending-backlog decision explicit before switching.

References

This article was adapted from an original UnifyPort technical guide with AI-assisted editing.

TikTok Business Messaging API vs QR-Authenticated Inbox: How to Choose

unifyport — Mon, 07 Sep 2026 07:22:19 +0000

“We need TikTok DMs in our backend” sounds like a clear technical requirement.

It is not.

Before selecting an API, you need to answer a more fundamental question:

Which TikTok identity and operating model are you building around?

There are two different integration paths:

TikTok’s official Business Messaging API.
A QR-authenticated inbox connected to a normalized webhook.

Both can bring direct messages into a backend, but they solve different problems.

The official API is designed around TikTok Business Account capabilities and TikTok-native messaging workflows. A QR-authenticated inbox starts with an existing account that already receives customer messages and connects that inbox to your operational backend.

Choosing between them is an architecture decision—not merely an authentication preference.

The short version

Question	TikTok Business Messaging API	QR-authenticated inbox
Primary identity	TikTok Business Account	Existing TikTok account
Best fit	TikTok-focused business messaging	Multi-channel support inbox
Setup focus	App access, authorization, reviews and limits	Account connection, QR authentication and webhook delivery
Event model	TikTok-specific API and webhooks	Normalized message events
Other channels	Build separate integrations	Reuse the same intake contract
Main advantage	Official TikTok business capabilities	Faster integration with an existing operational inbox
Main trade-off	Platform-specific access and implementation	Session lifecycle and re-authentication operations

A useful starting rule is:

Need TikTok-native business features?
    → Evaluate the official Business Messaging API

Need messages from an existing inbox in a shared multi-channel queue?
    → Evaluate a QR-authenticated inbox

Start with the identity

Many teams begin by comparing endpoints, payloads, or SDKs.

Start with identity instead.

Ask:

Is the account a TikTok Business Account?
Does the product depend on official business-messaging capabilities?
Are messages connected to paid-media or campaign workflows?
Does the team already operate a TikTok inbox manually?
Must TikTok messages enter the same queue as WhatsApp, LINE or Zalo?
Can the team operate session renewal and re-authentication safely?

The answers determine which integration model fits.

What the official Business Messaging API is for

TikTok’s Business Messaging documentation describes an official API surface for direct-message workflows.

Its documentation includes capabilities related to:

conversations;
sending and retrieving messages;
media upload and download;
webhook configuration;
Business Account capability checks;
automatic-message management.

This path is appropriate when TikTok itself is a core product surface.

Examples include:

a TikTok-first sales platform;
business messaging connected to advertising campaigns;
workflows that depend on official Business Account capabilities;
applications requiring a platform-supported integration model;
products that need TikTok-specific messaging operations.

Before committing to this path, review TikTok’s current requirements for:

authorization;
account eligibility;
application access;
data-security review;
regional availability;
rate limits;
return codes;
production approval.

Do not assume that finding an endpoint in the documentation means every application or account can immediately use it in production.

What a QR-authenticated inbox is for

A QR-authenticated inbox begins with a different requirement:

Our operators already use this TikTok inbox. How can its inbound messages reach our backend?

With UnifyPort, the flow uses the same general account lifecycle as other QR-authenticated messaging channels:

Create account
    ↓
Start QR authentication
    ↓
Poll authentication state
    ↓
User scans and confirms
    ↓
Account becomes connected
    ↓
Signed message events reach the webhook

The account is created with:

{
  "provider": "tiktok",
  "auth_mode": "qrcode"
}

Authentication then starts through:

POST /v1/accounts/{account_id}/auth/qr/start

The client checks progress through:

POST /v1/accounts/{account_id}/auth/qr/check

or:

GET /v1/accounts/{account_id}/auth

One important TikTok-specific detail is that the initial QR start response may not contain a QR URL.

That should not automatically be treated as an error.

Your interface must support an intermediate state in which authentication started successfully but the QR material is not available yet.

Model QR authentication as a state machine

Avoid implementing QR authentication as:

const response = await startQrAuthentication();

if (!response.qrUrl) {
  throw new Error("QR authentication failed");
}

That implementation incorrectly treats delayed QR material as failure.

Use an explicit state model instead:

idle
  ↓
starting
  ↓
waiting_for_qr
  ↓
qr_available
  ↓
waiting_for_scan
  ↓
authenticated

The flow may also terminate in:

expired
failed
cancelled

A polling loop can distinguish these outcomes:

async function waitForTikTokAuthentication(accountId) {
  const deadline = Date.now() + 2 * 60 * 1000;

  while (Date.now() < deadline) {
    const state = await checkQrAuthentication(accountId);

    if (state.qrUrl) {
      await displayQrCode(state.qrUrl);
    }

    if (state.status === "authenticated") {
      return state;
    }

    if (["expired", "failed", "cancelled"].includes(state.status)) {
      throw new Error(`Authentication ended with status: ${state.status}`);
    }

    await new Promise((resolve) => setTimeout(resolve, 2000));
  }

  throw new Error("Authentication polling timed out");
}

Use the documented response fields from the API instead of assuming the example property names above match every provider implementation.

The important design principle is that “QR URL not returned yet” and “authentication failed” are different states.

The architecture difference

The official API and QR-authenticated inbox also produce different system shapes.

TikTok-specific business integration

TikTok Business Account
        ↓
TikTok Business Messaging API
        ↓
TikTok-specific webhook adapter
        ↓
Application services

This model is a good fit when your product intentionally exposes TikTok-specific capabilities.

Normalized multi-channel intake

TikTok inbox ─────┐
WhatsApp inbox ───┤
LINE inbox ───────┤
Zalo inbox ───────┼→ Normalized webhook → Shared queue
Telegram inbox ───┤
X inbox ──────────┘

This model is a good fit when the operational problem is receiving and routing messages from several platforms.

It does not mean the platforms have identical features. It means the intake layer presents a shared event contract before provider-specific decisions are applied.

Store inbound events before routing them

Once authentication succeeds, incoming TikTok messages can be delivered as normalized message.received events.

For example:

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "tiktok",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-09-07T12:34:56Z",
  "data": {
    "conversation": {
      "id": "user_778899",
      "type": "user"
    },
    "sender": {
      "id": "user_778899",
      "type": "user",
      "name": "Jordan Lee"
    },
    "message": {
      "id": "msg_3003",
      "text": "Hi, is this item still available?",
      "direction": "inbound",
      "sent_at": "2026-09-07T12:34:55Z"
    },
    "event": {
      "kind": "message_received"
    }
  }
}

Do not send the message directly to business logic before storing it.

Use this order:

Verify signature
    ↓
Check event ID
    ↓
Store event
    ↓
Acknowledge delivery
    ↓
Route asynchronously

This protects the receiver from duplicate deliveries, downstream outages and slow CRM operations.

Verify the signed raw body

Webhook verification must happen before the event is trusted.

For UnifyPort webhook delivery, the receiver verifies X-Device-Signature using the endpoint’s signing_secret.

The signed input is constructed from:

X-Device-Timestamp + "." + raw request body

The signature uses HMAC-SHA256.

A simplified Express route should preserve the raw request body:

app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body;
    const timestamp = req.get("X-Device-Timestamp");
    const signature = req.get("X-Device-Signature");

    const valid = verifySignature({
      rawBody,
      timestamp,
      signature,
      signingSecret: process.env.UNIFYPORT_SIGNING_SECRET,
    });

    if (!valid) {
      return res.status(401).end();
    }

    const event = JSON.parse(rawBody.toString("utf8"));

    await storeEventIfAbsent(event);

    return res.status(200).end();
  },
);

Do not parse the JSON and then recreate it for signature verification. Re-serialization may change the exact bytes.

The verification function should also reject timestamps outside your accepted replay window and compare signatures using a timing-safe operation.

Make event storage idempotent

Webhook providers may retry delivery.

Use the event’s id as a unique key:

async function storeEventIfAbsent(event) {
  return database.events.insert({
    id: event.id,
    type: event.type,
    provider: event.provider,
    accountId: event.account_id,
    occurredAt: event.occurred_at,
    payload: event,
  }).onConflict("id").ignore();
}

The precise database syntax will vary, but the invariant should remain:

Processing the same event more than once must not create duplicate tickets, replies or notifications.

After storage, enqueue a separate routing job.

Normalize intake without hiding provider differences

A shared event contract makes common routing easier:

async function routeInboundMessage(event) {
  if (event.type !== "message.received") {
    return;
  }

  const message = {
    provider: event.provider,
    accountId: event.account_id,
    conversationId: event.data.conversation.id,
    senderId: event.data.sender.id,
    text: event.data.message.text,
  };

  await assignToQueue(message);
}

Common logic can handle:

persistence;
deduplication;
assignment;
CRM lookup;
notification;
SLA tracking;
AI classification.

Provider-specific behavior should remain explicit:

switch (message.provider) {
  case "tiktok":
    await applyTikTokPolicy(message);
    break;

  case "whatsapp":
    await applyWhatsAppPolicy(message);
    break;

  default:
    await applyDefaultPolicy(message);
}

Normalization should reduce duplicated infrastructure. It should not pretend that every platform has the same reply rules, media support, session behavior or business features.

Compare the operational responsibilities

The API surface is only part of the decision.

You also need to compare what your team will operate.

Responsibility	Official API	QR-authenticated inbox
Application authorization	TikTok business integration	UnifyPort API credentials
Account eligibility	Business Account requirements	Existing supported TikTok account
Session lifecycle	Platform-managed authorization model	QR authentication and possible re-authentication
Webhook verification	TikTok-specific contract	UnifyPort signed webhook contract
Message normalization	Build your own adapter	Shared event envelope
Multi-channel support	Separate provider integrations	Reusable intake pipeline
Feature guarantees	Official documented capabilities	Provider support matrix and current adapter behavior

Neither path eliminates operational work. It changes the kind of work your team owns.

Choose the official Business Messaging API when

Prefer TikTok’s official integration when:

TikTok Business Account identity is central to the product;
you need official business-messaging capabilities;
campaign attribution matters;
platform-managed automation is required;
your organization can complete the necessary reviews;
TikTok-specific features justify a dedicated adapter;
official program guarantees are more important than cross-channel uniformity.

This path should be evaluated against TikTok’s current documentation and access requirements.

Choose a QR-authenticated inbox when

Consider the QR path when:

an existing TikTok inbox already receives customer messages;
the immediate need is inbound message collection;
TikTok must enter the same queue as other messaging platforms;
the backend benefits from one signed event contract;
your team can manage session health and re-authentication;
you do not depend on TikTok-native business features;
the integration is operational rather than campaign-centric.

This path is especially useful when a support team wants to consolidate existing accounts without building an independent webhook adapter for every provider.

Do not confuse related TikTok APIs

TikTok exposes several integration surfaces that may sound similar.

Examples include:

Business Messaging API;
TikTok Shop Customer Service APIs;
content publishing APIs;
marketing and advertising APIs;
QR-authenticated account connections.

They should not be treated as interchangeable.

A TikTok Shop customer-support workflow may have different eligibility, data models and production requirements from a general Business Messaging integration.

Before choosing an endpoint, identify:

Account type
Product surface
Message source
Required operations
Region
Review requirements

Decision checklist

Before implementing either path, answer these questions:

[ ] Which TikTok account type will authorize the integration?
[ ] Does the product require official TikTok business features?
[ ] Is the workflow TikTok-only or multi-channel?
[ ] Does an operational TikTok inbox already exist?
[ ] Can the team complete platform access and review requirements?
[ ] Can the team operate QR session renewal safely?
[ ] How will webhook signatures be verified?
[ ] How will duplicate events be prevented?
[ ] Will events be stored before downstream processing?
[ ] Which provider-specific rules must remain outside the normalized layer?
[ ] What happens when authorization expires?
[ ] Which support matrix defines the features available today?

Takeaway

Do not select a TikTok DM integration by asking only:

Which endpoint lets me receive messages?

Ask:

Which identity, feature set and operating model should own this workflow?

Choose the official Business Messaging API when your product is built around TikTok Business Account capabilities.

Choose a QR-authenticated inbox when an existing operational account needs to join a signed, multi-channel inbound queue.

The right architecture depends less on whether both paths can deliver a message and more on what happens before authentication, after delivery, and when the connection needs ongoing maintenance.

References

This article was adapted from an original UnifyPort technical guide with AI-assisted editing.

Build a Reliable WhatsApp Group Join-Request Approval Queue with Node.js

unifyport — Wed, 02 Sep 2026 07:04:30 +0000

A WhatsApp group join request arrives.

Your backend receives a webhook, checks a few rules, and immediately approves the user.

That sounds convenient, but it creates a fragile moderation system.

Webhooks can be delayed, retried, delivered out of order, or missed. A requester may also disappear from the pending list before your moderator acts.

The safer architecture is:

Webhook signal
    ↓
Durable reconciliation job
    ↓
Fetch current pending requests
    ↓
Store and review
    ↓
Approve or reject exact requester IDs
    ↓
Reconcile again

The key principle is:

Use the webhook to wake up the system. Use the list endpoint to determine the current state.

This article demonstrates that pattern with Node.js and the UnifyPort API.

What WhatsApp still controls

WhatsApp group approval remains a group-admin feature.

When Approve new members is enabled, an administrator must approve people who request to join. According to the WhatsApp Help Center, this setting is disabled by default.

Your backend does not replace this permission model.

The connected WhatsApp account still needs the appropriate group permissions. Automation only helps answer the operational questions:

Who requested access?
Which group are they trying to join?
How did they arrive?
Who reviewed the request?
What decision was made?
Has WhatsApp accepted the decision?

Keep permission enforcement in WhatsApp and moderation policy in your own application.

The three API operations

A reliable approval queue uses three separate operations.

Operation	Purpose
`group.join_request` webhook	Low-latency notification that the pending state may have changed
List group join requests	Retrieve the current set of pending requesters
Update group join requests	Approve or reject selected requester IDs

Do not approve a user using only the data from the webhook.

Instead:

Receive and verify the webhook.
Enqueue a reconciliation job.
Fetch the current pending list.
Store the returned requester IDs.
Let a moderator or policy make the decision.
Submit the selected IDs to the update endpoint.

Example webhook event

A normalized WhatsApp group join-request event can look like this:

{
  "id": "evt_gjr_5e1c8a3f9b",
  "type": "group.join_request",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-09-02T05:10:30Z",
  "data": {
    "conversation": {
      "id": "120363041234567890@g.us",
      "type": "group"
    },
    "requester": {
      "id": "8613912345678@lid",
      "type": "user"
    },
    "request_method": "invite_link",
    "event": {
      "kind": "group_join_request"
    }
  }
}

Useful fields include:

id: webhook event ID;
account_id: connected WhatsApp account;
data.conversation.id: provider group ID;
data.requester.id: requester’s provider ID;
data.request_method: how the request was initiated, when available.

Store the event ID so webhook retries remain idempotent.

Verify before trusting the event

Webhook signatures must be verified against the raw HTTP request body.

Do not parse JSON, serialize it again, and then verify the reconstructed value. Even semantically identical JSON can produce different bytes.

A simplified Express route might look like this:

app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body;

    if (!verifyWebhookSignature(req.headers, rawBody)) {
      return res.status(401).end();
    }

    const event = JSON.parse(rawBody.toString("utf8"));

    if (event.type !== "group.join_request") {
      return res.status(200).end();
    }

    await handleJoinRequestSignal(event);

    return res.status(200).end();
  },
);

Keep signature verification isolated and test it using the exact header and signing contract documented for your webhook provider.

Make the receiver fast and idempotent

The webhook handler should not wait for a moderator decision.

Its job is to:

Verify the signature.
Check whether the event was already processed.
Store minimal event information.
Enqueue a reconciliation job.
Return a successful response quickly.

For example:

async function handleJoinRequestSignal(event) {
  const groupId = event.data.conversation.id;

  await database.transaction(async (transaction) => {
    const inserted = await transaction.insertWebhookEventIfAbsent({
      eventId: event.id,
      type: event.type,
      accountId: event.account_id,
      occurredAt: event.occurred_at,
    });

    if (!inserted) {
      return;
    }

    await transaction.enqueueReconciliation({
      key: `${event.account_id}:${groupId}`,
      accountId: event.account_id,
      groupId,
    });
  });
}

The unique eventId prevents duplicate webhook deliveries from creating duplicate work.

The reconciliation key prevents several events for the same group from producing an unnecessary burst of identical jobs.

Do not use an in-memory queue in production

A Map or array is useful for a local example:

const pending = new Map();

It is not a reliable production queue.

The state disappears when:

the process restarts;
the deployment replaces the instance;
the application crashes;
another instance receives the next webhook;
the platform scales the service horizontally.

Use durable infrastructure such as:

a database-backed jobs table;
Redis with a persistent queue library;
Amazon SQS;
Google Cloud Tasks;
RabbitMQ;
another queue with retry and visibility semantics.

The important requirement is that acknowledging the webhook must not discard the reconciliation work.

Fetch the current pending list

When the worker runs, fetch the group’s current join requests:

curl \
  "https://api.unifyport.ai/v1/accounts/acc_8c21d0/groups/join-requests?group_id=120363041234567890%40g.us" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

The group_id is passed as a query parameter and should be URL-encoded.

A Node.js worker can build the request safely:

async function listGroupJoinRequests({ accountId, groupId }) {
  const query = new URLSearchParams({
    group_id: groupId,
  });

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(
      accountId,
    )}/groups/join-requests?${query}`,
    {
      headers: {
        "X-Api-Key": process.env.UNIFYPORT_API_KEY,
      },
    },
  );

  if (!response.ok) {
    throw new Error(`Unable to list join requests: ${response.status}`);
  }

  return response.json();
}

Keep UNIFYPORT_API_KEY on the server. Never expose it to browser code or commit it to the repository.

Persist requesters before reviewing them

The list response is the reliable source for pending requests.

Persist each returned requester using a stable uniqueness rule such as:

account_id + group_id + member_id

A minimal record could contain:

const moderationRequest = {
  accountId: "acc_8c21d0",
  groupId: "120363041234567890@g.us",
  memberId: "8613912345678@lid",
  phone: null,
  requestMethod: "invite_link",
  requestedAt: "2026-09-02T05:10:30Z",
  status: "pending",
  decisionBy: null,
  decisionAt: null,
};

Do not use a display name as the primary identifier. Display names are not necessarily unique or stable.

Use the id returned by the list endpoint as the value that later enters member_ids.

Reconcile with upserts

A worker can upsert every currently pending request:

async function reconcileGroupJoinRequests({ accountId, groupId }) {
  const body = await listGroupJoinRequests({
    accountId,
    groupId,
  });

  for (const request of body.data.items) {
    await upsertModerationRequest({
      accountId,
      groupId: body.data.group_id,
      memberId: request.id,
      phone: request.phone ?? null,
      requestedAt: request.requested_at,
      status: "pending",
    });
  }

  await markMissingRequestsForReview({
    accountId,
    groupId,
    currentMemberIds: body.data.items.map((request) => request.id),
  });
}

Be careful with requests missing from a later list.

Their absence might mean they were:

approved elsewhere;
rejected elsewhere;
cancelled;
expired;
already processed by another moderator.

Do not automatically label every missing record as rejected unless the provider contract proves that interpretation.

A neutral state such as no_longer_pending is safer until you have more evidence.

Design the moderator workflow

The moderator UI should display enough information to make a decision without exposing unnecessary personal data.

Useful fields include:

group;
requester ID;
phone number, if returned and necessary;
request time;
request method;
current status;
assigned moderator.

A simple state machine could be:

pending
   ├── approving
   │      ├── approved
   │      └── pending
   └── rejecting
          ├── rejected
          └── pending

The intermediate states prevent two moderators from acting on the same request simultaneously.

For example:

async function claimDecision({
  accountId,
  groupId,
  memberId,
  action,
  moderatorId,
}) {
  return database.moderationRequests.updateMany({
    where: {
      accountId,
      groupId,
      memberId,
      status: "pending",
    },
    data: {
      status: action === "approve" ? "approving" : "rejecting",
      decisionBy: moderatorId,
    },
  });
}

Continue only if exactly one record was updated.

Approve or reject exact requester IDs

To approve a requester:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/acc_8c21d0/groups/join-requests/update" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "120363041234567890@g.us",
    "action": "approve",
    "member_ids": [
      "8613912345678@lid"
    ]
  }'

To reject the request, change the action:

{
  "group_id": "120363041234567890@g.us",
  "action": "reject",
  "member_ids": [
    "8613912345678@lid"
  ]
}

The value in member_ids must come from the list endpoint.

Do not substitute:

a display name;
a guessed phone-number format;
the group conversation ID;
an identifier copied from an unrelated event.

Wrap the decision in a service

async function updateJoinRequests({
  accountId,
  groupId,
  action,
  memberIds,
}) {
  if (!["approve", "reject"].includes(action)) {
    throw new Error("action must be approve or reject");
  }

  if (!Array.isArray(memberIds) || memberIds.length === 0) {
    throw new Error("memberIds must contain at least one requester ID");
  }

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(
      accountId,
    )}/groups/join-requests/update`,
    {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.UNIFYPORT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        group_id: groupId,
        action,
        member_ids: memberIds,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Unable to update join requests: ${response.status}`);
  }

  return response.json();
}

Call the external API only after your application has claimed the pending decision.

After success, save an audit record:

await saveModerationDecision({
  accountId,
  groupId,
  memberIds,
  action,
  moderatorId,
  decidedAt: new Date().toISOString(),
});

Never store the API key in the audit record.

Reconcile after the decision

A successful HTTP response confirms that the action request was accepted according to the API contract.

Your local queue should still reconcile the group afterward:

await updateJoinRequests({
  accountId,
  groupId,
  action: "approve",
  memberIds: [memberId],
});

await enqueueReconciliation({
  accountId,
  groupId,
});

The next list operation confirms which requests remain pending.

This catches situations where:

another moderator acted first;
a requester cancelled;
the group state changed;
a batch contained stale requester IDs;
the local view was outdated.

Webhook plus periodic polling

A webhook-triggered reconciliation gives low latency, but periodic polling closes delivery gaps.

A practical strategy is:

Webhook received → reconcile that group immediately
Every few minutes → reconcile active groups
Before moderation → refresh the selected group
After moderation → reconcile again

The polling interval depends on:

request volume;
acceptable moderation delay;
API limits;
number of active groups;
operational cost.

The goal is not to poll as frequently as possible. The goal is to ensure webhook delivery is not your only path to correct state.

Keep policy outside the transport layer

The webhook receiver should not contain business rules such as:

if (requesterPhone.startsWith("+86")) {
  approve();
}

Transport code should verify, store, and enqueue.

Moderation policy belongs in a separate service where it can be:

reviewed;
tested;
audited;
changed without touching signature verification;
overridden by a human moderator.

For example:

const recommendation = await evaluateJoinRequest({
  groupId,
  memberId,
  requestMethod,
});

await saveRecommendation({
  groupId,
  memberId,
  recommendation,
});

Even if the system generates an automated recommendation, keep the final action and its evidence auditable.

Failure scenarios to plan for

Duplicate webhooks

Use the webhook event ID as an idempotency key.

Missed webhooks

Run periodic list reconciliation.

Multiple events for one group

Deduplicate queued work using account_id + group_id.

Two moderators act simultaneously

Use an atomic status transition from pending to approving or rejecting.

Request disappears before review

Refresh the list and mark the local record no_longer_pending.

Worker crashes after the API request

Reconcile the list before retrying the external action.

Unauthorized account

Confirm the connected account has the required WhatsApp group-admin permissions. Automation cannot create permissions the account does not have.

Security and privacy checklist

Before deploying the queue, confirm that:

[ ] Webhook signatures are verified against the raw body.
[ ] Webhook event IDs are stored idempotently.
[ ] Reconciliation jobs use durable storage.
[ ] API keys remain server-side.
[ ] Logs do not contain API keys.
[ ] Moderator actions record who made the decision.
[ ] Only necessary requester data is displayed.
[ ] Requester IDs come from the list endpoint.
[ ] Missing requests are not automatically classified as rejected.
[ ] WhatsApp group permissions are checked operationally.
[ ] Periodic polling covers missed webhook delivery.
[ ] Post-decision reconciliation is enabled.

Takeaway

A webhook is an excellent wake-up signal, but it should not be your entire moderation database.

Build the approval queue around this sequence:

Verify
  ↓
Store
  ↓
Reconcile
  ↓
Review
  ↓
Approve or reject
  ↓
Reconcile again

This design remains reliable when webhooks are retried, events arrive out of order, moderators work concurrently, or the pending WhatsApp state changes outside your application.

Use WhatsApp’s group setting as the permission boundary, the pending-list endpoint as the current state, and your own database as the moderation and audit record.

References

This article was adapted from an original UnifyPort technical guide with AI-assisted editing.

Choosing the Right LINE Message UI: Confirm, Buttons, Quick Replies, Carousel, or Flex?

unifyport — Tue, 25 Aug 2026 07:53:44 +0000

You are building a LINE customer flow and start with a confirm template.

Then the requirements grow:

Confirm
Cancel
Change address
Contact support

At this point, the problem is no longer “How can I add more buttons to a confirm template?”

The real question is:

Which LINE message type matches the decision the user needs to make?

A LINE confirm template is intentionally limited to two actions. It is designed for one binary decision—not as a compact menu.

When the flow needs more choices, move to a buttons template, quick replies, a carousel, or a Flex Message instead of forcing the confirm component beyond its intended shape.

The short answer

LINE message surface	Best for	Main interaction limit
Confirm template	One binary decision	Two actions
Buttons template	A compact card with several primary actions	Up to four actions
Quick replies	A temporary next-step menu	Up to 13 quick reply buttons
Carousel template	Browsing repeated items	Multiple structured columns
Flex Message	Custom layouts and visual hierarchy	Flexible JSON-based layout

A useful rule is:

Two choices      → Confirm
Three or four    → Buttons
Five to thirteen → Quick replies
Repeated items   → Carousel
Custom layout    → Flex Message

The number of choices is not the only factor, but it is a good first filter.

What a confirm template is designed to do

A confirm template presents text followed by exactly two actions.

Typical examples include:

Confirm or cancel
Accept or decline
Approve or reject
Use this address or edit it
Contact support or continue browsing

A simplified request looks like this:

{
  "type": "template",
  "altText": "Please confirm your booking",
  "template": {
    "type": "confirm",
    "text": "Confirm your booking for tomorrow at 10:00?",
    "actions": [
      {
        "type": "postback",
        "label": "Confirm",
        "data": "action=confirm_booking"
      },
      {
        "type": "postback",
        "label": "Cancel",
        "data": "action=cancel_booking"
      }
    ]
  }
}

The two-action limit is not an arbitrary inconvenience. It protects the interaction model.

A confirm card asks one focused question:

Do you want to proceed?

If the card is trying to explain several unrelated paths, it is no longer a confirmation step.

Use a buttons template for three or four actions

A buttons template is a separate LINE template type.

Choose it when users need a few visible actions on one compact card, such as:

View order
Track delivery
Change address
Contact support

Unlike a confirm template, the buttons template can support up to four action objects.

It is a good fit when:

there are three or four important choices;
all choices belong to the same context;
the actions should remain visible on one card;
the content benefits from a title, text, or image.

Do not use four buttons merely because the component permits them. If one action is clearly primary and the others are secondary, consider simplifying the card or moving secondary options to the next step.

Use quick replies for temporary menus

Quick replies are useful when users need several immediate choices without a large permanent card.

For example:

Where should we route your request?

Billing
Delivery
Returns
Technical support
Sales
Other

LINE supports up to 13 quick reply buttons.

That makes quick replies appropriate for:

short category lists;
selecting the next workflow step;
choosing a language;
selecting a date or location;
answering a question immediately.

However, quick replies are temporary interface elements. They can disappear as the conversation moves forward.

Do not use them for actions users must be able to return to later.

If an option needs to remain available, consider:

a buttons template;
a rich menu;
a carousel;
a Flex Message;
sending the menu again when needed.

Use a carousel for repeated objects

A carousel is better when users are selecting between repeated items with the same structure.

Examples include:

products;
subscription plans;
store locations;
appointment slots;
support topics;
delivery options.

Instead of presenting a flat list of unrelated buttons, each carousel column can represent one item:

Product A
Image
Price
View
Buy

Product B
Image
Price
View
Buy

Product C
Image
Price
View
Buy

A carousel works well when users need to compare multiple objects.

It is a poor fit when the choices are simple workflow actions such as “confirm” and “cancel.” In that case, the additional visual structure only adds friction.

Use Flex Messages for custom hierarchy

A Flex Message is the most adaptable option.

Use it when the interaction depends on:

custom branding;
more complex visual hierarchy;
multiple content sections;
responsive layout;
structured summaries;
information-dense cards.

For example, an order confirmation might need to display:

Order number
Items
Delivery address
Payment status
Total
Primary action
Secondary action

A Flex Message can express that hierarchy more clearly than a template with a fixed structure.

The trade-off is complexity.

Flex Messages require:

more JSON;
more layout decisions;
more rendering tests;
checking different screen sizes;
validating fallback and accessibility text.

Do not choose Flex merely because it is flexible. Use it when the product experience actually needs a custom layout.

A practical decision function

You can model the initial choice in application code:

function chooseLineSurface({
  actionCount,
  isBinaryDecision,
  isTemporary,
  representsRepeatedItems,
  needsCustomLayout,
}) {
  if (isBinaryDecision && actionCount === 2) {
    return "confirm";
  }

  if (representsRepeatedItems) {
    return "carousel";
  }

  if (needsCustomLayout) {
    return "flex";
  }

  if (actionCount <= 4 && !isTemporary) {
    return "buttons";
  }

  if (actionCount <= 13 && isTemporary) {
    return "quickReplies";
  }

  return "redesignRequired";
}

This is not a replacement for product judgment, but it makes the component boundaries explicit.

If the function returns redesignRequired, splitting the interaction into multiple steps is usually better than placing every possible action in one message.

A complete decision tree

Ask these questions in order.

1. Is this one binary decision?

Examples:

Yes / No
Accept / Decline
Confirm / Cancel

Use a confirm template.

2. Are there three or four primary actions?

Use a buttons template.

Check whether all actions actually belong to the same card. If not, simplify the flow.

3. Are there several temporary next steps?

Use quick replies.

Design the workflow assuming those buttons may no longer be visible after the conversation continues.

4. Is the user comparing repeated objects?

Use a carousel.

Keep the column structure consistent so users can compare options easily.

5. Does the experience need a custom visual hierarchy?

Use a Flex Message.

Test the final JSON on different devices rather than assuming one preview represents every client.

6. Is the real problem receiving and routing the reply?

That is a separate architectural concern.

Use the official LINE Messaging API to render LINE-native UI. Then process the user’s reply through your inbound message pipeline.

Separate outbound presentation from inbound handling

The component used to send a message and the system used to process the response do not need to be the same layer.

A clean architecture separates them:

Official LINE Messaging API
        ↓
Render confirm, buttons, carousel, or Flex UI
        ↓
User taps or sends a reply
        ↓
Inbound webhook
        ↓
Queue, CRM, support system, or automation

This matters for multi-channel systems.

Your application may use LINE-native components for outbound presentation while routing incoming LINE replies through the same backend that handles WhatsApp, Telegram, Zalo, TikTok, and X.

UnifyPort fits this inbound side. It does not render native LINE confirm templates, buttons templates, carousel templates, or Flex Messages.

An inbound LINE event can use a normalized envelope such as:

{
  "id": "evt_01j7lineconfirm8p7m4w6n2a",
  "type": "message.received",
  "provider": "line",
  "account_id": "acct_line_support_01",
  "occurred_at": "2026-08-25T09:30:00Z",
  "data": {
    "message": {
      "id": "msg_line_4281",
      "direction": "inbound",
      "type": "text",
      "text": "Confirm"
    },
    "conversation": {
      "id": "conv_line_2841"
    },
    "sender": {
      "id": "user_line_73"
    }
  }
}

The backend can then route the event according to provider and reply content:

async function handleMessageReceived(event) {
  if (event.type !== "message.received") {
    return;
  }

  const message = {
    provider: event.provider,
    accountId: event.account_id,
    conversationId: event.data.conversation.id,
    senderId: event.data.sender.id,
    text: event.data.message.text,
  };

  await routeInboundMessage(message);
}

The same handler can accept events from multiple providers without pretending that every provider offers identical outbound UI components.

Common design mistakes

Forcing a third action into a confirm flow

If a binary decision suddenly needs a third option, review the product requirement.

The third option may indicate that the interaction is actually a menu, not a confirmation.

Using quick replies for permanent navigation

Quick replies are temporary. Important navigation should use a surface designed to remain accessible.

Using Flex for every message

Flex provides control, but it also increases implementation and testing cost. Fixed templates are often better for simple interactions.

Treating all channels as visually identical

A normalized inbound event does not mean LINE, WhatsApp, Telegram, and other providers support the same outbound UI.

Keep provider capabilities explicit.

Combining outbound UI and inbound routing decisions

Choosing a LINE confirm template does not determine how your backend should store, assign, or route the response.

Design those layers separately.

Implementation checklist

Before selecting a LINE message surface, confirm that:

[ ] A confirm template contains one binary decision.
[ ] The confirm template has exactly two actions.
[ ] Three or four visible actions use a buttons template.
[ ] Temporary menus use quick replies.
[ ] Repeated items use a carousel.
[ ] Custom visual hierarchy uses a Flex Message.
[ ] Flex layouts are tested across devices.
[ ] Important actions do not depend on temporary quick replies.
[ ] Official LINE APIs handle LINE-native presentation.
[ ] Inbound replies are processed by a separate webhook pipeline.
[ ] Other providers are not assumed to support the same UI.

Takeaway

Do not choose a LINE message component by asking:

How can I fit all these actions into one template?

Ask:

What kind of decision is the user making?

Use:

Confirm template → one binary decision
Buttons template → a few primary actions
Quick replies    → temporary next steps
Carousel         → repeated items
Flex Message     → custom visual hierarchy

The best component is the one that makes the next decision obvious—not the one that can technically contain the most buttons.

References

This article was adapted from an original UnifyPort technical guide with AI-assisted editing.

Building Reliable WhatsApp Read/Unread Sync for a Shared Inbox

unifyport — Fri, 21 Aug 2026 03:36:29 +0000

A shared inbox receives a new WhatsApp message.

Should the conversation immediately become “read”?

Usually, no.

Receiving a webhook only proves that your system received an event. It does not prove that an agent accepted the conversation, understood the request, or completed the work.

A reliable shared inbox must keep three different kinds of state separate:

Your application’s queue state.
The connected WhatsApp account’s read/unread state.
Message-level read receipts.

Combining these concepts can make unattended conversations disappear from the queue or create synchronization loops between your application and WhatsApp.

This article uses the UnifyPort API to demonstrate a safer design.

Three meanings of “read”

The word “read” can refer to three different things in a messaging system.

1. Local queue state

This is the workflow state stored by your application:

new
assigned
waiting
resolved

Your database should also know:

which agent owns the conversation;
when it was accepted;
why it was reopened;
whether a response is still required;
when the next follow-up is due.

This is your support system’s source of truth.

2. WhatsApp conversation state

The connected WhatsApp account also maintains a chat-list state:

read
unread

Changing this state affects how the conversation appears in the connected account.

It does not replace your application’s assignment and resolution model.

3. Message read receipts

A message.read event describes a recipient reading one or more messages sent through the account.

That is different from an agent opening an inbound support ticket.

The three states may influence one another, but they should not be stored as one Boolean value.

Define an explicit synchronization policy

Do not mark every conversation as read as soon as message.received reaches your webhook.

That policy can make an unattended queue look healthy.

Instead, connect provider state to meaningful team actions:

Team action	Local queue state	WhatsApp action
Inbound message stored	`new`	None
Agent accepts the conversation	`assigned`	Optionally mark through the accepted message
Agent resolves the conversation	`resolved`	Mark the conversation read
Agent requests follow-up	`waiting`	Mark the conversation unread
Automation fails before assignment	`new`	None

This prevents webhook retries, background previews, and browser refreshes from clearing work accidentally.

Mark a WhatsApp conversation as read

To mark an entire conversation as read, call:

POST /v1/accounts/{account_id}/conversations/read

Pass the provider conversation identifier in the JSON body:

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/$UNIFYPORT_ACCOUNT_ID/conversations/read" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "8613912345678@s.whatsapp.net"
  }'

The conversation_id belongs in the body instead of the URL because provider identifiers may contain characters such as @ and :.

Mark through a specific message

For a message-level WhatsApp receipt, include both:

up_to_message_id
up_to_message_sender_id

Example:

{
  "conversation_id": "120363041234567890@g.us",
  "up_to_message_id": "CURRENT-MESSAGE-ID",
  "up_to_message_sender_id": "8613912345678@lid"
}

These two fields form a pair.

Sending only one of them returns:

400 invalid_request

Copy all three identifiers from the same verified message.received event:

const identifiers = {
  conversationId: event.data.conversation.id,
  messageId: event.data.message.id,
  senderId: event.data.sender.id,
};

For a group conversation, do not derive the sender ID from the conversation ID. Use the matching event.data.sender.id.

If you do not need a message-specific receipt, omit both up_to_message_* fields and mark the whole conversation as read.

Build a small read-state helper

A helper can enforce the field-pair rule before making the request:

const apiBase = "https://api.unifyport.ai/v1";

async function setWhatsAppReadState({
  accountId,
  conversationId,
  unread,
  message,
}) {
  const action = unread ? "unread" : "read";
  const body = {
    conversation_id: conversationId,
  };

  if (!unread && message) {
    if (!message.id || !message.senderId) {
      throw new Error(
        "message.id and message.senderId must be supplied together",
      );
    }

    body.up_to_message_id = message.id;
    body.up_to_message_sender_id = message.senderId;
  }

  const response = await fetch(
    `${apiBase}/accounts/${encodeURIComponent(accountId)}/conversations/${action}`,
    {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.UNIFYPORT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    },
  );

  if (!response.ok) {
    const failure = await response.json();

    throw new Error(
      `${response.status} ${failure.error?.code ?? "unknown_error"}`,
    );
  }

  return response.json();
}

Keep the API key on the server. Do not call this endpoint directly from browser code.

After verifying and storing an inbound event, an agent-acceptance workflow could call:

await setWhatsAppReadState({
  accountId: event.account_id,
  conversationId: event.data.conversation.id,
  unread: false,
  message: {
    id: event.data.message.id,
    senderId: event.data.sender.id,
  },
});

Mark a conversation unread

When an agent intentionally reopens a conversation, call the unread action:

POST /v1/accounts/{account_id}/conversations/unread

Using the same helper:

await setWhatsAppReadState({
  accountId: event.account_id,
  conversationId: event.data.conversation.id,
  unread: true,
});

The unread action only requires conversation_id.

Do not use the provider’s unread state as your only reminder mechanism. Store the follow-up owner, reason, and due time in your own database.

For example:

await saveFollowUp({
  conversationId: event.data.conversation.id,
  ownerId: agent.id,
  reason: "Waiting for customer documents",
  dueAt: nextBusinessDay,
});

await setWhatsAppReadState({
  accountId: event.account_id,
  conversationId: event.data.conversation.id,
  unread: true,
});

If the provider action fails, the local follow-up record still preserves the work that must be completed.

Avoid synchronization feedback loops

When your application changes conversation state, a corresponding conversation.updated event may arrive at your webhook.

A naive implementation can produce a loop:

Application marks conversation read
        ↓
conversation.updated arrives
        ↓
Webhook handler marks conversation read again
        ↓
Another update arrives

Treat conversation.updated as a reconciliation signal, not a command to repeat the same action.

A safer workflow is:

1. Verify the webhook signature
2. Store the event idempotently
3. Update the local ticket state
4. Record the intended provider-state operation
5. Call the read/unread endpoint
6. Record success after the API confirms it
7. Use conversation.updated as confirmation

An operation record could contain:

const operation = {
  conversationId,
  requestedState: "read",
  source: "agent_acceptance",
  status: "pending",
};

When conversation.updated arrives, compare it with the pending operation.

If it matches, confirm the operation instead of issuing the API request again.

If there is no matching local operation, the state may have changed from the connected WhatsApp account or another system. Reconcile it according to your product policy.

Store webhook events idempotently

Webhook delivery can be retried.

Before updating queue state, ensure the event has not already been processed:

async function handleWebhook(event) {
  const existing = await findProcessedEvent(event.id);

  if (existing) {
    return;
  }

  await database.transaction(async (transaction) => {
    await transaction.saveEvent(event);
    await transaction.updateConversation(event);
  });
}

The exact database implementation will vary, but the invariant should remain:

Processing the same webhook more than once must not create additional state transitions.

Also verify the webhook signature against the raw request body before trusting any event fields.

Keep local state authoritative

Provider read state is useful for synchronization and operator visibility, but it is not a complete support database.

The provider does not know:

which agent accepted the ticket;
whether the issue was resolved;
why the conversation was reopened;
whether a service-level deadline is approaching;
which internal team owns the next action.

A practical local model might look like this:

const conversation = {
  id: "local-conversation-id",
  providerConversationId: "8613912345678@s.whatsapp.net",
  queueState: "assigned",
  providerReadState: "read",
  assignedAgentId: "agent-42",
  followUpAt: null,
  lastProcessedEventId: "event-123",
};

Here, providerReadState is a projection of WhatsApp state. It does not determine whether the support task is finished.

Handle unsupported providers correctly

Read and unread conversation actions are currently supported for WhatsApp.

An unsupported provider/action combination returns:

501 unsupported_by_provider

Do not treat this response as a temporary network failure. Retrying the same unsupported operation will not make it succeed.

For a multi-channel inbox, check capabilities before displaying the control:

function canChangeProviderReadState(provider) {
  return provider === "whatsapp";
}

If the provider is unsupported:

hide or disable the provider-state control;
keep the local queue workflow available;
explain that the action only affects internal state;
do not continuously retry 501 unsupported_by_provider.

A unified API route does not imply that every provider implements every action.

Implementation checklist

Before enabling read/unread synchronization, confirm that:

[ ] Queue state and provider read state are stored separately.
[ ] Receiving message.received does not automatically clear work.
[ ] Webhook signatures are verified using the raw request body.
[ ] Webhook processing is idempotent.
[ ] up_to_message_id and up_to_message_sender_id are always sent together.
[ ] Group sender IDs come from event.data.sender.id.
[ ] Locally initiated operations are recorded.
[ ] conversation.updated is used for reconciliation.
[ ] Follow-up ownership and reasons are stored locally.
[ ] Unsupported providers do not receive repeated read/unread requests.
[ ] API keys remain on the server.

Takeaway

A reliable shared inbox should not reduce every kind of read state to one Boolean value.

Keep these concepts separate:

Local queue state
Provider conversation state
Message receipt state

Change the WhatsApp read state only when a meaningful workflow action occurs, such as agent acceptance, resolution, or an intentional follow-up.

Then treat provider events as reconciliation signals while keeping assignment, ownership, and resolution state in your own database.

That separation prevents unattended conversations from disappearing and keeps your shared inbox reliable when webhooks are retried or multiple systems update the same chat.

References

This article was adapted from an original UnifyPort technical guide with AI-assisted editing.

Zero-Downtime API Key Rotation: Why You Shouldn’t Call Rotate First

unifyport — Mon, 17 Aug 2026 06:57:22 +0000

API key rotation sounds like a single operation:

Old key → Rotate → New key

In a production system, that sequence can cause an authentication outage.

The problem is not generating the new credential. The problem is that your web servers, background workers, scheduled jobs, and operational scripts do not all start using it at the same moment.

With the UnifyPort API, calling:

POST /v1/api-keys/{key_id}/rotate

invalidates the old key immediately.

That behavior is useful during a credential leak, but it is usually the wrong starting point for an ordinary rolling deployment.

For zero-downtime rotation, use a controlled overlap:

Create → Store → Test → Deploy → Verify → Deactivate

The two rotation strategies

Strategy	Old key	Best use case
Call the rotate endpoint	Invalidated immediately	Suspected credential exposure or coordinated maintenance
Create a second key, then deactivate the old one	Remains active during deployment	Normal rolling deployments

The distinction matters because a production deployment rarely changes every process atomically.

During a rolling release, some instances may already use the new configuration while others are still completing requests with the previous configuration. If the old key is revoked too early, otherwise healthy requests begin failing with:

401 invalid_api_key

A safer mental model

Treat credential rotation as a migration, not a single API call.

The application moves through four states:

State 1: Old key active
State 2: Old and new keys active
State 3: All callers use the new key
State 4: Old key inactive

State 2 is the overlap window that protects availability.

Keep that window short, but do not eliminate it until you have evidence that every caller has migrated.

Step 1: Inventory every API caller

Before creating or revoking anything, identify every component that sends X-Api-Key to the API.

Typical callers include:

public web and API services;
queue consumers;
background workers;
scheduled jobs;
webhook handlers that send replies;
health checks;
production support scripts;
regional deployments.

Do not confuse an API key with a webhook signing_secret.

They protect different directions of communication:

Credential	Purpose
`X-Api-Key`	Authenticates requests your application sends to the REST API
`signing_secret`	Verifies webhook requests delivered to your endpoint

Rotating one does not rotate the other.

You can inspect existing API key records with:

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

The response includes metadata such as:

id
name
key_prefix
status

It does not return the complete secret.

Step 2: Create a second active key

For a normal deployment, create another key instead of rotating the existing one:

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

A successful 201 response returns:

key metadata under data.key;
the complete new secret under data.api_key.

The full value is returned only once.

Capture it directly into your approved secret-management system. Do not:

print it in deployment logs;
paste it into a ticket;
send it through chat;
commit it to the repository;
assume it can be retrieved from the list endpoint later.

If the value is lost before deployment, create another key and deactivate the unused record.

A key prefix is metadata, not enough information to recover the secret.

Step 3: Test the new key before deployment

Before changing application configuration, prove that the new credential can authenticate successfully.

Use a read-only endpoint:

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

A successful response confirms that the key resolves to the expected workspace.

This is only the first verification gate. It proves that the credential works, but it does not prove that every application instance has loaded it.

Keep the old key active and deploy the new secret through your normal configuration system.

Step 4: Roll out and verify every caller

Update each caller in controlled batches.

For example:

1. Web/API instances
2. Queue consumers
3. Background workers
4. Scheduled jobs
5. Operational scripts

For each group, verify:

the deployment completed;
processes restarted or reloaded their configuration;
authenticated requests succeed;
no instance still references the old secret;
scheduled jobs will load the new value on their next run;
emergency scripts have also been updated.

Do not assume the migration is complete just because one HTTP request succeeded.

Also avoid relying on metadata that the API does not provide. If the key-list response does not expose per-key last-used analytics, it cannot prove that the old key is unused.

Use deployment state and application-side request results as your evidence.

A simple internal checklist might look like this:

const rollout = {
  web: "verified",
  workers: "verified",
  scheduledJobs: "verified",
  supportTools: "verified",
};

const safeToDeactivate = Object.values(rollout).every(
  (status) => status === "verified",
);

The exact implementation is less important than making the verification state explicit.

Step 5: Deactivate the old key

After every caller is confirmed on the new credential, deactivate the old record using the new key:

curl -X PATCH \
  "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

The documented API key states are:

active
inactive

After deactivation, make one controlled read-only request with the old credential and confirm that it returns:

401 invalid_api_key

Do not use a real customer request or production job as the test.

Finally, remove the retired secret from:

deployment configuration;
CI/CD variables;
local environment files;
temporary migration files;
operational scripts.

The change record should contain non-secret metadata only, such as the key ID, key name, owner, status, deployment version, and cutover time.

When immediate rotation is the right choice

The dedicated rotate endpoint is appropriate when immediate invalidation is the requirement.

Examples include:

the old credential may have leaked;
it appeared in a log or repository;
an unauthorized person may have accessed it;
all callers can switch together during a maintenance window.

The incident-response sequence is different:

1. Stop or isolate callers using the old key
2. Call the rotate endpoint
3. Capture the new secret once
4. Update every credential consumer
5. Restore traffic
6. Verify authentication

In this situation, revocation speed is more important than continuous availability.

Do not keep a potentially compromised credential active merely to preserve an overlap window.

The trade-off of overlapping keys

A zero-downtime migration briefly leaves two valid credentials active.

That creates a larger credential surface for a limited period, so the overlap should be:

planned;
monitored;
access-controlled;
as short as operationally practical.

This is a deliberate availability-versus-exposure trade-off.

For a normal rolling deployment, the short overlap prevents avoidable outages. For a security incident, immediate revocation usually takes priority.

Rotation checklist

Before deactivating the old key, confirm all of the following:

[ ] Every API caller has been identified.
[ ] A second active key has been created.
[ ] The one-time secret is stored securely.
[ ] GET /v1/workspace succeeds with the new key.
[ ] Web and API instances use the new key.
[ ] Workers and queue consumers use the new key.
[ ] Scheduled jobs will load the new key.
[ ] Operational scripts have been updated.
[ ] Authenticated production paths have been verified.
[ ] The old key has been changed to inactive.
[ ] A controlled request confirms the old key is rejected.
[ ] The retired value has been removed from configuration.

Takeaway

An API named rotate does not necessarily provide a zero-downtime migration.

Always check the endpoint’s actual contract.

If rotation invalidates the old credential immediately, use it for urgent revocation or a coordinated cutover.

For an ordinary rolling deployment, the safer sequence is:

Create a second key
        ↓
Store it securely
        ↓
Test it
        ↓
Deploy it everywhere
        ↓
Verify every caller
        ↓
Deactivate the old key

The key idea is simple: prove that the new credential is in use before removing the old one.

References

This article was adapted from an original UnifyPort technical guide with AI-assisted editing.

WhatsApp Contact APIs: Add a Contact or Send a vCard?

unifyport — Fri, 14 Aug 2026 07:21:17 +0000

Two Similar Requests, Two Different Operations

“Add this person to WhatsApp contacts” and “send this person’s contact card” may sound similar, but they describe two different API operations.

Add a contact changes the connected WhatsApp account’s address book.
Send a vCard delivers structured contact information inside a conversation.

Sending a vCard does not save that person to the connected account’s contacts. Adding a contact does not send anything to a user.

Choosing the wrong operation can create confusing workflows, duplicate mutations, and incorrect retry behavior.

Quick Decision Table

Requirement	API operation	Result
Save someone to the connected account’s contact list	`POST /v1/accounts/{account_id}/contacts/add`	Returns a contact object and identifiers
Share a person’s contact details in a chat	`POST /v1/messages` with `message.type: "contact"`	Returns an accepted message result
Save a customer and send a representative’s card	Call both operations separately	Two independent results and retry paths

The key distinction is state versus content:

Add contact
    -> changes account state

Send vCard
    -> sends conversation content

Option 1: Add a Contact to the Connected Account

Use the add-contact operation when your application needs to save someone to the connected WhatsApp account’s contact list.

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/acc_example/contacts/add" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "15550001111",
    "whatsapp_options": {
      "first_name": "Jane",
      "full_name": "Jane Doe",
      "sync_to_device_contacts": false
    }
  }'

The request must contain at least one of:

phone_number
username

WhatsApp-specific fields belong inside whatsapp_options:

first_name
full_name
sync_to_device_contacts

Do not move these fields to the top level of the request.

A successful response returns the contact representation. Preserve identifiers such as id and conversation_id from the response.

Do not construct a conversation identifier from the phone number. The provider’s canonical identifier may use a different format, so the API response should remain the source of truth.

See the complete Add contact API reference.

Option 2: Send a vCard in a Conversation

Use the unified message endpoint when the requirement is to share contact details with a user or group.

curl -X POST \
  "https://api.unifyport.ai/v1/messages" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_example",
    "to": {
      "id": "15550002222@s.whatsapp.net",
      "type": "user"
    },
    "message": {
      "type": "contact",
      "contacts": [
        {
          "name": "Jane Doe",
          "phones": [
            {
              "number": "+15550001111",
              "type": "CELL"
            }
          ],
          "emails": [
            {
              "address": "jane@example.com"
            }
          ],
          "organization": "Example Company",
          "title": "Product Manager"
        }
      ]
    }
  }'

Every card in message.contacts requires a non-empty name.

The following fields are optional:

phones[].number
phones[].type
emails[].address
organization
title

You can send one or multiple contact cards in the same request.

The API generates the vCard from structured JSON, so you do not need to construct raw BEGIN:VCARD content manually.

See the complete Send contact message API reference.

Why These Calls Should Remain Separate

Consider a customer-support handoff:

Save the customer to the connected WhatsApp account.
Send the customer a contact card for the assigned account manager.

Although both steps involve contacts, they have different side effects.

Step 1: Add customer
Result: Address-book mutation

Step 2: Send account manager's card
Result: Outbound message

Store the two results independently.

A successful address-book update does not prove that the contact message was accepted. An accepted contact message does not prove that the address book changed.

This separation becomes especially important during retries.

If sending the vCard fails after the contact was successfully added, retry only the message operation. Repeating the already successful address-book mutation adds unnecessary work and may produce provider-specific conflicts.

Model the Workflow Explicitly

A simple TypeScript workflow could look like this:

type ContactWorkflowResult = {
  addedContactId?: string;
  conversationId?: string;
  sentMessageId?: string;
};

async function addCustomerAndSendRepresentativeCard(
  accountId: string,
  customerPhone: string,
): Promise<ContactWorkflowResult> {
  const result: ContactWorkflowResult = {};

  const contact = await addContact({
    accountId,
    phoneNumber: customerPhone,
    whatsappOptions: {
      fullName: "Customer",
      syncToDeviceContacts: false,
    },
  });

  result.addedContactId = contact.id;
  result.conversationId = contact.conversation_id;

  const message = await sendContactMessage({
    accountId,
    to: {
      id: contact.conversation_id,
      type: "user",
    },
    contacts: [
      {
        name: "Jane Doe",
        phones: [{ number: "+15550001111", type: "CELL" }],
        organization: "Example Company",
        title: "Account Manager",
      },
    ],
  });

  result.sentMessageId = message.message_id;

  return result;
}

In a production system, persist the successful result of each step before starting the next one. That allows a failed workflow to resume from the correct operation.

Handle Errors by Operation

Do not place every contact-related error into one generic handler.

Operation	Error	Meaning
Add contact	`400 invalid_request`	Neither `phone_number` nor `username` is valid or present
Add contact	`501 unsupported_by_provider`	The provider does not implement address-book contact creation
Send vCard	`400 invalid_request`	The contacts array is empty or a card is missing `name`
Send vCard	`400 unsupported_message_type`	The selected account does not support structured contact messages

A practical error-handling structure is:

try {
  await executeContactOperation();
} catch (error) {
  switch (error.code) {
    case "invalid_request":
      // Correct the request instead of retrying it unchanged.
      break;

    case "unsupported_by_provider":
    case "unsupported_message_type":
      // Use a documented fallback or disable the feature.
      break;

    default:
      // Apply bounded retry rules only to transient failures.
      throw error;
  }
}

Validation and capability errors should not be retried with the same request.

For transient failures, use bounded retries and an idempotency strategy appropriate to the operation. Never treat a message retry as permission to repeat a completed address-book mutation.

Design a Cross-Provider Fallback

Structured contact messages are currently WhatsApp-specific in this integration.

Before exposing a universal “send contact” button across WhatsApp, Telegram, LINE, TikTok, Zalo, and X, check the provider message support matrix.

When structured cards are unavailable, a text fallback can preserve the essential information:

Jane Doe
Product Manager, Example Company
Phone: +1 555-000-1111
Email: jane@example.com

Make the fallback explicit in your product design. Silently converting structured content can create inconsistent formatting and privacy behavior across channels.

Keep Personal Data Minimal

Contact cards can contain personal information. Only include fields needed for the actual workflow.

Avoid sending phone numbers, email addresses, job titles, or organization details simply because the schema allows them.

Also remember that sending a vCard does not force the recipient to save it. The recipient’s WhatsApp client and their own actions determine how the card is displayed and whether it becomes a saved contact.

Implementation Checklist

Before shipping, verify that:

The product requirement distinguishes address-book changes from chat messages.
Add-contact requests contain phone_number or username.
WhatsApp-specific fields are placed under whatsapp_options.
Returned contact and conversation identifiers are persisted.
Contact messages contain a non-empty contacts array.
Every card contains name.
Add and send results are recorded independently.
Retries resume from the failed step.
Capability errors do not enter an automatic retry loop.
Unsupported providers have an explicit fallback.
Only necessary personal data is included.
Tests confirm that sending a vCard does not trigger contact creation.

Final Takeaway

Use /contacts/add when you need to change the connected WhatsApp account’s contact list.

Use /v1/messages with message.type: "contact" when you need to deliver contact details inside a chat.

Some workflows need both, but they should remain two explicit operations with separate results, errors, and retry policies.

Originally published on UnifyPort.

Disclosure: AI-assisted drafting and editing were used to prepare this DEV adaptation. The technical content was reviewed against the linked API documentation.

TikTok Shop Customer Service Webhooks: A Production-Ready Implementation Guide

unifyport — Tue, 11 Aug 2026 03:22:12 +0000

Receiving a webhook is easy.

Building a webhook pipeline that survives duplicate deliveries, delayed events, missing messages, invalid signatures, and seller authorization changes is the real engineering work.

This guide explains how to build a production-ready pipeline for TikTok Shop Customer Service messages—from HTTPS ingress to history reconciliation.

First, Understand the Scope

TikTok Shop Customer Service API is designed for conversations between buyers and sellers in a TikTok Shop.

It is not an API for reading ordinary TikTok direct messages.

Before implementation, confirm that:

Your application has access to the required Customer Service API scopes.
The seller has authorized your application.
The target shop is correctly mapped to your internal workspace or tenant.
Your webhook endpoint is publicly accessible over HTTPS.

Customer Service API access is inactive by default and requires approval. See the official Customer Service API overview and app features documentation.

If these prerequisites are missing, changing webhook code will not solve the problem.

Recommended Architecture

A reliable implementation separates webhook acknowledgement from business processing:

TikTok Shop
    |
    v
HTTPS webhook ingress
    |
    +-- Verify signature using raw request body
    |
    +-- Insert event into a durable inbox
    |
    +-- Return HTTP 200 within 3 seconds
    |
    v
Message queue
    |
    v
Normalize, deduplicate, and route
    |
    v
Customer service workspace
    ^
    |
History reconciliation worker

The webhook request should not wait for:

CRM updates
AI-generated replies
Media downloads
Ticket creation
Search indexing
External notifications

Persist the event, acknowledge it, and process it asynchronously.

Subscribe to the New Message Event

For incoming customer service messages, subscribe to NEW_MESSAGE, identified as event type 14.

You can configure the subscription in TikTok Shop Partner Center or through the webhook configuration API.

The official event reference is available in the New Message webhook documentation.

Useful fields from the payload include:

tts_notification_id
shop_id
message_id
conversation_id
index
create_time
type
visibility
Sender information

Preserve these identifiers before converting the payload into your internal message model. They are essential for deduplication, routing, ordering, and incident investigation.

Verify the Signature Before Parsing

TikTok Shop sends the webhook signature in the Authorization header.

According to the official webhook overview, the signature is generated with HMAC-SHA256 using:

Signature content: app_key followed by the raw webhook body
Signing key: the application's app_secret

The important word here is raw.

If your framework parses and serializes the JSON before verification, whitespace or character encoding changes can invalidate an otherwise legitimate signature.

A Node.js implementation can look like this:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyTikTokShopWebhook(
  rawBody: Buffer,
  authorization: string,
  appKey: string,
  appSecret: string,
): boolean {
  const expected = createHmac("sha256", appSecret)
    .update(appKey)
    .update(rawBody)
    .digest("hex");

  const actual = authorization.trim().toLowerCase();

  if (!/^[a-f0-9]{64}$/.test(actual)) {
    return false;
  }

  const actualBuffer = Buffer.from(actual, "hex");
  const expectedBuffer = Buffer.from(expected, "hex");

  return (
    actualBuffer.length === expectedBuffer.length &&
    timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

Use constant-time comparison and never log app_secret.

If you use Express, configure raw-body handling specifically for the webhook route:

import express from "express";

const app = express();

app.post(
  "/webhooks/tiktok-shop",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const authorization = req.header("authorization") ?? "";
    const rawBody = req.body as Buffer;

    if (
      !verifyTikTokShopWebhook(
        rawBody,
        authorization,
        process.env.TIKTOK_SHOP_APP_KEY!,
        process.env.TIKTOK_SHOP_APP_SECRET!,
      )
    ) {
      return res.status(401).send();
    }

    const payload = JSON.parse(rawBody.toString("utf8"));

    await webhookInbox.insertIfAbsent({
      notificationId: payload.tts_notification_id,
      shopId: payload.shop_id,
      payload,
    });

    return res.status(200).send();
  },
);

Make sure another global JSON middleware does not consume this route first.

Acknowledge Within Three Seconds

TikTok Shop requires a successful webhook response to:

Use HTTP status 200
Contain an empty response body
Arrive within three seconds

The endpoint must support HTTPS with TLS 1.2 or newer. TikTok Shop also documents retry behavior when delivery fails or times out. See the official webhook configuration guide.

That creates a strict boundary:

Webhook request = authenticate + persist + acknowledge
Worker job      = process + normalize + route + enrich

Do not acknowledge an event before it reaches durable storage. Otherwise, a process crash between acknowledgement and persistence can permanently lose the message.

Make Every Delivery Idempotent

Webhook delivery is at-least-once behavior in practice. Your system must expect the same event to arrive more than once.

Use tts_notification_id as the first idempotency key:

CREATE TABLE webhook_inbox (
  notification_id TEXT PRIMARY KEY,
  shop_id TEXT NOT NULL,
  payload JSONB NOT NULL,
  received_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  processed_at TIMESTAMPTZ
);

At the normalized message layer, also enforce uniqueness on message_id.

These keys protect different stages:

tts_notification_id prevents duplicate webhook processing.
message_id prevents duplicate customer messages.
conversation_id identifies the message stream.
shop_id determines tenant or workspace routing.

A duplicate webhook should still receive 200. Duplication is an expected delivery condition, not an application error.

Do Not Trust Arrival Order

Network delivery order is not guaranteed.

A newer message may arrive before an older one, and a retry may arrive after both. Use the message index and conversation_id to track ordering instead of assuming that request arrival time reflects conversation order.

A simplified worker check might look like this:

if (
  state.lastIndex !== null &&
  event.index > state.lastIndex + 1
) {
  await scheduleHistoryReconciliation(event.conversationId);
}

Preserve create_time, but do not use it as your only ordering mechanism.

Reconcile Missing Messages Through History

Webhooks should not be treated as the complete source of truth. TikTok Shop explicitly recommends using API queries when applications need to recover or validate state.

Use:

GET /customer_service/202309/conversations/{conversation_id}/messages

The Get Conversation Messages documentation specifies that:

The required scope is seller.customer_service.
page_size has a maximum value of 10.
Pagination uses next_page_token.
Fetching messages does not mark them as read.

Trigger reconciliation when:

A message index gap is detected.
A worker repeatedly fails to process an event.
A shop reconnects after authorization problems.
Monitoring detects an inactive conversation stream.
Support reports a missing message.

Insert recovered messages through the same idempotent normalization pipeline used for webhook events.

Keep Routing Separate from Authentication

A valid signature proves that the request came from TikTok Shop. It does not tell you which internal customer owns the shop.

Maintain an explicit mapping:

shop_id
  -> seller authorization
  -> internal tenant
  -> customer service workspace

If shop_id is unknown, store the event in an unroutable state instead of discarding it.

This makes delayed provisioning, authorization changes, and mapping mistakes recoverable.

Track Authorization as Its Own Lifecycle

Seller authorization can expire or be revoked independently of webhook delivery.

Treat these as different failure domains:

Webhook authentication
Seller access-token validity
API scope approval
Shop-to-tenant routing
Downstream message processing

For example, a webhook may be valid while the history API request fails because the seller token is no longer usable.

Do not classify every API failure as a webhook or network failure.

Monitor the Pipeline, Not Just the Endpoint

A webhook endpoint returning 200 does not prove that messages are reaching the customer service workspace.

Useful production metrics include:

Webhook acknowledgement latency at p95 and p99
Invalid signature count
Duplicate notification count
Durable inbox insertion failures
Queue age
Processing retry count
Conversation index gaps
History reconciliation count
Unroutable shop_id count
End-to-end message delivery latency

Logs should include safe correlation fields such as:

tts_notification_id
shop_id
conversation_id
message_id
Worker job ID
Internal tenant ID

Do not log access tokens, application secrets, or full authorization headers.

Common Failure Modes

Symptom	Likely cause	What to check
Webhook returns `401`	Signature mismatch	Raw body handling, app key, app secret, header parsing
Webhook returns `200`, but no ticket appears	Async processing failure	Inbox row, queue job, worker logs, tenant routing
Same message appears twice	Missing idempotency	Unique constraints for notification and message IDs
Conversation has missing messages	Delivery gap or processing failure	Message index and history reconciliation
Message reaches the wrong workspace	Incorrect shop mapping	`shop_id` ownership and authorization mapping
History API fails	Scope or token problem	Seller authorization and `seller.customer_service`
Fetching history does not update unread status	Expected behavior	Handle read state through the appropriate API separately

Production Acceptance Test

Before launch, perform a real end-to-end test:

Authorize a real test shop.
Send a buyer message through TikTok Shop.
Confirm that the webhook signature is accepted.
Confirm that the raw event reaches durable storage.
Confirm that the endpoint responds with an empty 200 within three seconds.
Confirm that the worker creates exactly one normalized message.
Replay the webhook and verify that no duplicate message is created.
Simulate an index gap and confirm that history reconciliation runs.
Confirm that the message is routed to the correct workspace.
Inspect the webhook delivery record in Partner Center.

A manually constructed HTTP request can test your endpoint mechanics, but it cannot prove that seller authorization, event subscription, TikTok delivery, and production routing all work together.

Final Checklist

Before going live, verify that:

Customer Service API access is approved.
The seller has authorized the application.
NEW_MESSAGE is subscribed.
The endpoint uses HTTPS and TLS 1.2 or newer.
Signatures are verified against the raw request body.
Events are durably stored before acknowledgement.
Empty 200 responses are returned within three seconds.
tts_notification_id and message_id are deduplicated.
Message ordering uses conversation identifiers and indexes.
History reconciliation handles missing events.
Shop routing and authorization lifecycles are observable.
A real Shop-to-workspace acceptance test has passed.

Production webhook engineering is less about receiving JSON and more about maintaining consistency across two systems that communicate asynchronously.

Once acknowledgement, idempotency, ordering, reconciliation, and authorization are treated as first-class components, the integration becomes much easier to operate.

Originally published on UnifyPort.

Disclosure: AI-assisted drafting and editing were used in preparing this article. The technical content was reviewed against the referenced documentation.

LINE Service Messages vs Messaging API: Choose the Right Message Path

unifyport — Fri, 07 Aug 2026 05:43:02 +0000

LINE MINI App Service Messages and the LINE Messaging API can both deliver messages to users, but they solve different problems.

A Service Message confirms or follows up on an action completed inside a LINE MINI App. A Messaging API message comes from a LINE Official Account and supports conversations, direct outreach, and audience messaging.

They differ in:

Sender identity
Trigger
Recipient model
Token lifecycle
Message format
Review requirements
Chat room
Pricing
Content policy

Choosing the wrong path can result in rejected templates, unusable tokens, duplicate notifications, or an architecture that cannot support customer conversations.

The short answer

Use a LINE MINI App Service Message when:

The user completed an action inside the MINI App
The message confirms, reports, or reminds the user about that action
The MINI App is verified
The template has passed review
You have a valid service notification token

Use the Messaging API when:

The sender should be a LINE Official Account
You need to reply to a user conversation
You need push, multicast, narrowcast, or broadcast delivery
You need flexible message objects
You are operating under the Official Account recipient, quota, and pricing model

One API is not an upgraded version of the other.

Compare the two paths

Decision point	Service Message API	Messaging API
Product	LINE MINI App	LINE Official Account
Purpose	Transactional action confirmation, result, or reminder	Conversation, support, outreach, and audience delivery
Trigger	User action inside the MINI App	User webhook event or application decision
Recipient	User associated with a service notification token	User, group, chat, audience, or Official Account friends
Production requirement	Verified MINI App and reviewed template	Messaging API channel connected to an Official Account
Message design	Reviewed LINE-provided template	Text, image, video, Flex, template, sticker, location, and other objects
Chat room	Regional MINI App notice chat	Chat with the Official Account
Marketing	Prohibited	Supported through eligible methods and applicable rules
Message limit	Normally up to five per qualifying action	Monthly allowance, endpoint limits, and account plan
Pricing	Described by LINE as free	Depends on market and Official Account plan

The official boundaries are documented in LINE's Service Message guide and Messaging API sending guide.

Service Messages begin with a MINI App action

A Service Message should not exist without a specific action performed by the user inside the LINE MINI App.

Appropriate examples include:

Reservation confirmation
Order confirmation
Check-in result
Shipment completion
Reservation reminder
Reminder for a purchased ticket
Queue-status update tied to a submitted request

The relationship should be explicit:

User action
    ↓
Business transaction
    ↓
Service notification token
    ↓
Approved template
    ↓
Confirmation, result, or reminder

The following are not valid Service Message use cases:

General promotions
Discount campaigns
Coupons
Shopping rewards
New-product announcements
Unrelated event notifications
Messages triggered by actions outside the MINI App

Verification does not remove these restrictions.

Messaging API messages begin with an Official Account

The Messaging API provides these primary delivery methods:

Method	Typical use
Reply	Respond to a webhook event from a user
Push	Send to an eligible user, group, or multi-person chat
Multicast	Send to a specified list of user IDs
Narrowcast	Send to an audience or demographic segment
Broadcast	Send to all friends of the Official Account

It also supports a broader set of message objects:

Text
Text v2
Image
Video
Audio
Sticker
Location
Imagemap
Template
Flex Message

This makes the Messaging API appropriate for customer support, chatbots, campaigns, and Official Account communication.

However, it follows the recipient, friendship, quota, rate-limit, and pricing rules of the Official Account.

Understand the token boundary

The most common implementation error is treating all LINE tokens as interchangeable.

They are not.

Credential or identifier	Belongs to	Purpose
LIFF access token	Current MINI App user session	Helps issue the first service notification token
MINI App channel access token	MINI App channel	Authenticates Service Message API calls
Service notification token	One MINI App user and action flow	Sends reviewed Service Messages
Messaging API channel access token	Official Account channel	Authenticates Messaging API requests
Reply token	One eligible webhook event	Sends a reply message once
LINE user ID	User within a channel context	Targets eligible Messaging API methods
Audience ID	Official Account audience	Targets narrowcast operations

A Service notification token is not:

A permanent user ID
A Messaging API reply token
An Official Account push target
A reusable cross-user credential
A general-purpose chat identity

Keep each token type in a separate model and storage path.

The Service Message token flow

The first Service Message normally starts with a LIFF access token obtained during the user action.

MINI App
    ↓ liff.getAccessToken()
Backend
    ↓ POST /message/v3/notifier/token
Service notification token
    ↓ POST /message/v3/notifier/send?target=service
Service Message
    ↓
Renewed service notification token

LINE recommends stateless channel access tokens for LINE MINI App channels. Long-lived and v2.1 channel access tokens cannot be used for MINI App channels.

The Service Message API returns state that must be preserved:

type ServiceNotificationState = {
  businessActionId: string;
  userReference: string;
  notificationToken: string;
  remainingCount: number;
  expiresAt: string;
  version: number;
};

Important characteristics include:

The token is associated with one user
It normally permits up to five messages for the approved action
It expires one year after issuance
The token value is renewed after a successful send
The renewed token must be used for the next message
One LIFF access token can issue only one Service notification token

Do not store the token in browser analytics or application logs.

Persist the renewed token atomically

Two workers must not send with the same Service notification token at the same time.

A safe operation looks like:

async function sendActionUpdate(input: {
  actionId: string;
  stage: "confirmation" | "result" | "reminder";
  templateName: string;
  params: Record<string, string>;
}) {
  return database.transaction(async (tx) => {
    const state = await tx.lockServiceNotificationState(
      input.actionId,
    );

    const idempotencyKey =
      `${input.actionId}:${input.stage}:${input.templateName}`;

    const existing = await tx.findDelivery(idempotencyKey);

    if (existing) {
      return existing;
    }

    if (state.remainingCount <= 0) {
      throw new Error("service_message_count_exhausted");
    }

    const response = await lineMiniApp.sendServiceMessage({
      notificationToken: state.notificationToken,
      templateName: input.templateName,
      params: input.params,
    });

    await tx.updateServiceNotificationState({
      actionId: input.actionId,
      notificationToken: response.notificationToken,
      remainingCount: response.remainingCount,
    });

    return tx.createDelivery({
      idempotencyKey,
      channel: "line_service_message",
      status: "sent",
    });
  });
}

The exact transaction implementation depends on your database and queue, but the invariants are the same:

Lock the action state
Check idempotency
Send once
Save the renewed token
Save the new remaining count
Commit together

If the request result is uncertain, reconcile it before retrying blindly.

Reply tokens have a different lifecycle

Messaging API reply tokens arrive in eligible webhook events.

They are:

Tied to one event
Usable only once
Intended to be used immediately
Not interchangeable with Service notification tokens

A reply flow looks like:

User sends message
       ↓
Official Account webhook
       ↓
Reply token
       ↓
POST /v2/bot/message/reply
       ↓
Reply in Official Account chat

If the response is generated too late or the reply token has already been consumed, your application must evaluate whether an eligible push message is appropriate.

Do not store a reply token as a permanent conversation address.

Treat templates differently

Service Messages use LINE-provided templates that must pass review.

Your application supplies approved variables and permanent links:

{
  "templateName": "reservation_confirmation_en",
  "params": {
    "reservation_number": "R-20260807-001",
    "reservation_time": "2026-08-08 19:00",
    "button_uri_1": "reservation/detail?id=R-20260807-001"
  }
}

The template must remain connected to the reviewed action.

Messaging API message objects are more flexible:

{
  "to": "USER_ID_PLACEHOLDER",
  "messages": [
    {
      "type": "text",
      "text": "How can we help with your reservation?"
    }
  ]
}

This flexibility does not mean every recipient is eligible for every send method. Recipient and friendship rules still apply.

Do not send the same message twice by default

A product that uses both APIs can accidentally send duplicate updates:

Reservation completed
       ├── Service Message
       └── Messaging API push

Unless duplication has a deliberate product reason, select one delivery path per purpose.

A routing policy can be explicit:

type MessagePurpose =
  | "transaction_confirmation"
  | "transaction_result"
  | "transaction_reminder"
  | "support_reply"
  | "support_follow_up"
  | "marketing_campaign";

function selectLineMessagePath(
  purpose: MessagePurpose,
): "service_message" | "messaging_api" {
  switch (purpose) {
    case "transaction_confirmation":
    case "transaction_result":
    case "transaction_reminder":
      return "service_message";

    case "support_reply":
    case "support_follow_up":
    case "marketing_campaign":
      return "messaging_api";
  }
}

The final implementation must still check verification, template, recipient, consent, and quota requirements.

Join both paths with your own business ID

A Service notification token is not a customer-support identity.

If a customer receives a reservation confirmation and later starts a support conversation, correlate both paths with your own transaction model:

type CustomerInteraction = {
  customerId: string;
  businessActionId: string;
  reservationId?: string;
  orderId?: string;
  lineMiniAppUserReference?: string;
  officialAccountUserId?: string;
  supportConversationId?: string;
};

Do not assume identifiers from different LINE channels or products are globally interchangeable.

Your application should own the relationship between:

Customer
Order or reservation
MINI App action
Service Message delivery
Official Account conversation
Support ticket

Recommended hybrid architecture

LINE MINI App action
        ↓
Transaction service
        ↓
Service Message worker
        ↓
Regional MINI App notice chat

Customer support message
        ↓
Official Account webhook
        ↓
Conversation service
        ↓
Messaging API reply

Both paths
        ↓
Shared customer/order database

Keep separate:

Credentials
Token storage
Queues
Delivery logs
Retry policies
Rate and quota monitoring
Compliance rules

Share only stable business context such as an internal order or reservation ID.

Common failure modes

Using the wrong token

Symptom:

Unauthorized, invalid token, or recipient error

Check whether the request used:

A LIFF access token
A MINI App channel access token
A Service notification token
A Messaging API channel access token
A reply token

Token type should be part of your request tracing metadata, but never log the token value.

Losing the renewed Service notification token

Symptom:

First notification succeeds
The next notification fails
Stored remainingCount does not match the latest response

Cause:

The application continued using the previous token value.

Reusing a token concurrently

Symptom:

Two workers process the same action
One succeeds and one fails
The next token state becomes unclear

Fix:

Use an action-level lock, idempotency key, and atomic token update.

Using Service Messages for marketing

Symptom:

Template review fails
Production use is restricted
Message content no longer matches the approved action

Fix:

Move promotional communication to an eligible Official Account method and follow its rules.

Treating a push message as a guaranteed alternative

Symptom:

The Service Message path fails
The application attempts a push message
The user is not an eligible Messaging API recipient

Fix:

Evaluate recipient eligibility before designing a fallback. The two paths do not have the same reach.

A practical decision tree

Ask these questions in order:

Did the user perform the triggering action inside the LINE MINI App?
Is the message only a confirmation, action result, or reminder for that action?
Is the MINI App verified?
Has the exact template passed review?
Is a valid Service notification token available?

If all answers are yes, use the Service Message API.

Otherwise ask:

Should the sender be the LINE Official Account?
Is this a reply to an eligible webhook event?
Is the recipient eligible for push or audience delivery?
Is the account within its message allowance?
Which Messaging API method matches the recipient model?

Then choose reply, push, multicast, narrowcast, or broadcast as appropriate.

Final checklist

[ ] Message purpose is defined
[ ] Triggering user action is identified
[ ] Sender identity is correct
[ ] Chat-room destination is understood
[ ] Token type is explicit
[ ] Service Message template is approved
[ ] Promotional content is excluded from Service Messages
[ ] Renewed notification tokens are stored atomically
[ ] remainingCount and expiry are persisted
[ ] Action-level idempotency is implemented
[ ] Reply tokens are not stored as permanent addresses
[ ] Messaging API recipient eligibility is checked
[ ] Monthly allowance and rate limits are monitored
[ ] Duplicate cross-path delivery is prevented
[ ] Both paths correlate through an internal business ID
[ ] Credentials, queues, and retry policies remain separate

The correct question is not:

Which LINE API can send the most messages?

It is:

Which product, sender identity, trigger, recipient model, and policy match this specific message?

Official references

Originally published on UnifyPort.

This article was prepared with AI assistance for language and structure, then technically reviewed and verified by the author.

One LINE Official Account, Multiple Tools: Webhook and Token Architecture

unifyport — Wed, 05 Aug 2026 06:02:41 +0000

A completed WhatsApp Embedded Signup dialog does not mean that a customer is ready to send and receive messages.

The browser flow may have finished while the backend still has one of these problems:

The result was attached to the wrong tenant
The access token belongs to another app
The wrong WhatsApp Business Account was selected
The system user lacks the required access
The phone number is not ready
The app is not subscribed to WABA webhooks
The first webhook cannot be routed to the customer

A SaaS application should display Connected only after every backend gate has passed.

Model onboarding as a state machine

Avoid representing onboarding with one Boolean field such as:

connected: true

Use explicit states instead:

type WhatsAppOnboardingStatus =
  | "started"
  | "browser_finished"
  | "token_validated"
  | "waba_resolved"
  | "access_verified"
  | "phone_ready"
  | "app_subscribed"
  | "webhook_pending"
  | "active"
  | "verification_required"
  | "failed";

A safe transition path is:

started
   ↓
browser_finished
   ↓
token_validated
   ↓
waba_resolved
   ↓
access_verified
   ↓
phone_ready
   ↓
app_subscribed
   ↓
webhook_pending
   ↓
active

Each transition should store evidence, not just a timestamp.

Define the acceptance gates

Meta's official Embedded Signup collection separates the browser flow from the Graph API work required afterward.

Gate	Evidence	Failure risk
Session correlation	Tenant ID, state, configuration ID	Assets attached to the wrong customer
Token validation	App ID, scopes, expiry metadata	Token exists but cannot manage the WABA
WABA resolution	Exact WABA ID and business mapping	First list result belongs to another customer
System-user access	System-user ID and required task	Later API operations fail
Phone readiness	Phone-number ID and onboarding path	WABA exists but messaging is unavailable
App subscription	App appears in `subscribed_apps`	Meta receives messages but sends no webhook
Delivery proof	One correctly routed webhook	Configuration passes without real delivery

A tenant should remain unavailable until all required gates pass.

1. Correlate the browser result with a server session

Create the onboarding session on your server before opening Embedded Signup.

Store:

type OnboardingSession = {
  id: string;
  tenantId: string;
  startedByUserId: string;
  state: string;
  configurationId: string;
  onboardingPath: "cloud_api" | "coexistence";
  expiresAt: string;
  consumedAt?: string;
};

The state value should be:

Random
Single-use
Bound to one tenant
Bound to the initiating user
Short-lived
Validated on the server

When the browser reports completion:

Look up the server session
Verify the state
Reject expired sessions
Reject already-consumed sessions
Verify that the current user can modify the tenant
Mark the result as consumed atomically

Do not trust a tenant ID submitted by the browser if it can be derived from the authenticated server session.

If the Coexistence flow emits FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING, treat it as evidence that the dialog finished—not evidence that the backend is active.

2. Keep credentials out of the browser

Credential exchange and Graph API verification belong on the server.

Do not place access tokens in:

Browser storage
Query strings
Client-side analytics
Error-reporting breadcrumbs
Support screenshots
Application logs
Database fields returned by public APIs

Store the credential in a secret manager or encrypted server-side store.

Persist only the audit metadata your application needs:

type TokenAuditMetadata = {
  tenantId: string;
  appId: string;
  tokenType: string;
  grantedScopes: string[];
  issuedAt?: string;
  expiresAt?: string;
  lastValidatedAt: string;
};

A non-empty token is not proof that it belongs to the expected Meta app or has the permissions required for the selected WABA.

3. Resolve the intended WABA deterministically

The official collection exposes this endpoint for retrieving client WABAs:

GET /{business-id}/client_whatsapp_business_accounts

A business can return multiple WABAs. Never select the first array element:

// Unsafe
const waba = response.data[0];

Match against information captured for the current onboarding session:

function resolveWaba(
  availableWabas: Array<{ id: string; name?: string }>,
  expectedWabaId: string,
) {
  const matches = availableWabas.filter(
    (candidate) => candidate.id === expectedWabaId,
  );

  if (matches.length !== 1) {
    throw new Error("expected_waba_not_resolved");
  }

  return matches[0];
}

Store the relationship explicitly:

type TenantWabaMapping = {
  tenantId: string;
  metaBusinessId: string;
  wabaId: string;
  sourceSessionId: string;
  verifiedAt: string;
};

If no exact match exists, move the tenant to verification_required. Do not silently attach another WABA.

4. Verify system-user access

Meta documents the following endpoint for checking assigned users:

GET /{waba-id}/assigned_users?business={business-id}

Verify:

The expected system user is present
It belongs to the expected business
It has the task required by your integration
Your backend credential can perform the required WABA operations

Do not treat any returned system user as sufficient.

A system user added for a different operational role may not have the access your message or template workflow requires.

5. Branch by onboarding path

Standard Cloud API onboarding and WhatsApp Business App Coexistence are not the same phone-number path.

Standard Cloud API

Depending on the current onboarding contract, the backend may need to register the phone number and verify that its status permits messaging.

Coexistence

Coexistence uses a number already connected to the WhatsApp Business app.

Do not automatically repeat the standard registration operation. Instead, validate:

The number returned by the Coexistence flow
Its current status
Its WABA association
The intended synchronization behavior
The supported message-history boundary
Which surface owns each business operation

Keep the path in your tenant configuration:

type WhatsAppConnection = {
  tenantId: string;
  wabaId: string;
  phoneNumberId: string;
  mode: "cloud_api" | "coexistence";
  status: "verification_required" | "active" | "failed";
};

This prevents later jobs from applying Cloud API assumptions to a Coexistence number.

6. Subscribe the app to the WABA

A valid WABA and phone number do not prove that webhook delivery is configured.

Meta's official collection uses:

POST /{waba-id}/subscribed_apps

Verify the result afterward:

GET /{waba-id}/subscribed_apps

The expected Meta app must appear in the returned subscription list.

Treat subscription as a separate gate:

async function verifyAppSubscription(
  subscriptions: Array<{
    whatsapp_business_api_data?: { id?: string };
  }>,
  expectedAppId: string,
) {
  const subscribed = subscriptions.some(
    (item) =>
      item.whatsapp_business_api_data?.id === expectedAppId,
  );

  if (!subscribed) {
    throw new Error("waba_app_subscription_missing");
  }
}

Registration can succeed while subscription fails. Subscription can also exist while the selected phone number is not operational.

Do not combine these conditions into one status.

7. Prove one real webhook delivery

Configuration reads are necessary but not sufficient.

Before marking the tenant active, require one controlled webhook to reach a production-equivalent receiver.

The acceptance path should be:

Controlled WhatsApp message
          ↓
Meta webhook delivery
          ↓
Signature verification
          ↓
WABA and phone-number lookup
          ↓
Tenant resolution
          ↓
Idempotency check
          ↓
Durable event storage
          ↓
Successful acknowledgement

For a Meta webhook, verify the signature against the raw request body before parsing or routing it.

An illustrative Node.js helper:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyMetaSignature(
  rawBody: Buffer,
  signatureHeader: string,
  appSecret: string,
): boolean {
  const prefix = "sha256=";

  if (!signatureHeader.startsWith(prefix)) {
    return false;
  }

  const expected = createHmac("sha256", appSecret)
    .update(rawBody)
    .digest();

  const actual = Buffer.from(
    signatureHeader.slice(prefix.length),
    "hex",
  );

  return (
    actual.length === expected.length &&
    timingSafeEqual(actual, expected)
  );
}

Never log the app secret, token, or complete sensitive webhook payload while debugging verification.

8. Route by provider assets, not browser state

The webhook receiver must resolve the tenant from trusted provider identifiers.

Relevant identifiers can include:

WABA ID
Phone-number ID
Meta app ID
Internal connection ID

Do not route a production webhook using a tenant ID previously stored in browser state without verifying its asset mapping.

A routing table can look like:

CREATE TABLE whatsapp_connections (
  id VARCHAR(64) PRIMARY KEY,
  tenant_id VARCHAR(64) NOT NULL,
  meta_app_id VARCHAR(64) NOT NULL,
  waba_id VARCHAR(64) NOT NULL,
  phone_number_id VARCHAR(64) NOT NULL,
  onboarding_mode VARCHAR(32) NOT NULL,
  status VARCHAR(32) NOT NULL,
  UNIQUE (meta_app_id, waba_id, phone_number_id)
);

If the mapping is missing or ambiguous:

Do not guess
Do not assign the event to the most recently onboarded tenant
Store it in a restricted reconciliation queue
Alert the integration owner
Keep the tenant out of active

9. Make webhook processing idempotent

Webhook delivery can be retried.

Choose an idempotency key from stable provider fields appropriate to the event type. For inbound messages, the provider message ID is usually part of that identity.

Store the event before running slow business logic:

Verify signature
      ↓
Resolve tenant
      ↓
Insert event if absent
      ↓
Return success
      ↓
Process asynchronously

A duplicate should not create:

Two conversations
Two automated replies
Two billing records
Two workflow executions
Two customer notifications

Operational readiness means that both the first delivery and a repeated delivery are safe.

10. Treat credit-line attachment as conditional

The official Embedded Signup collection includes credit-line sharing for provider-paid arrangements.

That does not make credit-line attachment a universal readiness gate.

Apply it only when:

Your business owns the billing relationship with Meta
Your partner model requires credit sharing
The customer WABA is expected to use that credit line

For customer-paid or other supported billing arrangements, document the appropriate billing check separately.

Do not block every tenant on a credit-line operation that does not belong to its commercial model.

11. Separate platform approval from operational readiness

This checklist does not prove:

Meta business eligibility
App Review approval
Advanced Access approval
Display-name approval
Number quality
Template approval
Messaging-limit tier
Policy compliance

Those are separate platform states.

Maintain them independently:

type WhatsAppReadiness = {
  embeddedSignup: "pending" | "completed";
  appReview: "unknown" | "approved" | "rejected";
  wabaAccess: "unknown" | "verified" | "failed";
  phoneStatus: "unknown" | "ready" | "failed";
  webhookSubscription: "unknown" | "verified" | "failed";
  deliveryTest: "pending" | "passed" | "failed";
};

A successful test tenant also does not prove that every customer configuration will work. Keep the verification process repeatable for every onboarding session.

Recommended failure states

Return actionable states instead of a generic connection error.

State	Meaning	Next action
`session_mismatch`	Browser result cannot be correlated	Restart onboarding
`token_invalid`	Credential validation failed	Repeat credential exchange
`waba_not_resolved`	Expected WABA was not found	Review business selection
`system_user_missing`	Required access is absent	Assign or repair system user
`phone_not_ready`	Phone path is incomplete	Follow path-specific recovery
`subscription_missing`	App is not subscribed	Subscribe and verify again
`webhook_not_received`	No delivery proof exists	Inspect webhook and routing
`routing_ambiguous`	Asset mapping matches multiple tenants	Stop and reconcile mappings

These states make support, retry behavior, and audit logs much easier to reason about.

Final post-onboarding checklist

[ ] Server-side onboarding session exists
[ ] State is valid, single-use, and tenant-bound
[ ] Browser result has been consumed exactly once
[ ] Credentials remain server-side
[ ] Token app, permissions, and expiry were validated
[ ] Exact WABA was resolved
[ ] WABA was not selected by array position
[ ] System-user access was verified
[ ] Standard and Coexistence paths are separated
[ ] Phone-number ID is stored
[ ] Phone status is ready for the selected path
[ ] Expected app appears in subscribed_apps
[ ] Billing checks match the commercial model
[ ] One real webhook reached the receiver
[ ] Webhook signature was verified
[ ] WABA and phone number resolved to one tenant
[ ] Duplicate delivery is safe
[ ] Failure states are recoverable
[ ] Only then is the tenant marked active

The browser dialog finishing is a user-interface milestone.

Operational readiness requires a verified chain from the server-side onboarding session to the correct WABA, system user, phone number, app subscription, tenant mapping, and real webhook delivery.

Official references

Originally published on UnifyPort.

This article was prepared with AI assistance for language and structure, then technically reviewed and verified by the author.

One LINE Official Account, Multiple Tools: Webhook and Token Architecture

unifyport — Tue, 04 Aug 2026 03:10:04 +0000

A single LINE Official Account can use multiple Messaging API tools.

For example, one account might connect:

A customer-support platform
A campaign sender
A rich-menu manager
An analytics service
An internal automation system

But these tools do not receive isolated LINE channels. They share one Messaging API channel, one webhook URL, channel access-token limits, API rate limits, and feature-specific quotas.

That makes adding another tool an architecture change—not just another OAuth or API-key setup step.

This guide explains how to share the channel without accidentally disabling an existing tool or losing inbound messages.

Understand the shared boundary

LINE's official multiple-tools guidance confirms that multiple tools can call the Messaging API through one LINE Official Account.

However, only one Messaging API channel can be linked to the account.

Shared resource	LINE constraint	Operational risk
Messaging API channel	One channel per Official Account	All tools share configuration
Webhook URL	One URL per channel	A new tool can replace the existing receiver
Channel access tokens	Issuance limits vary by token type	Rotation can disable another tool
API rate limits	Applied per endpoint and channel	One tool can throttle another
Messaging quota	Shared by the account and plan	Campaign traffic can affect support traffic
Rich menus and audiences	Channel-level limits	Tools can overwrite or exhaust shared resources

Before connecting another tool, identify exactly which shared resources it needs.

Create an integration inventory

Maintain a manifest for every system using the channel.

tools:
  - name: support-platform
    owner: customer-support-team
    features:
      - receive-webhooks
      - reply-messages
      - push-messages
    token_type: v2.1
    owns_webhook: true

  - name: campaign-service
    owner: marketing-operations
    features:
      - broadcast-messages
      - audience-management
    token_type: v2.1
    owns_webhook: false

  - name: rich-menu-manager
    owner: product-team
    features:
      - rich-menu-management
    token_type: stateless
    owns_webhook: false

For each tool, record:

Business owner
Technical owner
Messaging API endpoints
Required webhook events
Token type
Token issuer
Expiration and renewal procedure
Rich-menu or audience ownership
Expected request volume
Emergency-disable procedure
Rollback procedure

Do not connect a tool until these responsibilities are assigned.

Choose channel access tokens carefully

LINE currently supports four channel access-token types.

Token type	Validity	Issuance limit per channel	Limit behavior
Long-lived	No fixed expiration	1	Reissuing invalidates the active token
Short-lived	30 days	30	Issuing beyond the limit revokes the oldest
v2.1	Up to 30 days	30	Additional issuance is rejected
Stateless	15 minutes	No stated count limit	Cannot be revoked after issuance

The exact behavior is documented in LINE's channel access-token guide.

The dangerous case is a shared long-lived token.

If Tool A and Tool B both use the same long-lived token, reissuing it for Tool B immediately affects Tool A.

A safer policy is:

Issue credentials per team or tool
Prefer expiring tokens when the vendor supports them
Store tokens in a secret manager
Record the token type and owner
Automate renewal before expiration
Test the new token before retiring the old one
Revoke credentials when a tool is removed
Never copy one team's production token into an unrelated system

Do not log token values, even during migration troubleshooting.

Keep one webhook owner

A Messaging API channel supports one webhook URL.

LINE cannot directly deliver the same event to two independent URLs. If a new vendor changes the webhook URL, the current receiver stops receiving events.

Use this decision table:

New tool requirement	Recommended approach
Sends messages only	Give it an appropriate token; do not change the webhook
Manages rich menus only	Leave the webhook owner unchanged
Replaces the current inbox	Perform a controlled webhook migration
Needs a subset of inbound events	Forward verified events from the existing receiver
Multiple tools need every event	Use one receiver and fan out internally
Vendor requires direct ownership	Choose one inbound owner or use another Official Account

The stable architecture is:

LINE Platform
      ↓
Single webhook endpoint
      ↓
Signature verification
      ↓
Durable event inbox
      ↓
Internal event router
   ↙       ↓       ↘
Support  Analytics  Automation

Verify the signature before parsing

LINE signs webhook requests using the channel secret.

Verification must use the raw request body. Do not parse and reserialize the JSON before calculating the signature.

An illustrative Node.js receiver:

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const channelSecret = process.env.LINE_CHANNEL_SECRET;

if (!channelSecret) {
  throw new Error("LINE_CHANNEL_SECRET is required");
}

function verifyLineSignature(
  rawBody: Buffer,
  signature: string,
  secret: string,
): boolean {
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .digest();

  const actual = Buffer.from(signature, "base64");

  return (
    actual.length === expected.length &&
    timingSafeEqual(actual, expected)
  );
}

app.post(
  "/line/webhook",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body as Buffer;
    const signature = req.header("x-line-signature") ?? "";

    if (!verifyLineSignature(rawBody, signature, channelSecret)) {
      res.sendStatus(401);
      return;
    }

    const payload = JSON.parse(rawBody.toString("utf8"));

    for (const event of payload.events ?? []) {
      await eventInbox.insertIfAbsent({
        eventId: event.webhookEventId,
        occurredAt: event.timestamp,
        payload: event,
      });
    }

    res.sendStatus(200);
  },
);

Important boundaries:

Verify before processing
Use a timing-safe comparison
Preserve the raw body
Do not log secrets or reply tokens
Store the event before asynchronous fan-out
Return a successful response promptly

LINE recommends asynchronous webhook processing.

Deduplicate before fan-out

Webhook redelivery can cause the same event to arrive more than once.

Use webhookEventId as the idempotency key:

CREATE TABLE line_webhook_inbox (
  webhook_event_id VARCHAR(64) PRIMARY KEY,
  occurred_at BIGINT NOT NULL,
  payload JSON NOT NULL,
  processing_status VARCHAR(20) NOT NULL,
  created_at TIMESTAMP NOT NULL
);

The receiver should:

Verify the signature
Insert the event with a unique webhookEventId
Treat a duplicate-key result as an accepted duplicate
Return 2xx
Let a worker process newly inserted events

Do not let each downstream tool independently deduplicate the original webhook. Deduplication belongs at the shared receiving boundary.

Webhook redelivery can also change arrival order. Use the event timestamp to understand event sequence when order matters.

Give reply-token ownership to one component

Reply tokens create an additional concurrency problem.

LINE reply tokens:

Can only be used once
Should be used as soon as possible
Must normally be used within one minute of receiving the webhook
Cannot be safely consumed by multiple independent tools

If the same event is forwarded to a support system and an automation system, both systems must not attempt to use the reply token.

Assign one reply coordinator.

Downstream services can return a reply intent:

type ReplyIntent = {
  webhookEventId: string;
  source: "support" | "automation";
  priority: number;
  messages: Array<{
    type: "text";
    text: string;
  }>;
};

The coordinator decides:

Whether the event should receive a reply
Which tool has priority
Whether a human response suppresses automation
Whether multiple messages should be combined
Whether the reply token has already been consumed
Whether a later response must use a push message instead

This prevents duplicate or conflicting replies.

Separate inbound and outbound ownership

A tool that receives webhooks does not automatically need to own every outbound message.

Define ownership by operation:

Operation	Suggested owner
Webhook signature verification	Ingress service
Durable event storage	Ingress service
Reply-token consumption	Reply coordinator
Human support replies	Support system
Scheduled campaigns	Campaign platform
Rich menus	Product or marketing owner
Audiences	Marketing operations
Channel token issuance	Platform or security team
Shared quota monitoring	Platform operations

One tool should not silently change resources owned by another.

For example, a support-platform installation should not replace production rich menus unless rich-menu management is explicitly part of its approved scope.

Budget shared rate limits

Messaging API rate limits are applied per API function and per channel, regardless of which tool or IP address sends the request.

This means:

Tool A traffic
+ Tool B traffic
+ Tool C traffic
= Channel traffic

Monitor aggregate usage rather than isolated vendor dashboards.

Track:

Requests per endpoint
429 Too Many Requests
Monthly message usage
Broadcast volume
Push-message volume
Rich-menu count
Audience count
Statistics-unit usage
Per-tool error rate

Do not blindly retry every 429. A coordinated retry policy should include:

Endpoint-aware backoff
Jitter
Maximum attempts
Message-expiration rules
Shared concurrency limits
Alerting when one tool consumes unusual capacity

Reserve capacity for critical support replies before launching a large campaign.

Test unknown webhook events

Adding or enabling a tool can change which features are used through the shared channel.

Your current receiver must safely handle events it does not consume.

function routeEvent(event: LineWebhookEvent) {
  switch (event.type) {
    case "message":
      return messageQueue.publish(event);

    case "follow":
    case "unfollow":
      return accountQueue.publish(event);

    case "postback":
      return automationQueue.publish(event);

    default:
      return unknownEventQueue.publish({
        eventId: event.webhookEventId,
        eventType: event.type,
        payload: event,
      });
  }
}

An unknown event should be observable, but it should not crash the entire webhook request.

Migration checklist for a new tool

Before installation:

Export the current webhook URL
Identify the current token types
List all token consumers
Record current rich menus and audiences
Measure normal API traffic
Confirm whether the new tool needs inbound events
Confirm which settings its installer changes
Prepare the rollback configuration

During installation:

Use a tool-specific credential
Prevent unapproved webhook replacement
Test in a controlled environment
Send one inbound message
Confirm exactly one durable event
Confirm the correct downstream consumers receive it
Verify only one component uses the reply token
Test one supported outbound action
Monitor rate-limit and authentication errors

After installation:

Recheck the webhook URL
Recheck existing tools
Confirm campaigns and support replies still work
Confirm rich menus were not replaced
Review message usage
Rotate temporary credentials
Record the final configuration

Prepare a rollback procedure

A rollback should specify:

rollback:
  previous_webhook_url: STORED_IN_SECURE_CONFIGURATION
  affected_tools:
    - support-platform
    - campaign-service
  token_action: revoke-new-tool-token
  verification:
    - send-controlled-user-message
    - confirm-single-webhook-record
    - confirm-support-reply
    - confirm-existing-rich-menu

Do not make the first production failure the first time the rollback is tested.

Final architecture checklist

[ ] Every connected tool has an owner
[ ] Messaging API features are inventoried per tool
[ ] Token type and renewal owner are documented
[ ] Tools do not share one long-lived token
[ ] The single webhook owner is explicit
[ ] Webhook signatures are verified against the raw body
[ ] Events are stored before asynchronous fan-out
[ ] webhookEventId is used for deduplication
[ ] Reply tokens have one coordinator
[ ] Unknown webhook events remain observable
[ ] Rich-menu and audience ownership is documented
[ ] Rate limits are monitored at channel level
[ ] Monthly message capacity is shared deliberately
[ ] A controlled end-to-end test has passed
[ ] The previous webhook configuration can be restored
[ ] Removing a tool revokes its credentials

Multiple tools can safely share one LINE Official Account, but only when the shared channel is treated as production infrastructure.

The most important rule is simple: receive once, verify once, store once, and coordinate everything that happens afterward.

Official references

Originally published on UnifyPort.

This article was prepared with AI assistance for language and structure, then technically reviewed and verified by the author.

DEV Community: unifyport

Telegram Bot Receives DMs but Not Group Messages? Debug Privacy Mode First

Start with the observed behavior

What Privacy Mode controls

Visibility and delivery are different layers

Visibility failure

Delivery failure

Application-filtering failure

Step 1: confirm the bot identity

Check can_read_all_group_messages

Step 2: run a controlled group test

Step 3: inspect the raw receiver

Step 4: audit application filters

Step 5: check allowed_updates

Step 6: verify the receiving mode

Step 7: choose the minimum required access

Do not promote the bot to administrator just for testing

Disabling Privacy Mode safely

Build an acceptance-test matrix

Preserve updates idempotently

A compact diagnostic function

Bot identity versus account-based intake

Production checklist

Takeaway

References

Telegram getUpdates vs setWebhook: A Safe Migration Runbook

The two receiving modes

Long polling with getUpdates

Push delivery with setWebhook

Why the conflict happens

First step: inspect the active mode

Diagnose common symptoms

Migration rule: one receiver owns the bot

Switching from webhook to getUpdates

Step 1: pause downstream changes

Step 2: inspect the webhook

Step 3: choose the pending-update policy

Step 4: verify webhook removal

Step 5: start exactly one polling worker

Step 6: advance the offset

Switching from getUpdates to setWebhook

Step 1: stop the polling worker

Step 2: finish or checkpoint current work

Step 3: deploy the webhook endpoint

Step 4: configure the webhook

Step 5: verify the configured URL

Step 6: send a controlled test message

Handle pending updates deliberately

Make both modes idempotent

Avoid duplicate side effects

A migration checklist

Before switching

Webhook to polling

Polling to webhook

When the Bot API is the right model

When a unified inbound webhook fits better

Takeaway

References

TikTok Business Messaging API vs QR-Authenticated Inbox: How to Choose

The short version

Start with the identity

What the official Business Messaging API is for

What a QR-authenticated inbox is for

Model QR authentication as a state machine

The architecture difference

TikTok-specific business integration

Normalized multi-channel intake

Store inbound events before routing them

Verify the signed raw body

Make event storage idempotent

Normalize intake without hiding provider differences

Compare the operational responsibilities

Choose the official Business Messaging API when

Choose a QR-authenticated inbox when

Do not confuse related TikTok APIs

Decision checklist

Takeaway

References

Build a Reliable WhatsApp Group Join-Request Approval Queue with Node.js

What WhatsApp still controls

Check `can_read_all_group_messages`

Step 5: check `allowed_updates`

Long polling with `getUpdates`

Push delivery with `setWebhook`

Switching from webhook to `getUpdates`

Switching from `getUpdates` to `setWebhook`