DEV Community: unifyport

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.

LINE MINI App Verification Review: A Pre-Submission Checklist That Prevents Rework

unifyport — Mon, 03 Aug 2026 07:17:46 +0000

A LINE MINI App does not automatically need verification before it can be published.

The first question is whether your product actually depends on a verified-only capability. If it does, the review is more than a technical launch check: LINE evaluates identity consistency, policy compliance, channel configuration, and whether a reviewer can complete the service's real user flows.

A preventable documentation mismatch can add another review cycle, so the best time to audit the submission is before opening the Review request tab.

Decide whether verification is necessary

According to LINE's custom-features matrix, these capabilities require a verified MINI App:

Feature	Verification required
Production service messages	Yes
Custom Path	Yes
Home-screen shortcut	Yes
Common Profile Quick-fill	Yes
MINI App name and verified badge in the header	Yes
Official Account add-friend prompt	No
Custom action button	No
Payment-system integration	No, but availability and separate reviews vary by region

If none of the verified-only features are on your critical path, publishing the core experience as an unverified MINI App may be a reasonable first release.

If verification is required, budget for the review before committing to a launch date.

1. Align the organization identity

The official submission guide requires the provider name to match the service provider. The company named in the privacy policy must also match the provider.

Audit these fields together:

Location	Value to verify
LINE Developers Console provider	Registered provider name
Channel information	Service provider name
Privacy policy	Company acquiring or processing user data
Channel description	Company and service relationship
Localized information	The same identity in every supported language

A simple internal review record might look like this:

{
  "providerName": "Example Company Ltd.",
  "serviceProviderName": "Example Company Ltd.",
  "privacyPolicyCompany": "Example Company Ltd.",
  "status": "matched"
}

Do not assume that a brand name, parent company, subsidiary, or trading name is automatically equivalent to the registered provider.

If development and service operation are handled by different companies, describe that relationship clearly in the channel description and privacy policy.

2. Make the channel description testable

A vague description tells the reviewer what the business is, but not what the MINI App actually does.

Weak description:

This is an online store.

Stronger description:

This LINE MINI App lets customers select a store, order products, complete payment, and present the resulting pickup code at the selected location.

The stronger version identifies:

The primary user
The core workflow
Payment or reservation behavior
The result generated by the MINI App
What the reviewer should be able to test

Compare the description with the current UI. Names, buttons, navigation, and available features should match what you submit.

3. Verify the Review channel

During verification, LINE evaluates the LIFF URL of the Review channel.

Before requesting review, confirm that the Review and Published channels expose the same service:

Same core features
Same screen transitions
Same product or reservation data
Same authentication requirements
Same payment behavior
Same privacy and terms links
Same error and completion states

Do not leave the Review channel pointed at an old staging deployment.

Create an environment record:

Published endpoint: https://app.example.com/
Review endpoint:    https://review.example.com/
Release version:    2026.08.03
Test data version:  review-fixtures-v3

Avoid including secrets in normal logs, screenshots, source control, or public documentation.

4. Prepare complete test scenarios

For services containing reservations, payments, or orders, LINE asks applicants to provide test scenarios in the review reference materials.

A useful scenario should contain:

scenario: Complete a store pickup order
account:
  username: PROVIDED_IN_REVIEW_FORM
  password: TEMPORARY_REVIEW_CREDENTIAL
preconditions:
  - Test store is available
  - Sample product is in stock
steps:
  - Open the MINI App
  - Select the test store
  - Add the sample product
  - Complete the test payment flow
  - Open the order result
expected_result:
  - Order confirmation is displayed
  - Pickup code is generated
  - Order appears in order history
cleanup:
  - Cancel or reset the test order

Prepare separate scenarios for:

Registration and login
Reservation creation
Reservation cancellation
Successful payment
Failed or cancelled payment
Order completion
Empty or unavailable inventory
Permission denial
Service-message delivery, if applicable
Account deletion or data-management flows

The reviewer should not need to guess which product, store, date, or account can complete the flow.

If Basic Authentication protects the Review channel, provide the temporary credentials in the designated review materials. Rotate or remove them after the review.

5. Check privacy and terms pages

Review every public legal page from a logged-out browser.

Confirm that:

The URL is publicly reachable
The company name matches the submitted provider
The service name matches the MINI App
Data collection and processing are described
Contact information works
The page is readable on mobile
Redirects do not require an internal session
Every configured localization points to an appropriate document

The privacy-policy company is especially important because LINE explicitly compares it with the provider name.

A Terms of use URL may be optional depending on the channel configuration, but if you configure one, treat it as review-controlled information. Changes to either the privacy-policy or terms URL after verification can require re-review.

6. Run a policy gate before the technical review

A technically correct MINI App can still be rejected if the underlying business or content conflicts with the LINE MINI App Policy.

Examples of restricted business categories include:

Gambling
Dating and matchmaking
Lending
Fundraising and crowdfunding
Multi-level marketing
Tobacco and e-cigarettes
Weapons and poisons
Clinical trials
Certain religious, political, adult-entertainment, and investment-related services

Also review the actual content for:

Intellectual-property infringement
Misleading claims
Spam
Aggressive user inducement
Unsafe or age-inappropriate material
Unreliable product comparisons or rankings
Features that move the main service entirely outside the MINI App

Treat policy eligibility as a product requirement, not a final copy-editing task.

7. Review API scopes

Request only the scopes required by the submitted workflow.

For each scope, document:

Scope	Feature using it	Screen	Required?
Profile access	Populate customer name	Checkout	Yes
OpenID	Identify returning customer	Login	Yes
Additional scope	Related feature	Screen name	Yes/No

Remove experimental scopes that are not part of the submitted service.

After verification, changing scopes is one of the configuration changes that can require another review.

8. Treat service messages as a separate approval gate

Verification makes the channel eligible for production service messages, but it does not automatically approve every message template.

Production service messages require both:

A verified MINI App
An approved service-message template

Service messages must confirm or respond to an action performed by the user in the MINI App.

Appropriate examples include:

Reservation confirmation
Payment result
Order status
Appointment reminder
Completion of a submitted request

Promotional content is not allowed, including:

Discounts
Shopping rewards
New-product announcements
Coupons
General promotions
Unrelated event announcements

Audit template variables, permanent links, languages, and the triggering user action before submitting the template review.

9. Freeze re-review-sensitive settings

After verification, changes to many LINE Developers Console settings require re-review.

These include:

Channel icon
Channel name
Channel description
Privacy policy URL
Terms of use URL
Localization
Linked LINE Official Account
Published Endpoint URL
Scopes
Add-friend option
Service company information
Provider information
Service-message template information

The complete list is documented in LINE's re-review guide.

Before the first submission, freeze:

Channel identity
Legal URLs
Production endpoint
Required scopes
Official Account linkage
Localization
Service-message templates
Review test data

This does not mean the product can never change. It means review-controlled changes should be planned as release work with their own approval lead time.

10. Plan for the real review timeline

LINE states that verification normally takes approximately one to two weeks.

Applicants cannot specify the completion date. If the application is rejected, correcting the issue and requesting another review adds more time.

A safer release plan is:

Internal submission audit
        ↓
First review request
        ↓
1–2 week review window
        ↓
Re-review buffer
        ↓
Production launch

Once the review process begins, the submitted information cannot be edited. A review request can only be cancelled before LINE starts reviewing it.

If a campaign or seasonal launch depends on a verified-only capability, do not schedule the public launch immediately after the earliest possible approval date.

11. Keep verification separate from inbound messaging

LINE MINI App verification answers this question:

Can this MINI App use verified-only platform capabilities?

It does not answer:

How will ordinary LINE customer conversations reach our support system?

Receiving customer messages, normalizing webhook events, routing conversations, and sending supported replies are separate architecture decisions.

Do not assume that MINI App verification automatically provides a general customer-message inbox. Likewise, connecting an inbound messaging API does not grant a Custom Path, verified badge, or production service-message capability.

If the product uses both systems, connect them deliberately through stable customer, reservation, or order identifiers.

Final pre-submission checklist

[ ] Verification is required by a specific product feature
[ ] Provider and service-provider names match
[ ] Privacy-policy company matches the provider
[ ] Localized identity information is consistent
[ ] Channel description explains the real workflow
[ ] Review and Published channels expose the same service
[ ] Production endpoint has been frozen
[ ] Privacy and terms pages are publicly accessible
[ ] Every reservation, payment, and order flow has a test scenario
[ ] Temporary review credentials work
[ ] Test data can complete every submitted scenario
[ ] Business category and content pass the policy audit
[ ] API scopes match implemented features
[ ] Service-message templates are reviewed separately
[ ] Re-review-sensitive settings have owners
[ ] Launch planning includes a re-review buffer
[ ] Review credentials can be rotated after approval

A successful verification submission is not just an application that launches. It is a review package in which the legal identity, configuration, product description, policies, and test environment all describe the same service.

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.

Telegram Bot API 10.2 Migration Guide: Rich Messages, Ephemeral Edits, and Communities

unifyport — Thu, 30 Jul 2026 09:04:09 +0000

Telegram Bot API 10.2 looks like a small version bump, but it changes several parts of a production bot at once:

Rich Messages gain typed blocks and embedded media
Ephemeral messages gain a complete edit and delete lifecycle
Communities introduce new topology events and metadata
Mini Apps receive stricter origin protection

Telegram released Bot API 10.2 on July 14, 2026. The safest upgrade is not to enable every new feature immediately. First update your data model and event dispatcher, then test each outbound capability behind a feature flag.

This guide turns the official Bot API 10.2 changelog into an implementation checklist.

Start with an impact map

Before changing code, separate the upgrade into four areas.

Area	Main change	Primary risk
Rich Messages	`media`, `blocks`, and new `InputRichBlock*` types	Invalid payloads or incomplete SDK serialization
Ephemeral messages	Send, reply, edit, and delete lifecycle	Losing the user-specific message identifiers
Communities	New lifecycle fields and `ChatFullInfo.community`	Dropping topology events in a default handler
Mini Apps	Cross-origin method protection	Previously working cross-origin calls being rejected

You do not have to enable every feature during the same deployment.

A reasonable rollout order is:

Upgrade the library and types
Accept and store the new fields
Add dispatcher coverage
Run regression tests
Enable outbound features separately

1. Pin a compatible Bot API library

Check whether your Telegram library has released a version compatible with Bot API 10.2.

Before updating production, inspect:

Generated API types
Serialization of optional fields
Method names and parameter casing
Webhook update types
Retry and error behavior
Support for unknown message fields

Do not assume that upgrading the package automatically enables the new behavior. Some libraries may expose new types before fully supporting every method.

Pin the selected version instead of using an open-ended dependency range:

{
  "dependencies": {
    "your-telegram-library": "PINNED_COMPATIBLE_VERSION"
  }
}

Run the upgrade in a branch and keep the previous dependency version available for rollback.

2. Audit Rich Message construction

Bot API 10.2 adds:

InputRichMessageMedia
InputMediaVoiceNote
media on InputRichMessage
blocks on InputRichMessage
A full set of InputRichBlock* builders

According to the Bot API reference, an InputRichMessage must use exactly one of these content representations:

html
markdown
blocks

If you generate payloads dynamically, validate that rule before making the API call.

function validateRichMessage(input: {
  html?: string;
  markdown?: string;
  blocks?: unknown[];
  media?: unknown[];
}) {
  const representations = [
    input.html,
    input.markdown,
    input.blocks,
  ].filter((value) => value !== undefined);

  if (representations.length !== 1) {
    throw new Error(
      "A rich message must contain exactly one of html, markdown, or blocks",
    );
  }
}

The new media field is used with media references embedded in HTML or Markdown, such as:

tg://photo?id=product_photo

Review the following before enabling media:

Media identifiers are unique inside the payload
Referenced media actually exists in the media array
The bot has permission to send that media type
A plain-text fallback is available
Your SDK preserves every new field during serialization

Do not silently convert an existing Markdown builder into a block builder during the dependency upgrade. Treat that as a separate feature change.

3. Preserve the ephemeral message identity

Bot API 10.2 completes the ephemeral-message lifecycle with:

editEphemeralMessageText
editEphemeralMessageMedia
editEphemeralMessageCaption
editEphemeralMessageReplyMarkup
deleteEphemeralMessage

It also adds receiver_user and ephemeral_message_id to Message.

A normal message ID is not enough to manage an ephemeral message. Store the complete routing identity:

type EphemeralMessageReference = {
  chatId: string;
  receiverUserId: number;
  ephemeralMessageId: number;
};

A library call may look similar to this, although the exact method naming depends on your SDK:

await bot.editEphemeralMessageText({
  chat_id: chatId,
  receiver_user_id: receiverUserId,
  ephemeral_message_id: ephemeralMessageId,
  text: "Your request has been updated.",
});

Also review reply construction. In Bot API 10.2, ReplyParameters.message_id becomes optional when ephemeral_message_id is present.

Your implementation should test:

Sending to the intended user
Editing text
Editing media or captions
Updating reply markup
Deleting the message
Rejecting edits from the wrong user context
Handling an expired or unknown identifier
Preventing a retry from creating a duplicate reply

Ephemeral messages are user-specific. Never treat them as a group broadcast mechanism.

4. Add Community events to the dispatcher

Communities link supergroups, channels, and bots around a shared topic or audience.

Bot API 10.2 introduces:

Community
CommunityChatAdded
CommunityChatRemoved
message.community_chat_added
message.community_chat_removed
ChatFullInfo.community

A handler that only checks message.text may silently discard these service messages.

Add explicit branches:

function handleMessage(message: TelegramMessage) {
  if (message.community_chat_added) {
    recordCommunityChatAdded(message);
    return;
  }

  if (message.community_chat_removed) {
    recordCommunityChatRemoved(message);
    return;
  }

  if (message.text) {
    handleTextMessage(message);
    return;
  }

  handleUnknownMessageType(message);
}

Do not use the Community ID as a replacement for the original chat ID.

A Community describes topology. Messages still need to be stored and routed according to their original chat identity.

A practical metadata model can retain both:

type CommunityChatRelation = {
  communityId: string;
  chatId: string;
  relationStatus: "active" | "removed";
  observedAt: string;
};

When topology changes:

Persist the lifecycle event
Update the relation state
Reconcile current information with getChat
Keep an audit record
Continue routing messages by their original chat ID

5. Handle the additional update type

Bot API 10.2 also adds BotSubscriptionUpdated and the subscription field on Update.

Even if your bot does not currently use payment subscriptions, make sure the webhook decoder does not reject an update merely because this field is present.

The safe pattern is:

Parse known top-level fields
Preserve unknown fields where possible
Log the event category without sensitive payload data
Route unsupported updates to an observable fallback
Avoid failing the entire webhook request

Returning a non-success response for every unknown update can create unnecessary retries.

6. Recheck Mini App origins

Telegram automatically enabled stricter Mini App origin protection on July 20, 2026, unless the bot opted out through BotFather.

Audit:

The configured Mini App domain
Redirect destinations
Embedded authentication pages
Payment or support pages
Calls made after navigation
Third-party content opened inside the Mini App
Development and staging domains

Do not solve an origin failure by broadly disabling protection without understanding which page initiated the call.

Test the production domain and each allowed non-production environment separately.

7. Avoid an unnecessary inbound rewrite

The new InputRichMessage builders primarily affect the outbound path.

They do not mean that every ordinary incoming user message must suddenly be parsed as a tree of rich blocks.

Your inbound work should focus on:

Recognizing the new Community service-message fields
Accepting subscription updates
Preserving new optional fields
Keeping an observable unknown-event fallback
Maintaining the existing text, media, and callback handling

This is a compatibility update, not a reason to replace a working inbound normalization pipeline.

8. Deploy behind separate feature flags

Use independent flags instead of one global “Bot API 10.2” switch.

const telegramFeatures = {
  richMessageBlocks: false,
  richMessageMedia: false,
  ephemeralEdits: false,
  communityTopology: true,
};

This lets you accept Community events immediately while delaying new outbound formatting.

A safe rollout looks like this:

Upgrade dependency
        ↓
Accept new webhook fields
        ↓
Deploy with outbound flags disabled
        ↓
Verify normal inbound traffic
        ↓
Enable one outbound feature internally
        ↓
Monitor errors and payloads
        ↓
Expand gradually

Monitor at least:

Telegram API error codes
Serialization failures
Unknown update counts
Community topology changes
Ephemeral edit/delete failures
Rich-message fallback usage
Webhook retry volume

9. Build a rollback path

Before production rollout, record:

Previous library version
New database fields
Feature-flag defaults
Payload format differences
Reversible and irreversible migrations
Rollback owner
Monitoring thresholds

If new fields are optional, prefer additive database changes. Do not make the previous application version unable to read records created during the rollout.

The rollback should disable new sends while still accepting already-delivered webhook fields.

Final upgrade checklist

[ ] Bot API library version is pinned
[ ] New SDK types and serialization have been inspected
[ ] Existing inbound regression tests pass
[ ] Exactly one Rich Message representation is enforced
[ ] Rich Message media references are validated
[ ] Plain-text fallbacks are available
[ ] Ephemeral message identifiers are persisted
[ ] Ephemeral edit and delete failure paths are tested
[ ] Community lifecycle events have explicit handler branches
[ ] Community topology is stored separately from chat routing
[ ] subscription updates do not break webhook decoding
[ ] Mini App production and staging origins have been checked
[ ] Outbound features use separate flags
[ ] Unknown updates remain observable
[ ] Dependency and feature rollback steps are documented

Bot API 10.2 is manageable when it is treated as several small migrations instead of one large feature launch.

Update the compatibility layer first. Enable Rich Messages, ephemeral editing, and Community-aware behavior only after the underlying fields, routing rules, and rollback path are ready.

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.

Before You Submit a LINE MINI App Service Message Template: A Review Checklist

unifyport — Tue, 28 Jul 2026 08:16:49 +0000

Passing a simulator test does not mean a LINE MINI App service message is ready for production.

A production service message must pass three separate gates:

Your LINE MINI App must be verified.
The service message template must pass review.
Your application must supply a valid service notification token at runtime.

This checklist helps you catch review and implementation problems before they delay your release.

1. Understand the three production gates

Treat verification, template review, and runtime delivery as separate controls.

Gate	What it checks
MINI App verification	Whether the service can use service messages in production
Template review	Whether the message content and use case comply with LINE requirements
Runtime token	Whether the message can be sent for the correct user action

An unverified MINI App can test service messages only through a Developing channel with users who have an Admin or Tester role.

Even after a template passes review, delivery can still fail if the service notification token is missing, expired, already used incorrectly, or unrelated to the current user action.

2. Know the template states

The template status in the LINE Developers Console is an operational signal, not just a label.

Status	Meaning
`DEVELOPING`	Review has not been requested. The template is available only for development testing.
Under review	The submitted template is being evaluated. Some template operations are restricted.
`PUBLISHING`	The template passed review and can be used in production after the MINI App is verified.

While a template is under review, you can inspect it and run simulator tests, but you cannot freely add templates, delete them, or edit their Use Case.

Plan your complete template set before requesting review.

3. Start from the user action

A service message should confirm, report the result of, or remind the user about an action they performed in the MINI App.

Good use cases include:

Confirming a reservation
Reporting a payment result
Sending a delivery update
Reminding a user about an upcoming appointment
Reporting that a submitted request has completed

A weak use case would be:

Send customers information about available products.

A stronger version would be:

After a customer completes a delivery booking, send a confirmation containing the booking number, delivery date, and status page link.

The second version identifies:

The triggering action
The recipient
The delivery timing
The message purpose
The expected content

Promotional messages, discounts, coupons, shopping rewards, new-product announcements, and general event announcements are not appropriate service-message use cases.

4. Document the entire message sequence

Do not review each message in isolation.

Document the sequence from the triggering action to the final service message:

User completes an action
        ↓
MINI App receives a service notification token
        ↓
Backend stores the token securely
        ↓
Backend selects an approved template
        ↓
Service message is sent
        ↓
Renewed token and remaining count are processed

For each message, record:

Triggering user action
Delivery timing
Template name
Language
Variable source
Destination link
Expected next user action

LINE normally permits up to five service messages for one user action, although the reviewed limit may differ by use case.

5. Choose the template and language early

LINE provides predefined service message templates. A channel can register up to 20 templates.

Supported template languages include:

Japanese
English
Traditional Chinese
Thai
Indonesian
Korean

Choose the required language variants before review. Adding or changing template information later can require another review.

For API requests, use the exact template name displayed in the LINE Developers Console. The effective name includes the template name and its BCP 47 language tag.

Do not reconstruct or translate the identifier in application code.

For example:

{
  "templateName": "delivery_result_en"
}

Treat templateName as an approved configuration value rather than a label generated at runtime.

6. Validate every variable

For every variable, confirm:

Its value comes from the action described in the Use Case
It is available when the message is sent
It cannot contain unexpected HTML or formatting
Its fallback behavior is defined
Its maximum length is enforced before the API call

LINE applies different recommendations and limits depending on the variable type.

Variable type	Recommended	Soft limit	Hard limit
Detailed	10 grapheme clusters	36	50
Simple	32 grapheme clusters	100	150

A grapheme cluster is closer to a user-perceived character than a raw byte or code point. Emoji and combined Unicode characters make this distinction important.

Your preflight validation should therefore use Unicode-aware length checks.

If a template contains no variables, send an empty params object rather than inventing placeholder values:

{
  "templateName": "booking_confirmation_en",
  "params": {}
}

7. Review button behavior

For templates containing buttons:

The first button is required
Additional buttons may be optional
Each button must use a permanent link
The destination must be available after the message is delivered
The link should take the user directly to the relevant result or next action

Avoid temporary URLs that expire before the user opens the message.

Also test:

Whether the link opens the expected MINI App page
Whether authentication state is handled correctly
Whether an invalid or completed record has a safe fallback
Whether the page still works when opened later from message history

8. Use the simulator as a content test

Before submission, preview every language variant in the simulator.

Check:

Long customer names
Long order or reservation identifiers
Emoji and combined characters
Empty optional values
Date and time formats
Currency formats
Button-label truncation
Permanent-link destinations
Differences between language variants

The simulator helps validate layout and content. It does not prove that the template is approved or that production token handling works.

9. Freeze the review package

Before requesting review, prepare one review package containing:

Final template list
Languages
Use Case
Message sequence
Variable definitions
Example values
Permanent links
Screenshots or simulator results
Runtime template identifiers

A compact internal record might look like this:

{
  "templateName": "delivery_result_en",
  "approvedUseCase": "Send the delivery result after the user completes a booking",
  "actionType": "delivery_booking",
  "variables": [
    "order_id",
    "delivery_status"
  ],
  "permanentLink": "https://miniapp.line.me/example",
  "reviewStatus": "PUBLISHING"
}

Freezing this information reduces the risk that the reviewed template differs from the implementation shipped by another team.

10. Prepare the production handoff

Before enabling production traffic, verify all of the following:

The MINI App is verified
The required template status is PUBLISHING
The backend uses the exact reviewed templateName
Each token is associated with the correct user action
Tokens are not exposed in application logs
Renewed tokens are stored correctly
remainingCount is checked when planning follow-up messages
Retries cannot accidentally duplicate a service message
Failures are observable without logging sensitive token values

Template approval and runtime token management solve different problems. Both must be tested.

11. Control changes after approval

After the LINE MINI App is verified, changes to service message template information require re-review.

Before modifying a reviewed template, compare:

Triggering action
Delivery timing
Message purpose
Text content
Variables
Language variants
Button labels
Permanent links
Message sequence

Do not treat a text or URL adjustment as automatically safe just because the overall business flow has not changed.

Final pre-submission checklist

[ ] The Use Case begins with a specific user action
[ ] The message is transactional, not promotional
[ ] The full message sequence is documented
[ ] The channel remains within the 20-template limit
[ ] Every required language variant is ready
[ ] Every variable has a source, limit, and fallback
[ ] Unicode-aware length validation is implemented
[ ] The first button and every permanent link have been tested
[ ] Long and empty values have been tested in the simulator
[ ] Runtime code uses the exact console template name
[ ] The review package matches the implementation
[ ] Production token storage, renewal, and retry behavior have been tested
[ ] The team understands which future changes require re-review

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.

How to Stop Queued WhatsApp Replies After the 24-Hour Window Expires

unifyport — Mon, 27 Jul 2026 02:51:54 +0000

A WhatsApp reply can be valid when an agent writes it and invalid when a queue worker finally sends it.

Approval queues, retries, outages, and delayed jobs can all push a free-form reply beyond WhatsApp's 24-hour customer service window. Checking the window only in the UI is therefore not enough—the sender needs a server-side guard immediately before transport.

This tutorial builds that guard with explicit timestamps, idempotent inbound processing, and versioned conversation state.

The queue race

Consider this sequence:

10:00 — Customer sends a message
10:05 — Agent writes a reply
10:10 — Reply is approved
09:59 next day — Job is still waiting
10:01 next day — Worker claims the job

The reply was valid when it was written and approved, but the customer service window has expired by the time the worker attempts to send it.

The worker must block the non-template send and return an explicit routing result. It must not trust a decision made earlier in the workflow.

Model timestamps instead of one boolean

Avoid storing a single value such as:

const isFreeConversation = true;

That value does not explain:

When the window expires
Which user message opened it
Whether the event was duplicated
Whether a newer event already changed the state
Whether a separate free-entry period is active
Whether a queued worker is using stale state

Store explicit state instead:

type WhatsAppWindowState = {
  serviceWindowExpiresAt: Date | null;
  freeEntryExpiresAt: Date | null;
  lastUserMessageAt: Date | null;
  lastUserMessageId: string | null;
  stateVersion: number;
};

Each field has a separate job.

Field	Purpose
`serviceWindowExpiresAt`	Controls whether a non-template service reply is permitted
`freeEntryExpiresAt`	Records the separate 72-hour free-entry billing period
`lastUserMessageAt`	Prevents an older event from moving the window backward
`lastUserMessageId`	Provides idempotency and audit evidence
`stateVersion`	Detects stale workers and concurrent state changes

The 72-hour free-entry period is not an extended customer service window. Keep the two clocks separate.

Evaluate permission separately from pricing

The send guard should answer whether the selected transport is permitted.

Do not hard-code market rates or future pricing rules into the permission state machine.

type SendDecision =
  | {
      allowed: true;
      path: "non_template_service";
      serviceWindowExpiresAt: Date;
      stateVersion: number;
      freeEntryActive: boolean;
    }
  | {
      allowed: false;
      path: "approved_template_or_human_review";
      reason: "service_window_expired" | "no_user_message";
      stateVersion: number;
      freeEntryActive: boolean;
    };

function evaluateWhatsAppSend(
  state: WhatsAppWindowState,
  now: Date,
): SendDecision {
  const serviceWindowOpen =
    state.serviceWindowExpiresAt !== null &&
    now.getTime() < state.serviceWindowExpiresAt.getTime();

  const freeEntryActive =
    state.freeEntryExpiresAt !== null &&
    now.getTime() < state.freeEntryExpiresAt.getTime();

  if (!serviceWindowOpen) {
    return {
      allowed: false,
      path: "approved_template_or_human_review",
      reason:
        state.serviceWindowExpiresAt === null
          ? "no_user_message"
          : "service_window_expired",
      stateVersion: state.stateVersion,
      freeEntryActive,
    };
  }

  return {
    allowed: true,
    path: "non_template_service",
    serviceWindowExpiresAt: state.serviceWindowExpiresAt,
    stateVersion: state.stateVersion,
    freeEntryActive,
  };
}

Notice the strict comparison:

now < serviceWindowExpiresAt

At the exact expiry timestamp, treat the window as closed.

Update the window only from verified user messages

Not every webhook should extend the service window.

These events must not reset it:

Delivery receipts
Read receipts
Message status changes
Agent drafts
Internal notes
Retry events
Business-sent message echoes
Duplicate webhook deliveries

A safe inbound sequence is:

Verify the provider webhook.
Parse the verified payload.
Confirm that the event represents a user-sent inbound message.
Deduplicate using the stable message or event ID.
Reject stale state changes from older events.
Set the expiry to the accepted message timestamp plus 24 hours.
Increment stateVersion.
Save the source event for audit.

A simplified updater:

type InboundUserMessage = {
  id: string;
  occurredAt: Date;
};

function applyInboundUserMessage(
  state: WhatsAppWindowState,
  message: InboundUserMessage,
): WhatsAppWindowState {
  if (message.id === state.lastUserMessageId) {
    return state;
  }

  if (
    state.lastUserMessageAt !== null &&
    message.occurredAt.getTime() <= state.lastUserMessageAt.getTime()
  ) {
    return state;
  }

  return {
    ...state,
    lastUserMessageId: message.id,
    lastUserMessageAt: message.occurredAt,
    serviceWindowExpiresAt: new Date(
      message.occurredAt.getTime() + 24 * 60 * 60 * 1000,
    ),
    stateVersion: state.stateVersion + 1,
  };
}

Do not add 24 hours to the previous expiry.

If the user sends a message at 09:00 and another at 12:00, the new expiry is 12:00 the next day—not one extra day after the previous expiry.

Recheck the state when claiming a queued reply

The UI may display the current window, but the queue worker owns the final decision.

When claiming a job:

Lock the reply job.
Load the latest conversation state.
Evaluate the state using the current server time.
Record the decision and stateVersion.
Mark the job for the selected route.
Commit the short transaction.
Recheck the captured deadline immediately before transport.

Conceptually:

async function claimQueuedReply(
  jobId: string,
  now: Date,
) {
  return database.transaction(async (transaction) => {
    const job = await transaction.lockReplyJob(jobId);
    const state = await transaction.lockConversationState(
      job.conversationId,
    );

    if (job.status !== "queued") {
      return {
        outcome: "already_claimed",
      } as const;
    }

    const decision = evaluateWhatsAppSend(state, now);

    if (!decision.allowed) {
      await transaction.updateReplyJob(jobId, {
        status: "needs_rerouting",
        reason: decision.reason,
        evaluatedStateVersion: decision.stateVersion,
      });

      return {
        outcome: "blocked",
        decision,
      } as const;
    }

    await transaction.updateReplyJob(jobId, {
      status: "ready_to_send",
      evaluatedStateVersion: decision.stateVersion,
      sendBefore: decision.serviceWindowExpiresAt,
    });

    return {
      outcome: "ready",
      decision,
    } as const;
  });
}

Do not keep a database transaction open across the external WhatsApp API request.

Instead, persist the decision and deadline, then let the transport layer perform a final time check before sending:

function assertBeforeTransport(
  sendBefore: Date,
  now: Date,
) {
  if (now.getTime() >= sendBefore.getTime()) {
    throw new Error("service_window_expired");
  }
}

If the job waits again after being marked ready, it must return through the guard.

Do not silently convert expired text into a template

When the 24-hour window closes, the state machine should return a routing decision—not rewrite content.

Safe outcomes include:

non_template_service
approved_template
human_review
blocked

Unsafe behavior includes:

Automatically converting arbitrary text into a template
Truncating a reply until it fits a template
Selecting a template based only on keyword similarity
Reusing template variables with a different business purpose
Sending first and reviewing the decision afterward

Templates have their own approved wording, category, variables, and business intent. Those contracts belong to a separate decision step.

Test the one-second boundaries

Use a fixed clock in automated tests.

describe("evaluateWhatsAppSend", () => {
  const expiry = new Date("2026-07-28T10:00:00.000Z");

  const state: WhatsAppWindowState = {
    serviceWindowExpiresAt: expiry,
    freeEntryExpiresAt: null,
    lastUserMessageAt: new Date(
      "2026-07-27T10:00:00.000Z",
    ),
    lastUserMessageId: "msg_123",
    stateVersion: 7,
  };

  it("allows a reply one millisecond before expiry", () => {
    const decision = evaluateWhatsAppSend(
      state,
      new Date("2026-07-28T09:59:59.999Z"),
    );

    expect(decision.allowed).toBe(true);
  });

  it("blocks a reply at the exact expiry time", () => {
    const decision = evaluateWhatsAppSend(
      state,
      new Date("2026-07-28T10:00:00.000Z"),
    );

    expect(decision.allowed).toBe(false);
  });
});

Also test these scenarios:

Scenario	Expected result
Reply at `23:59:59` after the user message	Non-template reply allowed
Reply at exactly 24 hours	Window closed
New user message before expiry	Expiry resets from the new message
Reply approved before expiry but claimed afterward	Non-template transport blocked
Duplicate inbound webhook	State remains unchanged
Older event arrives after a newer event	Expiry does not move backward
Two workers claim the same reply	Only one worker commits the claim
Job is delayed after being marked ready	Transport checks the deadline again

Keep an audit trail

For every send decision, record:

type SendAuditRecord = {
  replyJobId: string;
  conversationId: string;
  evaluatedAt: Date;
  evaluatedStateVersion: number;
  serviceWindowExpiresAt: Date | null;
  freeEntryExpiresAt: Date | null;
  selectedPath:
    | "non_template_service"
    | "approved_template"
    | "human_review"
    | "blocked";
  reason: string;
};

This makes it possible to answer:

Which user message opened the window?
Which state version did the worker evaluate?
Was the job already expired when it was claimed?
Did another worker process the same reply?
Was the message sent as free-form text or through a template?
Why was the job routed to human review?

Implementation checklist

Before release:

[ ] Verify webhook signatures before changing state
[ ] Deduplicate inbound user messages
[ ] Ignore receipts, echoes, and internal events
[ ] Normalize provider timestamps to UTC
[ ] Store explicit expiry timestamps
[ ] Keep the 24-hour and 72-hour clocks separate
[ ] Increment a monotonic stateVersion
[ ] Re-evaluate state when claiming a queued reply
[ ] Check the deadline again immediately before transport
[ ] Treat the exact expiry timestamp as closed
[ ] Prevent concurrent workers from claiming one reply
[ ] Route expired drafts instead of rewriting them
[ ] Keep permission and pricing calculations separate
[ ] Store a complete send-decision audit record

Final takeaway

A WhatsApp reply is not authorized forever just because it was valid when an agent drafted it.

The reliable boundary is the moment the worker attempts transport.

A safe implementation should:

Update the window only from verified, deduplicated user messages.
Store explicit timestamps and a monotonic state version.
Re-evaluate the state when a queued reply is claimed.
Check the deadline again before the external API request.
Block expired free-form replies.
Route them to an approved-template decision or human review.
Keep charging calculations outside the permission state machine.

The UI can explain the window, but the server-side sender must enforce it.

Official reference

WhatsApp Business Platform pricing and customer service window

Originally published on UnifyPort.

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

Third-Party AI Assistants on WhatsApp in the EU: What Changed in 2026

unifyport — Thu, 23 Jul 2026 05:55:23 +0000

On June 9, 2026, the European Commission ordered Meta to restore free WhatsApp access for competing general-purpose AI assistants while its antitrust investigation continues.

That sounds simple, but the headline is easy to overread.

The measure does not mean that every third-party assistant is automatically available on every WhatsApp account. It is regional, temporary, and focused on a specific distribution path: competing general-purpose AI assistants using the WhatsApp Business API.

The short answer

Can third-party AI assistants use WhatsApp in Europe again?

Yes, under the interim conditions ordered by the European Commission—but actual availability still depends on the provider, region, onboarding status, and account eligibility.

The order requires Meta to restore the access conditions that applied before October 15, 2025, including free access, and to maintain them until the Commission reaches a final decision.

It does not:

Create Business API credentials for a provider
Complete Meta app review
Approve individual WhatsApp accounts
Guarantee worldwide access
Apply automatically to every type of business chatbot
Represent a final finding that Meta violated competition law

The timeline

The distinction between policy, access, fees, and interim enforcement becomes clearer when viewed as a timeline.

Date	Event	Practical meaning
October 15, 2025	Meta adopted a policy restricting competing general-purpose AI assistants from using the WhatsApp Business API	Rival assistants lost the previous distribution path
December 2025	The European Commission opened an antitrust investigation	Meta's policy entered formal competition review
March 4, 2026	Meta readmitted third-party general-purpose assistants but introduced a fee	Access returned, but the Commission preliminarily considered the fee equivalent to the earlier restriction
June 9, 2026	The Commission imposed interim measures	Meta was ordered to restore the previous free-access conditions
Five working days later	Compliance deadline specified by the Commission	Meta was required to implement the temporary remedy
Final decision	Still pending	The underlying antitrust investigation remains open

An interim measure protects competition while an investigation continues. It changes what Meta must do now, but it does not predetermine the final legal outcome.

Which type of “WhatsApp AI” are we discussing?

The phrase “WhatsApp AI” can describe several unrelated products and architectures.

Product or integration	Covered directly by the EU measure?
A competing general-purpose AI assistant distributed through the WhatsApp Business API	Yes—this is the core subject
A business-specific support bot answering questions about one company	Not necessarily; its terms and permissions may be different
Meta AI	No; this is Meta's own assistant
Meta Business Agent	No; this is another Meta product
An internal workflow that sends inbound customer messages to an AI model	This is a separate integration decision
A third-party assistant outside the European market	No automatic conclusion should be drawn

This distinction matters because the legal measure concerns access to a distribution channel. It does not define the technical availability of every chatbot, account, or region.

Why might an assistant still be unavailable?

Even after the interim measure, a third-party assistant may still be unavailable for several reasons:

The provider has not completed restored Business API onboarding.
The provider has not reopened registration in the target region.
The user or business account is outside the relevant rollout.
The account does not meet Meta's current eligibility requirements.
The integration belongs to a different product category.
App review, business verification, or permissions are incomplete.
The provider has restored its public assistant but not the related webhook or operational controls.

A legal order does not automatically create credentials, deploy code, configure webhooks, or approve an account.

A verification checklist for engineering teams

Before changing a production integration, verify each layer independently.

1. Confirm the region

Record:

Where the AI provider is established
Where the service is being offered
Where the WhatsApp user or business account is located
Whether the provider describes the rollout as EU, EEA, or global

Do not treat a European competition remedy as a global product announcement.

2. Name the product precisely

Determine whether the integration is:

A general-purpose AI assistant
A business-specific customer-support agent
Meta AI
Meta Business Agent
A Cloud API application
A BSP-managed integration
An internal message-processing workflow

These products do not necessarily use the same access or approval path.

3. Ask the provider for current operational status

Confirm:

Whether Business API access has been restored
Whether new onboarding is open
Which regions are active
Which accounts are eligible
Whether pricing has changed
Whether the provider has published a migration notice
Whether existing users need to reconnect

The Commission's decision is authoritative for the competition measure. The provider remains the authoritative source for its own rollout.

4. Retest the complete workflow

Do not stop after confirming that an assistant profile is visible.

Test:

User consent
Incoming messages
Webhook delivery
Conversation state
Model invocation
Human handoff
Reply delivery
Logging and retention
Account disconnect and recovery

A working profile page does not prove that the operational integration is healthy.

Keep the architecture reversible

Platform policies, regional rollouts, fees, and account rules can change independently.

A more resilient architecture separates the major stages:

WhatsApp message
       |
       v
Message intake
       |
       v
Consent and policy checks
       |
       v
Conversation storage
       |
       +------------------+
       |                  |
       v                  v
AI model              Human queue
       |                  |
       +--------+---------+
                |
                v
          Reply delivery

This separation provides several advantages:

The message history does not belong exclusively to one model.
A human agent can take over without losing context.
The AI provider can be replaced without rebuilding message intake.
Regional policies can be applied before model invocation.
Reply delivery can be disabled independently during an incident.
Audit logs can distinguish automated and human responses.

The legal right of a provider to access WhatsApp and the technical design of a company's support workflow are related, but they are not the same decision.

Common interpretation mistakes

“The WhatsApp AI ban has been permanently cancelled”

Not confirmed.

The Commission imposed interim measures while the investigation continues. A final decision has not yet been reached.

“Every third-party assistant should now work”

Not necessarily.

The provider still needs operational access, regional rollout, appropriate credentials, and eligible accounts.

“The measure applies worldwide”

Do not assume that.

The decision addresses competition in the European market and should not be treated as a global availability guarantee.

“Meta AI availability proves that competitors are available”

No.

Meta AI is a Meta product. Its rollout does not demonstrate that a competing provider has completed Business API onboarding.

“A customer-support chatbot is automatically covered”

Not always.

The measure focuses on competing general-purpose AI assistants. A business-specific support agent may be governed by different product terms and permissions.

What teams should document

For every affected integration, record:

Provider name
Product category
WhatsApp access method
Target region
Business verification state
App-review state
Required permissions
Webhook configuration
Human handoff behavior
Current pricing terms
Provider confirmation date
Last successful end-to-end test

This creates a verifiable operational record instead of relying on a news headline or assumptions about account eligibility.

Final takeaway

The 2026 EU interim measures are important, but their scope is narrower than “third-party WhatsApp AI is available again.”

The accurate interpretation is:

The European Commission ordered Meta to restore free WhatsApp Business API access for competing general-purpose AI assistants.
The restored conditions apply while the antitrust investigation continues.
The measure is not a final judgment.
Actual availability still depends on provider rollout, onboarding, region, and account eligibility.
Engineering teams should retest the entire message workflow before changing production routing.
Message intake, AI reasoning, human handoff, and reply delivery should remain separable.

Treat the Commission's announcement as a policy and access change—not as proof that a particular assistant or account is production-ready.

Official sources

Originally published on UnifyPort.

This article provides a technical and product interpretation, not legal advice. It was prepared with AI assistance for language and structure, then reviewed and fact-checked against the cited official sources.

Recover Missed LINE MINI App Purchase Webhooks with a 7-Day Reconciliation Job

unifyport — Wed, 22 Jul 2026 09:02:38 +0000

A successful LINE MINI App purchase reservation does not mean that the customer completed the payment.

The final source of truth is the purchaseComplete webhook. But what happens when your endpoint is unavailable, a deployment breaks webhook processing, or the event reaches your server but the business transaction fails?

LINE provides an event history API that can recover purchase webhooks from the previous seven days. The recovery process still needs careful pagination, reconciliation, and idempotency to avoid granting the same item twice.

Reservation success and purchase completion are different events

LINE MINI App in-app purchases use a multi-step flow.

Your server first reserves the purchase:

POST https://api.line.me/iap/v1/product/reserve

LINE returns an orderId, but the customer can still:

Close the MINI App
Cancel the app-store payment
Lose network connectivity
Fail to finish the payment flow

The digital item or entitlement should therefore be granted only after processing a purchaseComplete event.

These are four separate questions:

Question	Evidence to trust
Did the reservation succeed?	Reserve response, saved `orderId`, and `x-line-request-id`
Did the purchase complete?	A `purchaseComplete` event
Did the live webhook reach your endpoint?	Raw request log and webhook-processing record
Was the entitlement granted exactly once?	An idempotency record keyed by `orderId`

Store recovery data when reserving the purchase

A recovery job cannot reconcile an order if the reservation was never recorded.

Store at least:

Your internal checkout ID
LINE's orderId
The x-line-request-id response header
Reservation timestamp
Expected product or entitlement
Current purchase state
Whether a purchaseComplete event has already been applied

Alert when a reservation remains unresolved beyond the expected checkout duration.

Do not mark it as paid automatically, and do not wait until the seventh day to investigate. The event history API only covers the preceding seven days.

Query a fixed recovery window

Use the official event history endpoint:

curl --get "https://api.line.me/iap/v1/webhook/events" \
  -H "Authorization: Bearer ${LINE_CHANNEL_ACCESS_TOKEN}" \
  --data-urlencode "startEpochSeconds=1784678400" \
  --data-urlencode "endEpochSeconds=1784700000" \
  --data-urlencode "pageSize=100" \
  --data-urlencode "status=FAILED"

The timestamps above are example values for a window on July 22, 2026. Generate UTC epoch seconds from the actual incident start and end times.

The status filter describes webhook delivery:

FAILED: LINE could not successfully deliver the webhook
SUCCESS: LINE successfully delivered it

It does not describe whether the customer's payment succeeded or failed.

When the problem occurred after your endpoint accepted the request, querying only status=FAILED may not be sufficient. In that case, omit the filter and reconcile every event within the incident window.

Keep pagination parameters stable

The history endpoint returns at most 100 records per page and may include a nextCursor.

For every subsequent page, keep these values unchanged:

startEpochSeconds
endEpochSeconds
pageSize
status

Only the cursor should change.

const baseUrl = "https://api.line.me/iap/v1/webhook/events";

const fixedQuery = {
  startEpochSeconds: "1784678400",
  endEpochSeconds: "1784700000",
  pageSize: "100",
  status: "FAILED",
};

let cursor;

do {
  const query = new URLSearchParams(fixedQuery);

  if (cursor) {
    query.set("cursor", cursor);
  }

  const response = await fetch(`${baseUrl}?${query}`, {
    headers: {
      Authorization: `Bearer ${process.env.LINE_CHANNEL_ACCESS_TOKEN}`,
    },
  });

  if (!response.ok) {
    throw new Error(
      `LINE event history request failed: ${response.status}`,
    );
  }

  const page = await response.json();

  for (const record of page.events) {
    if (record.event.type === "purchaseComplete") {
      await applyPurchaseOnce(
        record.event.orderId,
        record.event,
      );
    }
  }

  cursor = page.nextCursor ?? undefined;
} while (cursor);

Changing the time range or filters during pagination can create overlaps or gaps in the recovery result.

Use the same handler for live and recovered events

Do not create a separate entitlement implementation exclusively for recovered events.

Both paths should call the same business handler:

Live webhook ────────┐
                     ├── applyPurchaseOnce(orderId, event)
Event history API ───┘

The handler should atomically:

Insert an idempotency record keyed by orderId
Stop if that key already exists
Validate the expected product and order state
Grant the entitlement
Mark the purchase as completed
Commit everything in one transaction

If the live webhook was already applied, the recovered event should become a no-op.

Conceptually:

async function applyPurchaseOnce(orderId, event) {
  return database.transaction(async (transaction) => {
    const inserted = await transaction.insertIdempotencyKey(orderId);

    if (!inserted) {
      return {
        status: "already_applied",
        orderId,
      };
    }

    await transaction.grantEntitlement({
      orderId,
      productId: event.productId,
    });

    await transaction.markPurchaseCompleted(orderId);

    return {
      status: "applied",
      orderId,
    };
  });
}

The exact database API will differ, but the idempotency record and entitlement update must share the same transaction boundary.

Reconcile four sources of evidence

For a fixed incident window, compare:

Reserved orderId values that remain unresolved
Live webhook request and processing logs
Event history records returned by LINE
Idempotency and entitlement records in your database

Classify every reservation as one of:

Completed and applied
Completed but already applied
Incomplete or canceled
Missing and requiring manual investigation

Record the following information in the incident report:

Exact UTC start and end timestamps
Applied filters
Number of pages processed
Number of events examined
Recovered orderId values
Duplicate events skipped
Last successful recovery time

Continue verifying live webhook signatures

The history API uses a channel access token. It does not recreate the original HTTP webhook request and should not be expected to contain its original signature header.

For live deliveries, continue verifying LINE's x-line-signature against the raw request body using the channel secret.

Do not parse and serialize the JSON again before verification. Signature validation must use the exact raw bytes received by the endpoint.

Recovered history events should be marked with a source such as:

{
  "source": "line_event_history",
  "orderId": "example-order-id"
}

This makes audit logs distinguishable without introducing a second entitlement path.

Important limitations

The event history API is a recovery source, not a replacement for live webhook monitoring.

Keep these boundaries in mind:

The lookback period is seven days, not a permanent ledger
Each page returns at most 100 records
status=FAILED reports delivery failure, not purchase failure
A successfully delivered webhook may still fail inside your application
Recovered events may duplicate events already processed live
Refund history may follow a different API lifecycle
Your own reservation and entitlement records must be retained longer than seven days

Schedule reconciliation frequently enough that a weekend outage cannot age out of the recovery window.

Recovery checklist

Before running the job:

[ ] Confirm the exact UTC incident window
[ ] Save the original query parameters
[ ] Confirm the channel access token is available server-side
[ ] Back up or snapshot the unresolved reservation list
[ ] Verify that applyPurchaseOnce is idempotent

While processing:

[ ] Keep filters unchanged across pages
[ ] Change only cursor
[ ] Process only expected event types
[ ] Deduplicate by orderId
[ ] Record recovered and skipped orders
[ ] Stop on authentication or schema errors

After processing:

[ ] Reconcile every reservation in scope
[ ] Confirm entitlements were granted exactly once
[ ] Record the last successful recovery checkpoint
[ ] Investigate records that remain unclassified
[ ] Confirm live webhook monitoring is healthy again

Final takeaway

A successful purchase reservation is not proof of payment, and a missed live webhook does not need to become a permanent lost order.

A reliable recovery workflow should:

Query LINE's event history before the seven-day boundary
Keep the incident window fixed during pagination
Replay purchaseComplete events through the live business handler
Use orderId as the idempotency key
Reconcile reservations, deliveries, and entitlements before closing the incident

The history endpoint helps recover the event. Your own durable records and idempotent transaction determine whether recovery is safe.

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.

How LINE MINI App Service Notification Tokens Work (and Why You Must Rotate Them)

unifyport — Tue, 21 Jul 2026 08:36:35 +0000

LINE MINI App service messages are not ordinary push notifications.

They use a user-bound, action-specific notification token that changes after every successful send. If your application keeps using the original token, later reminders can fail even when the template and channel credentials are correct.

This guide explains the complete flow: issuing the token, sending an approved template, saving the renewed token, and handling retries safely.

Prerequisites

Before implementing the API flow, make sure:

Your LINE MINI App is verified for production use.
The service-message template has been approved.
The message confirms or responds to an action completed by the user.
The channel access token is stored only on your server.

Unverified MINI Apps can test service messages in a Developing channel, but they cannot send production service messages from a Published channel.

Understand the three tokens

Three different credentials are involved in the flow.

Credential	Purpose	Important lifecycle rule
LIFF access token	Identifies the current LINE user	Exchange it shortly after the user completes the action
Channel access token	Authorizes server-side LINE API calls	Never expose it to the browser
Service notification token	Authorizes notifications for one user action	Replace it after every successful send

A LIFF access token can be obtained in the MINI App with:

const liffAccessToken = liff.getAccessToken();

Send this value to your backend over HTTPS after the reservation, purchase, check-in, or other approved action succeeds.

Do not write the LIFF access token or service notification token to application logs.

Step 1: Issue a service notification token

Your backend exchanges the LIFF access token for a service notification token:

curl -X POST https://api.line.me/message/v3/notifier/token \
  -H "Authorization: Bearer ${LINE_CHANNEL_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"liffAccessToken\":\"${LIFF_ACCESS_TOKEN}\"}"

A successful response looks like this:

{
  "notificationToken": "34c11a03-b726-49e3-8ce0-949387a9f531",
  "expiresIn": 31536000,
  "remainingCount": 5,
  "sessionId": "xD06R2407210008"
}

Store the following values:

notificationToken
expiresIn
remainingCount
sessionId
Your internal order, reservation, or action ID

The token is bound to one user and one action session. It is not a reusable user identifier.

One LIFF access token can issue only one service notification token, so perform the exchange once and persist the result.

Step 2: Send an approved template

Use the service notification token with the official send endpoint:

curl -X POST "https://api.line.me/message/v3/notifier/send?target=service" \
  -H "Authorization: Bearer ${LINE_CHANNEL_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "thankyou_msg_en",
    "params": {
      "date": "2026-07-21",
      "username": "Brown & Cony"
    },
    "notificationToken": "34c11a03-b726-49e3-8ce0-949387a9f531"
  }'

A few details are easy to miss:

target=service is required.
templateName must exactly match an approved template.
The keys inside params must match the variables defined by that template.
If the template has no variables, params is still required and should be {}.

Step 3: Save the renewed token

This is the most important implementation rule:

After every successful send, replace the stored notification token with the new token returned by LINE.

The response contains an updated token and counters:

{
  "notificationToken": "renewed-token-value",
  "expiresIn": 31536000,
  "remainingCount": 4,
  "sessionId": "xD06R2407210008"
}

Do not schedule another reminder until the renewed token has been saved successfully.

A safe sequence is:

Lock or version the action record.
Send the approved service-message template.
Receive the successful response.
Replace the stored notification token.
Update remainingCount and expiresIn.
Commit the database transaction.
Schedule the next reminder.

This prevents two workers from sending with the same token concurrently.

Example storage model

A minimal action record could look like this:

{
  "actionId": "order_12345",
  "sessionId": "xD06R2407210008",
  "notificationToken": "encrypted-token-value",
  "remainingCount": 4,
  "expiresAt": "2027-07-21T10:00:00Z",
  "version": 2
}

Encrypt the notification token at rest and use the version field—or an equivalent database lock—to prevent concurrent updates.

Handling errors and retries

Treat notification tokens as rotating credentials, not permanent addresses.

HTTP 400

Check:

Request body format
Template name
Template variables
Recipient state
Current notification token

Do not repeatedly retry the same invalid request.

HTTP 401

Refresh or verify the server-side channel credential.

If the LIFF access token or service notification token is invalid, start a new eligible user-action flow instead of replaying it indefinitely.

HTTP 403

Confirm:

The channel is authorized for the operation
The MINI App has the required status
The template exists and is approved

Concurrent sends

Never allow two workers to spend the same notification token simultaneously. Use a database lock, compare-and-swap update, or version check around the send operation.

Message limits

A newly issued token is normally valid for up to one year and starts with a limited number of sends.

The reviewed use case may have a different limit, so your application should always treat the latest remainingCount returned by LINE as the runtime source of truth.

Service messages must remain tied to the original user action. They are designed for cases such as:

Reservation confirmations
Order results
Shipping updates
Reminders related to the original action

They are not intended for:

Advertising
Coupons
Product promotions
General announcements
Free-form customer support conversations

Implementation checklist

Before releasing the integration, verify:

[ ] The LIFF access token is collected after an eligible user action
[ ] Token exchange happens on the server
[ ] Channel credentials are never exposed to the browser
[ ] Tokens are not written to application logs
[ ] The exact approved template name is used
[ ] target=service is included
[ ] The renewed notification token is saved after every send
[ ] remainingCount is checked before scheduling another message
[ ] Concurrent sends are prevented
[ ] Failed requests use bounded, reason-specific retry logic

Conclusion

The API calls themselves are straightforward. The difficult part is managing the notification token correctly.

Think of it as a rotating credential associated with one user action:

Obtain a fresh LIFF access token.
Exchange it on the server.
Send an approved template.
Save the renewed notification token.
Use the latest remainingCount for future decisions.

If you get the rotation and concurrency rules right, follow-up service messages become much more predictable.

Sources

Originally published on UnifyPort.

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

Five Things Every Production Webhook Receiver Should Handle

unifyport — Mon, 20 Jul 2026 07:39:11 +0000

Webhooks look simple at first.

Your application exposes an HTTP endpoint, another service sends a JSON payload, and your code processes the event.

But a webhook receiver that works in a local demo is very different from one that can safely handle production traffic.

Here are five things every production webhook receiver should handle.

1. Verify every webhook request

A public webhook endpoint can receive requests from anyone on the internet.

Your application should verify that each request really came from the expected service before processing its contents.

A common approach is HMAC signature verification:

The sender signs the raw request body with a shared secret.
The signature is included in an HTTP header.
Your receiver calculates the expected signature.
The two signatures are compared using a timing-safe comparison.

Always verify the signature before parsing or processing the event.

It is also important to verify the raw request body. Parsing and serializing JSON again can change the bytes and cause a valid signature check to fail.

2. Make event processing idempotent

Webhook providers may deliver the same event more than once.

This can happen when your server times out, returns an error, or successfully processes an event but fails to return a response quickly enough.

Every event should have a unique identifier. Store that identifier before performing an action that must happen only once.

Without idempotency, one customer message could create multiple support tickets, notifications, or automated replies.

For a small application, event identifiers can be stored in a database table. Larger systems may use Redis or another shared idempotency store.

3. Respond quickly and process asynchronously

A webhook endpoint should not perform long-running work inside the HTTP request.

Instead, the receiver should:

Verify the request.
Validate the event.
Store it or add it to a queue.
Return a successful response.
Process the event asynchronously.

This prevents temporary problems in a CRM, AI service, database, or notification system from blocking webhook delivery.

It also makes retry behavior easier to control.

4. Store the original event

Do not treat a Slack notification, CRM record, or application log as the only copy of an inbound event.

Store the original webhook event before transforming it.

This gives your team a reliable record for:

Debugging delivery problems
Reprocessing failed events
Investigating customer reports
Auditing automated actions
Comparing old and new event schemas

Sensitive message contents should only be stored when necessary and should follow your privacy and retention policies.

5. Monitor delivery and processing failures

A production webhook system needs more than application logs.

Useful metrics include:

Number of received events
Invalid signature attempts
Duplicate deliveries
Processing duration
Queue depth
Downstream failures
Events waiting for retry

Logs should include identifiers such as the event ID, delivery ID, provider, account ID, and response status.

Avoid writing API keys, signing secrets, access tokens, or unnecessary personal message contents to logs.

A simple production architecture

A reliable webhook pipeline can remain simple:

Webhook delivery

→ Signature verification

→ Event validation

→ Persistent storage

→ Processing queue

→ CRM, support system, AI agent, or notification service

The same structure can be used for payments, source control events, messaging platforms, and many other event-driven integrations.

The difficult part is rarely receiving the first request. The difficult part is making sure every valid event is processed safely, only once, and remains observable when another system fails.

Applying this to messaging platforms

These principles become especially important when receiving customer messages.

A support team may receive messages from Telegram, WhatsApp, LINE, Zalo, TikTok, and X. Each platform has different authentication methods and capabilities, but the receiving system still needs the same security, idempotency, storage, and monitoring boundaries.

At UnifyPort, we are building one API and a standard webhook event layer for these messaging platforms.

You can learn more about the event model and webhook design in the UnifyPort documentation:

https://www.unifyport.ai/docs/