DEV Community: UnifyPort

Media Send Accepted but Not Delivered? A URL-First Debugging Guide

unifyport — Fri, 09 Oct 2026 06:02:18 +0000

Sending media through an API looks simple:

Choose a file
Build JSON
POST the request

In production, failures usually happen across several separate boundaries:

Media source
    ↓
Request validation
    ↓
Account readiness
    ↓
Provider acceptance
    ↓
Delivery
    ↓
Read receipt

A file opening in your browser does not prove that a remote sender can retrieve it. An API response with status: accepted does not prove that the recipient received it. A timed-out request does not prove that nothing happened.

This guide shows how to build and troubleshoot URL-based media sends with UnifyPort without unsafe retries or incorrect delivery claims.

Start with the sending contract

UnifyPort sends media through:

POST /v1/messages

Supported media message types include:

image
video
audio
document
file

Provider support still varies. A shared endpoint does not mean every connected channel supports every media type.

A URL-based image request looks like this:

{
  "account_id": "acc_8c21d0",
  "to": {
    "id": "conversation_42",
    "type": "user"
  },
  "message": {
    "type": "image",
    "url": "https://media.example.com/orders/order-42.jpg",
    "caption": "Your order is ready"
  }
}

The media source can use a documented field such as:

message.url
message.file_url
message.file_key

Do not provide conflicting source fields unless the API explicitly documents their precedence. Start with one source and keep the request unambiguous.

A local filename is not a media URL

This is not remotely accessible:

{
  "message": {
    "type": "image",
    "url": "/Users/alice/Desktop/photo.jpg"
  }
}

Neither is this:

{
  "message": {
    "type": "image",
    "url": "./uploads/photo.jpg"
  }
}

Those paths only have meaning on your machine or application server.

A remote media sender needs an absolute HTTP or HTTPS URL:

{
  "message": {
    "type": "image",
    "url": "https://media.example.com/uploads/photo.jpg"
  }
}

A data: URL is not a substitute for a documented remote media source.

If the file begins locally, first place it in an approved storage system and obtain a controlled URL.

“Works in my browser” is not enough

A browser may successfully open a URL because it has:

login cookies;
a cached session;
VPN access;
internal DNS;
a previously completed redirect;
credentials stored by an extension.

The sender retrieving the media does not inherit your browser session.

For example:

https://app.example.com/download/invoice-42

may return the PDF for your authenticated browser but return an HTML login page to an unauthenticated client.

Before sending, test the URL from a separate trusted environment without browser cookies.

Inspect:

the final HTTP status;
redirect behavior;
Content-Type;
response size;
whether the response contains media bytes or HTML;
URL expiration;
DNS and network accessibility.

Do not perform unrestricted server-side fetches against arbitrary user-provided URLs. Use approved storage origins or a carefully designed allowlist to avoid introducing an SSRF vulnerability.

Use controlled media storage

A production media source should have:

HTTPS;
a known storage origin;
a predictable content type;
sufficient URL validity;
narrowly scoped access;
no credentials embedded in the URL authority;
logs that redact sensitive query strings.

Signed URLs are useful, but their expiration must account for asynchronous retrieval.

A URL that works during request construction may expire while the message waits in a queue.

There is no universal fetch deadline that applies to every provider and delivery path. Choose an expiration window that matches your own queueing and delivery expectations, then monitor failures.

Build a minimal request

A small JavaScript helper can validate the application-controlled fields:

function buildMediaRequest({
  accountId,
  conversation,
  type,
  url,
  caption,
}) {
  const mediaTypes = new Set([
    "image",
    "video",
    "audio",
    "document",
    "file",
  ]);

  if (!accountId) {
    throw new Error("accountId is required");
  }

  if (!conversation?.id || !conversation?.type) {
    throw new Error("conversation id and type are required");
  }

  if (!mediaTypes.has(type)) {
    throw new Error(`Unsupported media type: ${type}`);
  }

  const source = new URL(url);

  if (!["http:", "https:"].includes(source.protocol)) {
    throw new Error("Media source must use HTTP or HTTPS");
  }

  if (source.username || source.password) {
    throw new Error("Do not embed credentials in the media URL");
  }

  const message = {
    type,
    url: source.href,
  };

  if (caption !== undefined) {
    if (type === "audio") {
      throw new Error("Caption is not valid for this audio request");
    }

    if (typeof caption !== "string") {
      throw new Error("caption must be a string");
    }

    message.caption = caption;
  }

  return {
    account_id: accountId,
    to: {
      id: conversation.id,
      type: conversation.type,
    },
    message,
  };
}

This helper validates syntax. It does not prove that:

the URL is remotely reachable;
the bytes are valid media;
the account is connected;
the provider supports the type;
the recipient will receive the message.

Those require separate checks.

Send from the server

Keep the API key out of browser code:

async function sendMedia(requestBody) {
  const response = await fetch(
    "https://api.unifyport.ai/v1/messages",
    {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.UNIFYPORT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(requestBody),
    },
  );

  const body = await response.json();

  if (!response.ok) {
    throw new Error(
      `${response.status} ${
        body.error?.code ?? "unknown_error"
      }`,
    );
  }

  return body;
}

Do not log the API key, signed media URL, or unnecessary recipient data.

Do not copy inbound attachments into outbound requests

Inbound media and outbound media use different contracts.

An inbound event may contain fields such as:

{
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/temporary-download",
      "mimetype": "image/jpeg"
    }
  ]
}

That object is not automatically a valid outbound message.

The locator may also be temporary or provider-specific.

Build a new outbound request using the documented send fields:

{
  "message": {
    "type": "image",
    "url": "https://approved-storage.example.com/image.jpg"
  }
}

If an inbound locator expired, recover the file through the provider’s documented download flow, place it in approved storage, and then construct the outbound request.

Check provider support before showing the control

Do not let users select a media type that the connected provider cannot send.

Your application should evaluate:

provider
account mode
message type
current capability matrix

A conceptual capability check might look like:

function canSendMedia({
  provider,
  type,
  capabilities,
}) {
  return capabilities[provider]?.send?.includes(type) === true;
}

If a provider returns:

unsupported_message_type

do not retry the unchanged request.

Disable the control or offer a supported fallback.

A unified API reduces integration differences, but it does not erase provider capabilities.

Check account readiness separately

Authorization does not always mean the messaging runtime is ready.

Before enabling automated sends, distinguish:

Account exists
Account is authorized
Runtime is connected
Provider supports the action
Recipient is valid

An error such as:

provider_not_ready

should trigger account-state diagnosis, not immediate reauthorization or blind retries.

Inspect the account’s authentication and runtime state, then decide whether the connection needs recovery.

Accepted is not delivered

An accepted response means the API accepted the request for processing.

It does not mean:

The provider delivered the file
The recipient received the file
The recipient opened the file

Track distinct states:

created
submitted
accepted
delivered
read
failed
unknown

For example:

const outboundOperation = {
  operationId: "send_order_42_image_1",
  state: "accepted",
  messageId: "msg_3003",
  requestId: "req_91c4",
  deliveredAt: null,
  readAt: null,
};

Only supported delivery evidence should advance the record to delivered or read.

Not every provider emits every receipt. Missing confirmation should remain unknown, not automatically become failed.

Timeouts create uncertain outcomes

A request timeout does not prove that the provider rejected the message.

This is unsafe:

try {
  await sendMedia(request);
} catch {
  await sendMedia(request);
}

The first request may have succeeded after your client stopped waiting. The retry can produce a duplicate message.

Instead, persist an outbound operation before sending:

const operation = await createOutboundOperation({
  accountId,
  conversationId,
  mediaUrlReference: "order-42-image",
  state: "submitting",
});

Then record the result:

try {
  const response = await sendMedia(requestBody);

  await markAccepted(operation.id, {
    messageId: response.data?.message_id,
  });
} catch (error) {
  if (isDefinitiveRejection(error)) {
    await markFailed(operation.id, error);
  } else {
    await markOutcomeUnknown(operation.id, error);
  }
}

An unknown result needs reconciliation or operator review. It should not automatically trigger another irreversible send.

Keep diagnostic IDs for support

Save the returned message identifier and request_id when available.

They help correlate:

client logs;
API responses;
provider processing;
support investigations;
webhook receipts.

A request_id is a tracing identifier, not an idempotency token.

Do not reuse it as proof that two send attempts are the same business operation.

Your own stable operation ID should represent intent:

send-media:order-42:customer-copy:1

Debug the failing boundary

Use the observed result to choose the next check.

Observation	Next check
Local path or relative URL	Move the file to reachable HTTP(S) storage
URL works only while logged in	Remove session dependency and inspect actual response bytes
URL has expired	Generate a new approved source with sufficient validity
`unsupported_message_type`	Provider capability and selected media type
`provider_not_ready`	Authentication and runtime status
Request rejected with validation error	Request schema and required fields
Request times out	Preserve the uncertain operation; do not blindly resend
Response says `accepted`	Store identifiers and wait for supported delivery evidence
Delivery receipt never arrives	Provider receipt support, webhook health and unknown-state policy

Branch on machine-readable error codes instead of parsing human-readable error messages.

Test one variable at a time

Begin with the smallest possible test:

One connected account
One known conversation
One supported media type
One small file
One approved HTTPS URL
No optional provider metadata

Avoid combining:

a new account connection;
an expiring URL;
an unsupported media type;
a group conversation;
optional duration metadata;
an automated retry system.

If the request fails, changing several variables at once destroys the evidence needed to identify the boundary.

Suggested acceptance tests

Before production, test:

[ ] A small reachable HTTPS image.
[ ] A URL that returns an HTML login page.
[ ] An expired signed URL.
[ ] A redirect to an inaccessible origin.
[ ] An unsupported provider/type combination.
[ ] A disconnected account.
[ ] A request-validation failure.
[ ] An accepted request with delayed delivery evidence.
[ ] A lost or timed-out client response.
[ ] Duplicate webhook receipts.
[ ] Out-of-order delivery events.
[ ] A repeated send job after worker restart.
[ ] Redaction of signed URLs and credentials in logs.

The goal is not only to prove the happy path. It is to prove that an uncertain result does not create duplicate customer messages.

A production state machine

A useful outbound state model is:

draft
  ↓
submitting
  ├── accepted
  │      ├── delivered
  │      │      └── read
  │      ├── failed
  │      └── unknown
  ├── failed
  └── unknown

Transitions should come from evidence:

Transition	Evidence
`draft → submitting`	Worker claims the operation
`submitting → accepted`	Successful API response
`submitting → failed`	Definitive API rejection
`submitting → unknown`	Timeout or lost response
`accepted → delivered`	Supported delivery event
`accepted → failed`	Supported failure evidence
`delivered → read`	Supported read evidence

This prevents the UI from presenting “delivered” immediately after request acceptance.

Optional metadata should remain optional

Some providers support additional media metadata.

For example, WhatsApp audio and video requests may accept duration information through:

{
  "provider_data": {
    "seconds": 12
  }
}

Do not copy an inbound millisecond value directly into a field expressed in seconds.

Also do not invent optional metadata when it is not required.

If the provider can process the media without it, omitting uncertain metadata is safer than sending a guessed value.

Takeaway

Reliable media sending requires more than valid JSON.

Trace the complete path:

Supported media type
        ↓
Reachable approved URL
        ↓
Valid request
        ↓
Ready account
        ↓
Accepted operation
        ↓
Provider delivery evidence

Remember:

A local path is not a URL.
A browser session is not remote accessibility.
Accepted is not delivered.
A timeout is not a confirmed failure.
A request ID is not an idempotency key.

Start with one explicit media source, store the outbound operation before sending, and keep uncertain outcomes separate from retries.

References

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

WhatsApp October 2026 Pricing: Build a Cost Model Before You Migrate

unifyport — Mon, 28 Sep 2026 10:24:32 +0000

WhatsApp pricing changes on October 1, 2026.

For teams using the official WhatsApp Business Platform, ordinary customer-service replies will no longer always have a zero Meta message charge.

The first 1,000 delivered Service messages per business phone number each month remain free. Deliveries after that allowance use the Service rate for the recipient’s market.

That sounds like a simple formula:

Service charge
  = (messages − 1,000)
  × market rate

In practice, a useful cost model must also account for:

multiple business phone numbers;
recipients in several markets;
message categories;
free entry-point traffic;
provider fees;
support software;
AI usage;
account-based subscription alternatives.

This article builds that model and compares it with UnifyPort’s messaging-account subscription structure without treating the two products as equivalent.

What changes on October 1, 2026?

Meta’s updated pricing documentation describes a new charge for Service messages delivered through the official WhatsApp Business Platform.

Message or situation	From October 1, 2026
Incoming customer message	No Meta message charge
Service reply within the 24-hour window	First 1,000 per business number each month are free; later deliveries use the recipient-market rate
Utility template inside the 24-hour window	Charged under Utility rules
Eligible 72-hour free entry-point window	Message-delivery exception remains
Meta Business Agent usage	Separate token-based pricing model

The 24-hour customer-service window is still a sending restriction.

It does not mean every message inside that window belongs to the same billing category.

An ordinary Service reply, Utility template and eligible free-entry-point message must be classified separately.

The allowance belongs to each phone number

The 1,000-message monthly allowance applies to each business phone number.

It is not one shared workspace allowance.

Suppose a business operates two numbers:

Number A: 1,600 delivered Service messages
Number B: 0 delivered Service messages

The billable quantity is:

Number A: 1,600 − 1,000 = 600
Number B: 0

You cannot transfer Number B’s unused allowance to Number A.

Compare that with:

Number A: 800 delivered Service messages
Number B: 800 delivered Service messages

Both numbers remain within their individual allowances, so the Meta Service charge is zero.

The distribution of traffic matters—not only the total volume.

The allowance is also shared across recipient markets

A single business number may send Service messages to customers in several markets.

Do not subtract 1,000 separately from every market.

Incorrect:

Brazil deliveries − 1,000
Germany deliveries − 1,000
United Kingdom deliveries − 1,000

Correct:

First 1,000 Service deliveries for the number are free
Later deliveries use the rate for each recipient’s market

This means an accurate implementation should retain:

business phone number;
delivery timestamp;
recipient market;
delivered message category;
free-entry-point status;
billing eligibility.

Aggregating only by market can apply the allowance incorrectly.

October Service rates used in this example

The following USD rates come from the October 1, 2026 rate card cited by Meta’s pricing documentation.

Recipient market	Service rate per delivered message
India	$0.0014
North America	$0.0034
Brazil	$0.0068
Singapore	$0.0160
United Kingdom	$0.0220
Germany	$0.0550

For one phone number sending only one-to-one Service messages to one market:

Monthly Service charge
  = max(delivered Service messages − 1,000, 0)
  × recipient-market rate

The estimated charges are:

Recipient market	10,000 deliveries	100,000 deliveries
India	$12.60	$138.60
North America	$30.60	$336.60
Brazil	$61.20	$673.20
Singapore	$144.00	$1,584.00
United Kingdom	$198.00	$2,178.00
Germany	$495.00	$5,445.00

These are estimates, not measured customer bills.

They assume:

one business number;
one recipient market;
one-to-one Service messages;
no eligible free-entry-point traffic;
no other message categories;
an unchanged rate for the entire month.

They exclude provider fees, support software, AI, staffing, taxes and currency conversion.

A two-number Brazil example

Assume a support team operates two WhatsApp numbers.

Each number delivers 10,000 ordinary Service replies to customers in Brazil during one month.

The free allowance is deducted separately:

Billable messages per number
  = 10,000 − 1,000
  = 9,000

The monthly charge for both numbers is:

2 × 9,000 × $0.0068
  = $122.40

At 100,000 replies per number:

2 × 99,000 × $0.0068
  = $1,346.40

At 800 replies per number:

Both numbers remain below 1,000
Meta Service charge = $0

The low-volume row is important.

If every number stays inside its allowance, avoiding Service charges alone is not a reason to migrate to another integration.

Model delivered messages, not API requests

A successful send request is not necessarily a delivered, billable message.

Your cost pipeline should distinguish:

Request accepted
Message sent
Message delivered
Message failed
Message classified
Message billed

Do not estimate charges by counting HTTP 200 responses from the send endpoint.

Use delivery and billing evidence from the platform or provider.

A simplified record might look like this:

const delivery = {
  businessNumberId: "number_br_01",
  recipientMarket: "BR",
  category: "service",
  deliveredAt: "2026-10-12T08:31:04Z",
  freeEntryPoint: false,
  deliveryStatus: "delivered",
};

Keep the original classification inputs so the calculation can be audited later.

An illustrative calculator

For a single number, process Service deliveries in chronological order.

The first 1,000 eligible deliveries consume the monthly allowance. Later deliveries use their market rates.

const serviceRatesUsd = {
  IN: 0.0014,
  NORTH_AMERICA: 0.0034,
  BR: 0.0068,
  SG: 0.016,
  GB: 0.022,
  DE: 0.055,
};

function calculateNumberServiceCharge(deliveries) {
  const eligible = deliveries
    .filter((delivery) => {
      return (
        delivery.status === "delivered" &&
        delivery.category === "service" &&
        delivery.freeEntryPoint !== true
      );
    })
    .sort((a, b) => {
      return new Date(a.deliveredAt) - new Date(b.deliveredAt);
    });

  let remainingAllowance = 1000;
  let totalUsd = 0;

  for (const delivery of eligible) {
    if (remainingAllowance > 0) {
      remainingAllowance -= 1;
      continue;
    }

    const rate = serviceRatesUsd[delivery.recipientMarket];

    if (rate === undefined) {
      throw new Error(
        `Missing rate for market: ${delivery.recipientMarket}`,
      );
    }

    totalUsd += rate;
  }

  return totalUsd;
}

This is an explanatory example, not production billing code.

A real billing system should:

avoid binary floating-point arithmetic for money;
use versioned rate cards;
preserve the billing timezone and period;
support corrected delivery classifications;
distinguish every applicable message category;
reconcile estimates against actual billing exports.

Store rates as versioned data

Do not hardcode one permanent price table into business logic.

Rates can change.

A versioned model could include:

const rateCard = {
  currency: "USD",
  effectiveFrom: "2026-10-01",
  effectiveTo: null,
  category: "service",
  rates: {
    IN: "0.0014",
    NORTH_AMERICA: "0.0034",
    BR: "0.0068",
    SG: "0.0160",
    GB: "0.0220",
    DE: "0.0550",
  },
};

When calculating October traffic, select the rate card effective on the delivery date.

This also makes later audits reproducible after pricing changes again.

Compare the correct cost components

The official API and UnifyPort use different commercial models.

Official WhatsApp Business Platform

Costs may include:

Meta message charges;
integration engineering;
webhook and delivery monitoring;
support inbox software;
provider or BSP charges;
seats;
AI usage;
operations;
taxes.

UnifyPort

UnifyPort uses monthly messaging-account subscriptions rather than Meta’s Service-message rate card for traffic sent through its unofficial interface.

Its current graduated pricing includes one messaging account per workspace, followed by paid account bands:

Paid account positions	Monthly price per account
1–5	$10.00
6–10	$8.00
11–200	$5.00
201–1,000	$4.50
1,001 onward	$4.00

The pricing is graduated.

For ten paid accounts:

First 5 × $10 = $50
Next 5 × $8 = $40
Total = $90/month

Reaching the second band does not reprice all ten accounts at $8.

Together with the included account, ten paid accounts provide eleven messaging accounts in the workspace.

Why the comparison is not apples to apples

Meta Service charges and UnifyPort subscriptions represent different line items.

The official example measures:

Delivered Service messages
× recipient-market rates

The UnifyPort example measures:

Connected paid messaging accounts
× graduated subscription prices

They do not provide identical authorization, capabilities or guarantees.

For the two-number Brazil example:

Meta Service estimate:
$122.40/month

UnifyPort account subscription estimate:
1 included account
+ 1 paid account × $10
= $10/month

The difference between those listed charges is:

$122.40 − $10
= $112.40/month

That is not proof of a $112.40 reduction in total operating cost.

The calculation excludes:

implementation;
monitoring;
staff;
support software;
AI;
taxes;
throughput requirements;
failure handling;
account continuity;
provider-specific capabilities.

Use the difference as one input to a broader architecture decision.

Capability differences matter

Evaluate the official path when your product depends on:

official templates;
Meta-native workflows;
official authorization;
formal Business Platform capabilities;
provider or BSP support;
contractual requirements.

Evaluate an account-based interface when your priority is:

connecting an existing operational account;
ordinary-account messaging;
multi-platform intake;
one API and webhook model across channels;
account-based subscription pricing.

An unofficial interface is not a drop-in equivalent to the official Cloud API.

Include access changes, account restrictions, reauthorization and continuity in any production trial.

A lower estimated message-related charge is not useful if the alternative cannot support a required workflow.

Low-volume and high-volume teams reach different conclusions

Low-volume example

Two numbers each send 800 Service replies:

Meta Service charge: $0
UnifyPort subscription estimate: $10/month

The official message charge is lower in this narrow comparison.

Higher-volume example

Two Brazil numbers each send 10,000 Service replies:

Meta Service charge: $122.40
UnifyPort subscription estimate: $10/month

The account subscription is lower than the selected Meta line item, but capability and operational differences still need evaluation.

Distribution example

One number sends 1,600 replies and the second sends none:

Billable messages: 600
Charge: 600 × $0.0068 = $4.08

If the same 1,600 replies are evenly split:

Number A: 800
Number B: 800
Charge: $0

The account topology changes the result even when total traffic is identical.

AI creates another cost layer

An AI support workflow can include:

Model or agent usage
+ message-delivery charges
+ orchestration
+ retrieval
+ human escalation

Do not assume that changing the messaging integration makes third-party AI free.

For a useful AI cost model, measure:

model tokens per conversation;
replies required to resolve an issue;
tool calls;
retrieval cost;
human handoff rate;
message-delivery category;
delivery success rate.

Optimize for resolved customer issues, not merely the cost of one generated reply.

Build a pre-October worksheet

Export one representative month and group records by:

Business phone number
Recipient market
Delivery timestamp
Delivered message category
Free-entry-point eligibility
Delivery status
Provider

Then calculate:

The 1,000-message allowance independently for each number.
Recipient-market rates after each number exhausts its allowance.
Utility and other categories separately.
Free-entry-point exceptions separately.
Provider, software, AI and operational fees.
Account-subscription alternatives by paid account position.
Capability gaps and migration costs.

A final comparison should resemble:

Cost or requirement	Official API	Account-based alternative
Service message charges	Calculated from delivered traffic	Not the same billing model
Messaging account subscription	Provider-specific	Graduated account pricing
Support inbox	Add if required	Add if required
AI	Add if required	Add if required
Engineering	Estimate	Estimate
Monitoring	Estimate	Estimate
Official templates	Supported according to official product	Verify before considering migration
Account continuity risk	Evaluate	Evaluate
Cross-channel normalization	Build or buy	Evaluate available provider support

Takeaway

The October 2026 WhatsApp pricing change should not trigger an automatic migration.

It should trigger a better cost model.

Calculate using:

Delivered messages
Business phone number
Recipient market
Message category
Free-entry-point status
Current rate card

Then compare the complete operating model—not one message charge against one subscription fee.

For low-volume numbers, the official Service charge may remain zero.

For higher-volume numbers, recipient-market rates can become material.

In every case, capability, authorization, reliability and operational ownership belong in the same decision as price.

Sources

Pricing figures were checked on September 28, 2026. Recheck the official documentation and your applicable agreement before making a production or purchasing decision.

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

Telegram Inline Button Keeps Loading? Fix answerCallbackQuery Correctly

unifyport — Tue, 22 Sep 2026 09:48:12 +0000

A user presses an inline button in your Telegram bot.

The callback reaches your webhook. Your server returns HTTP 200. The business action may even complete successfully.

But the button keeps showing a loading indicator.

The missing step is usually:

answerCallbackQuery

Telegram treats these as three separate outcomes:

Outcome	How it is confirmed
Telegram delivered the update	Your webhook returns a successful HTTP response
Your bot acknowledged the button press	Your bot calls `answerCallbackQuery`
The requested business operation completed	Your application commits and records the result

Returning HTTP 200 acknowledges webhook delivery. It does not answer the callback query.

Callback buttons are not text messages

Consider this inline keyboard:

{
  "inline_keyboard": [
    [
      {
        "text": "Approve",
        "callback_data": "approval:approve:request_42"
      },
      {
        "text": "Reject",
        "callback_data": "approval:reject:request_42"
      }
    ]
  ]
}

When the user presses one of these buttons, Telegram does not send an ordinary text message.

It sends an update containing callback_query:

{
  "update_id": 710000001,
  "callback_query": {
    "id": "4382bfdwdsb323b2d9",
    "from": {
      "id": 123456789,
      "is_bot": false,
      "first_name": "Jordan"
    },
    "message": {
      "message_id": 815,
      "chat": {
        "id": -1001234567890,
        "type": "supergroup"
      },
      "text": "Approve request #42?"
    },
    "data": "approval:approve:request_42"
  }
}

A handler that only checks update.message will ignore this interaction:

if (!update.message) {
  return;
}

Instead, dispatch callbacks explicitly:

if (update.callback_query) {
  await handleCallbackQuery(update.callback_query);
  return;
}

if (update.message) {
  await handleMessage(update.message);
}

Use the correct identifier

The callback answer requires:

callback_query_id

Its value comes from:

update.callback_query.id

Do not substitute:

update_id;
message_id;
chat.id;
inline_message_id;
callback_query.data.

The correct mapping is:

Incoming field	Purpose
`callback_query.id`	Pass as `callback_query_id`
`callback_query.data`	Application input associated with the button
`callback_query.from`	User who pressed the button
`callback_query.message`	Message context, when present
`callback_query.inline_message_id`	Inline-mode message context, when present

A wrong ID can leave the client waiting even though your webhook completed successfully.

Call `answerCallbackQuery`

The Bot API request looks like this:

curl -X POST \
  "https://api.telegram.org/bot$BOT_TOKEN/answerCallbackQuery" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_query_id": "4382bfdwdsb323b2d9"
  }'

The text field is optional.

You do not need to show a notification merely to clear the progress indicator.

A small JavaScript helper can make the request:

async function answerCallbackQuery({
  callbackQueryId,
  text,
  showAlert = false,
}) {
  const payload = {
    callback_query_id: callbackQueryId,
    show_alert: showAlert,
  };

  if (text) {
    payload.text = text;
  }

  const response = await fetch(
    `https://api.telegram.org/bot${process.env.BOT_TOKEN}/answerCallbackQuery`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    },
  );

  const result = await response.json();

  if (!response.ok || result.ok !== true) {
    throw new Error(
      `answerCallbackQuery failed: ${response.status} ${
        result.description ?? "unknown error"
      }`,
    );
  }

  return result;
}

Keep BOT_TOKEN on the server. Never include it in browser code, source control, logs, screenshots, or support tickets.

Answer promptly

Do not wait for a slow business operation before answering the interaction.

This is fragile:

async function handleCallbackQuery(query) {
  await callCrm(query.data);
  await runAiClassification(query.data);
  await updateDatabase(query.data);

  await answerCallbackQuery({
    callbackQueryId: query.id,
  });
}

If the CRM or AI request is slow, the Telegram client continues displaying progress while the user waits.

Answer the interaction first, then perform the work:

async function handleCallbackQuery(query) {
  await answerCallbackQuery({
    callbackQueryId: query.id,
  });

  await enqueueCallbackAction({
    callbackQueryId: query.id,
    userId: query.from.id,
    data: query.data,
    messageId: query.message?.message_id ?? null,
    chatId: query.message?.chat?.id ?? null,
    inlineMessageId: query.inline_message_id ?? null,
  });
}

This acknowledges the button press without pretending the underlying operation already succeeded.

Button feedback is not business success

Suppose the button approves a refund.

Calling answerCallbackQuery means:

The bot acknowledged the button press.

It does not mean:

The refund was approved and committed.

Keep interaction state and business state separate:

Callback received
    ↓
Callback answered
    ↓
Request validated
    ↓
Authorization checked
    ↓
Business transition committed
    ↓
Message updated with the final result

A user-facing flow might be:

Clear the Telegram loading indicator immediately.
Validate the callback payload.
Confirm that the user is authorized.
Perform the state transition idempotently.
Edit the message or send a new message with the real outcome.

For example:

async function processApprovalAction(job) {
  const action = parseCallbackData(job.data);

  await assertAuthorized({
    userId: job.userId,
    action: action.type,
    resourceId: action.resourceId,
  });

  const result = await applyActionIdempotently({
    action: action.type,
    resourceId: action.resourceId,
    actorId: job.userId,
    idempotencyKey: `telegram:${job.callbackQueryId}`,
  });

  await publishFinalResult({
    chatId: job.chatId,
    messageId: job.messageId,
    result,
  });
}

Do not display “Approved” merely because the callback was received.

Treat `callback_data` as untrusted input

A callback came from Telegram, but its contents should still be validated against current server-side state.

Do not write logic like this:

const [action, resourceId] = query.data.split(":");
await database.update(resourceId, { status: action });

Validate the format and allowlist the action:

function parseCallbackData(data) {
  if (typeof data !== "string") {
    throw new Error("Missing callback data");
  }

  const [namespace, action, resourceId] = data.split(":");

  if (namespace !== "approval") {
    throw new Error("Unsupported callback namespace");
  }

  if (!["approve", "reject"].includes(action)) {
    throw new Error("Unsupported callback action");
  }

  if (!/^request_[a-zA-Z0-9]+$/.test(resourceId)) {
    throw new Error("Invalid resource identifier");
  }

  return {
    type: action,
    resourceId,
  };
}

Then check:

whether the user may perform the action;
whether the object still exists;
whether it is still in an actionable state;
whether the action was already completed;
whether the button belongs to the expected bot workflow.

The originating message may be old, edited, forwarded, or no longer representative of the current server-side state.

Do not require `callback_query.message`

A callback query does not always have ordinary message context.

Depending on how the inline button was created, the callback may provide:

callback_query.message

or:

callback_query.inline_message_id

This code can crash before answering the callback:

const chatId = query.message.chat.id;
const messageId = query.message.message_id;

await answerCallbackQuery({
  callbackQueryId: query.id,
});

Use optional context:

const context = {
  chatId: query.message?.chat?.id ?? null,
  messageId: query.message?.message_id ?? null,
  inlineMessageId: query.inline_message_id ?? null,
};

await answerCallbackQuery({
  callbackQueryId: query.id,
});

Answering the callback only requires the callback query ID. Do not let missing message context block that acknowledgment.

Check `allowed_updates`

If the callback never reaches your handler, inspect the receiver configuration.

Telegram’s allowed_updates parameter must permit:

callback_query

For example, a webhook configuration may include:

{
  "allowed_updates": [
    "message",
    "callback_query"
  ]
}

A configuration that only permits message can deliver ordinary messages while excluding callback queries.

This creates a misleading symptom:

Bot receives messages correctly
Inline buttons keep loading
No callback handler logs appear

The receiving transport may be healthy while the update filter excludes the interaction type.

Telegram documents that omitting allowed_updates can retain the previous setting. Do not assume leaving it out resets the receiver to every update type.

Review the effective configuration used by the active webhook or polling worker.

Separate missing delivery from missing handling

Use this diagnostic sequence.

Case 1: no callback update reaches the receiver

Check:

allowed_updates;
webhook delivery status;
the currently configured webhook URL;
whether the polling worker requests callback updates;
whether the button actually uses callback_data.

A URL button does not produce a callback query. It opens its configured URL.

Case 2: the callback arrives but the loading indicator remains

Check:

whether answerCallbackQuery was called;
whether callback_query.id was used;
whether the Bot API response returned success;
whether the handler crashed before the answer call;
whether a slow dependency blocked the call.

Case 3: the loading indicator clears but nothing happens

Check:

callback-data parsing;
user authorization;
current server-side state;
queue processing;
failed business transitions;
final message updates.

Case 4: the action happens more than once

Check:

duplicate update delivery;
repeated user clicks;
queue retries;
missing business idempotency;
multiple consumers processing the same job.

These are different failure boundaries and should not be fixed with the same retry.

Webhook HTTP `200` is not enough

This webhook handler is incomplete:

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

  await saveUpdate(update);

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

It tells Telegram:

The update was delivered successfully.

It does not tell the Telegram client:

The button interaction was acknowledged.

A more complete structure is:

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

  const inserted = await saveUpdateIfAbsent(update);

  res.status(200).end();

  if (!inserted) {
    return;
  }

  if (update.callback_query) {
    await handleCallbackQuery(update.callback_query);
    return;
  }

  if (update.message) {
    await handleMessage(update.message);
  }
});

In production, ensure errors after the HTTP response are captured by your worker or job system rather than becoming unobserved promise rejections.

Deduplicate delivery and business actions separately

Telegram update retries and repeated button presses are different duplication problems.

Delivery-level idempotency

Use update_id to prevent processing the same update twice:

async function saveUpdateIfAbsent(update) {
  return database.telegramUpdates.insertIfAbsent({
    updateId: update.update_id,
    payload: update,
    receivedAt: new Date(),
  });
}

Interaction-level tracking

Record the callback query:

await database.callbackQueries.insertIfAbsent({
  callbackQueryId: query.id,
  userId: query.from.id,
  data: query.data,
  receivedAt: new Date(),
});

Business-level idempotency

Protect the irreversible operation independently:

const idempotencyKey =
  `approval:${action.resourceId}:${action.type}`;

This prevents two different callback queries from approving the same request twice.

A unique update does not necessarily represent a unique business action.

Decide what feedback the user should see

answerCallbackQuery supports optional text.

An empty answer is appropriate when the message will immediately update:

await answerCallbackQuery({
  callbackQueryId: query.id,
});

Short feedback can confirm receipt:

await answerCallbackQuery({
  callbackQueryId: query.id,
  text: "Processing…",
});

An alert may be appropriate for an important validation error:

await answerCallbackQuery({
  callbackQueryId: query.id,
  text: "You are not allowed to approve this request.",
  showAlert: true,
});

Do not use callback notifications as the permanent record of a business result. Update the conversation with a durable final state.

For example:

Request approved by Jordan at 14:32 UTC

A production-oriented handler

The complete flow can be organized like this:

async function handleCallbackQuery(query) {
  const callbackQueryId = query.id;

  try {
    await answerCallbackQuery({
      callbackQueryId,
    });
  } catch (error) {
    logger.error("callback_answer_failed", {
      callbackQueryId,
      error: error.message,
    });

    throw error;
  }

  let action;

  try {
    action = parseCallbackData(query.data);
  } catch (error) {
    logger.warn("invalid_callback_data", {
      callbackQueryId,
      userId: query.from.id,
    });

    return;
  }

  await enqueueCallbackAction({
    callbackQueryId,
    action,
    userId: query.from.id,
    chatId: query.message?.chat?.id ?? null,
    messageId: query.message?.message_id ?? null,
    inlineMessageId: query.inline_message_id ?? null,
  });
}

This handler deliberately separates:

Telegram interaction acknowledgment.
Input parsing.
Durable business processing.

Acceptance tests

Before release, test all of these cases:

[ ] A valid callback clears the progress indicator.
[ ] An empty callback answer works without notification text.
[ ] Optional text displays when requested.
[ ] A slow CRM or AI task does not delay the callback answer.
[ ] callback_query.id is passed as callback_query_id.
[ ] A callback without message does not crash the handler.
[ ] Inline-message context is handled when present.
[ ] Unknown callback data does not execute an action.
[ ] Unauthorized users cannot perform protected actions.
[ ] A stale button cannot overwrite current server state.
[ ] Repeated update delivery does not duplicate processing.
[ ] Repeated clicks do not repeat an irreversible operation.
[ ] Final business success or failure is shown separately.
[ ] Bot tokens are absent from logs.

Bot callbacks and account-level webhooks are different

Telegram inline keyboards and answerCallbackQuery belong to the official Telegram Bot API.

An account-level normalized webhook solves a different problem.

UnifyPort’s documented event contract includes events such as:

message.received

It does not document a Telegram callback_query event or an answerCallbackQuery operation.

Do not rename a normalized message event into a callback query, and do not assume that returning Telegram Bot API JSON from an unrelated webhook receiver will execute the bot method.

If your system needs both architectures, keep them separate:

Telegram Bot API
    → Inline keyboard callbacks
    → answerCallbackQuery
    → Bot-specific business logic

Connected account webhook
    → message.received
    → Multi-channel support intake

Share downstream services where appropriate, but preserve the different authentication, event and response contracts.

Takeaway

When a Telegram inline button keeps loading, trace one click through these boundaries:

Button uses callback_data
        ↓
callback_query reaches the receiver
        ↓
Handler reads callback_query.id
        ↓
Bot calls answerCallbackQuery
        ↓
Telegram returns success
        ↓
Business action runs separately

Remember:

HTTP 200 acknowledges webhook delivery.
answerCallbackQuery acknowledges the button press.
Your database confirms the business result.

Keeping those outcomes separate produces faster interactions, safer retries and much clearer debugging.

References

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

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

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

Your Telegram bot receives private messages without a problem.

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

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

Those changes may be unnecessary.

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

The important distinction is:

Group-message visibility and update delivery are separate layers.

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

Diagnose the layers independently.

Start with the observed behavior

Different symptoms point to different parts of the system.

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

Treat these as diagnostic hypotheses rather than guaranteed conclusions.

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

What Privacy Mode controls

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

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

For example:

/help@support_example_bot

An ordinary group message such as:

Has anyone received their order?

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

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

A successful private-message test therefore proves only that:

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

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

Visibility and delivery are different layers

Think of the system as a pipeline:

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

A failure at each layer looks different.

Visibility failure

Telegram never exposes the ordinary group message to the bot.

Changing webhook code does not fix this.

Delivery failure

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

Privacy settings do not fix this.

Application-filtering failure

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

Changing the bot’s permissions does not fix this.

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

Step 1: confirm the bot identity

A surprisingly common cause is deploying the wrong bot token.

Use getMe from a trusted environment:

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

Do not paste the bot token into:

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

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

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

Check `can_read_all_group_messages`

The getMe response may include:

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

The relevant field is:

can_read_all_group_messages

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

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

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

Step 2: run a controlled group test

Use a dedicated test group with informed participants.

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

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

Example test messages:

Private chat:
privacy-test-private-001

Group:
 /status@support_example_bot

Reply to bot:
privacy-test-reply-001

Ordinary group text:
privacy-test-group-001

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

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

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

Step 3: inspect the raw receiver

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

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

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

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

  await storeUpdateIfAbsent(update);

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

Do not log the bot token or unnecessary message content.

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

Inspect:

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

Step 4: audit application filters

A handler may accidentally accept only private chats:

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

Or it may accept only commands:

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

A more explicit router makes the boundary easier to inspect:

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

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

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

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

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

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

Step 5: check `allowed_updates`

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

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

message

A conceptual configuration looks like this:

{
  "allowed_updates": [
    "message"
  ]
}

Privacy Mode and allowed_updates solve different problems:

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

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

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

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

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

Audit the configuration used by the currently active receiver.

Step 6: verify the receiving mode

Telegram Bot API supports two mutually exclusive receiving modes:

getUpdates
setWebhook

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

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

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

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

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

Diagnose transport separately using a controlled migration runbook.

Step 7: choose the minimum required access

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

A command-driven bot may need only:

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

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

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

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

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

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

Do not promote the bot to administrator just for testing

Administrator status carries permissions and responsibilities beyond receiving messages.

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

Do not combine all these changes in one experiment:

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

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

Change one layer at a time:

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

This preserves causal evidence.

Disabling Privacy Mode safely

If ordinary group conversation is required:

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

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

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

Build an acceptance-test matrix

Record results instead of relying on memory.

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

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

Preserve updates idempotently

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

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

  if (!inserted) {
    return false;
  }

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

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

Business operations may need their own idempotency keys:

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

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

A compact diagnostic function

You can turn the troubleshooting logic into an internal checklist:

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

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

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

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

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

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

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

Bot identity versus account-based intake

This guide concerns Telegram Bot API bots.

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

An account-based intake system solves a different problem:

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

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

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

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

Choose based on the required identity:

Users should talk to a bot
    → Telegram Bot API

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

Production checklist

Before declaring the issue fixed, verify:

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

Takeaway

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

Diagnose the pipeline in order:

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

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

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

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

References

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

Telegram getUpdates vs setWebhook: A Safe Migration Runbook

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

Your Telegram bot worked yesterday.

After a deployment, one of these things happens:

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

The underlying rule is simple:

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

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

A safe migration therefore requires four things:

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

This runbook covers both migration directions.

The two receiving modes

Telegram bots can receive updates through polling or webhooks.

Long polling with `getUpdates`

Your application repeatedly asks Telegram for new updates:

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

Example:

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

Polling is often convenient for:

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

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

Push delivery with `setWebhook`

Telegram sends each update to your HTTPS endpoint:

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

Example:

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

Webhooks are often a better fit for:

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

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

Why the conflict happens

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

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

This creates a confusing operational state:

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

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

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

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

First step: inspect the active mode

Before changing a deployment flag, call getWebhookInfo:

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

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

The most important field for this diagnosis is url.

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

Do not guess the active mode from:

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

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

Diagnose common symptoms

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

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

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

Migration rule: one receiver owns the bot

Before switching, define one owner for the bot:

telegram-receiver-mode = polling

or:

telegram-receiver-mode = webhook

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

A useful deployment invariant is:

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

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

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

Switching from webhook to `getUpdates`

Use this direction when returning to polling.

Step 1: pause downstream changes

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

Examples include:

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

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

Step 2: inspect the webhook

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

Confirm which URL is configured before deleting it.

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

Step 3: choose the pending-update policy

Remove the webhook using deleteWebhook:

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

The critical parameter is:

drop_pending_updates

Use false when pending messages still matter.

Use true only when the backlog can be discarded deliberately.

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

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

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

Step 4: verify webhook removal

Call getWebhookInfo again:

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

Confirm that the webhook url is empty.

Do this before starting the polling worker.

Step 5: start exactly one polling worker

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

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

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

Step 6: advance the offset

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

A simplified worker looks like this:

let offset = 0;

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

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

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

    const body = await response.json();

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

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

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

Store update IDs and processing state durably.

Switching from `getUpdates` to `setWebhook`

Use this direction when moving from polling to push delivery.

Step 1: stop the polling worker

Stop or scale down the polling deployment first.

Confirm that:

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

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

Step 2: finish or checkpoint current work

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

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

Step 3: deploy the webhook endpoint

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

A minimal Express receiver might look like this:

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

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

  res.status(200).end();

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

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

The reliable pattern is:

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

Step 4: configure the webhook

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

Use a production HTTPS endpoint controlled by your team.

Do not point a production bot at:

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

Step 5: verify the configured URL

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

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

This catches:

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

Step 6: send a controlled test message

Send one identifiable test message to the bot.

Verify the entire path:

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

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

Handle pending updates deliberately

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

Before switching, decide:

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

Document the decision in the deployment record:

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

Never record the bot token in the deployment record.

Make both modes idempotent

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

A conceptual database table could be:

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

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

A handler can then claim stored work atomically:

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

  if (!inserted) {
    return;
  }

  await enqueueUpdate(update.update_id);
}

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

Avoid duplicate side effects

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

Examples include:

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

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

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

A migration checklist

Before switching

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

Webhook to polling

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

Polling to webhook

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

When the Bot API is the right model

Use Telegram’s official Bot API when:

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

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

When a unified inbound webhook fits better

The Bot API runbook solves delivery for one Telegram bot.

It does not:

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

If your actual requirement is:

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

then a normalized inbound webhook may be a cleaner architecture.

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

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

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

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

These are different product models, not interchangeable transport settings.

Takeaway

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

What does getWebhookInfo say?

Then follow a controlled migration:

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

Never treat getUpdates and setWebhook as parallel delivery layers.

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

References

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

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

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

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

It is not.

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

Which TikTok identity and operating model are you building around?

There are two different integration paths:

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

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

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

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

The short version

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

A useful starting rule is:

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

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

Start with the identity

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

Start with identity instead.

Ask:

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

The answers determine which integration model fits.

What the official Business Messaging API is for

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

Its documentation includes capabilities related to:

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

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

Examples include:

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

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

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

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

What a QR-authenticated inbox is for

A QR-authenticated inbox begins with a different requirement:

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

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

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

The account is created with:

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

Authentication then starts through:

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

The client checks progress through:

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

or:

GET /v1/accounts/{account_id}/auth

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

That should not automatically be treated as an error.

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

Model QR authentication as a state machine

Avoid implementing QR authentication as:

const response = await startQrAuthentication();

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

That implementation incorrectly treats delayed QR material as failure.

Use an explicit state model instead:

idle
  ↓
starting
  ↓
waiting_for_qr
  ↓
qr_available
  ↓
waiting_for_scan
  ↓
authenticated

The flow may also terminate in:

expired
failed
cancelled

A polling loop can distinguish these outcomes:

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

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

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

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

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

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

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

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

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

The architecture difference

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

TikTok-specific business integration

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

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

Normalized multi-channel intake

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

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

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

Store inbound events before routing them

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

For example:

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

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

Use this order:

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

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

Verify the signed raw body

Webhook verification must happen before the event is trusted.

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

The signed input is constructed from:

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

The signature uses HMAC-SHA256.

A simplified Express route should preserve the raw request body:

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

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

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

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

    await storeEventIfAbsent(event);

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

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

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

Make event storage idempotent

Webhook providers may retry delivery.

Use the event’s id as a unique key:

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

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

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

After storage, enqueue a separate routing job.

Normalize intake without hiding provider differences

A shared event contract makes common routing easier:

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

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

  await assignToQueue(message);
}

Common logic can handle:

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

Provider-specific behavior should remain explicit:

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

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

  default:
    await applyDefaultPolicy(message);
}

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

Compare the operational responsibilities

The API surface is only part of the decision.

You also need to compare what your team will operate.

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

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

Choose the official Business Messaging API when

Prefer TikTok’s official integration when:

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

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

Choose a QR-authenticated inbox when

Consider the QR path when:

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

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

Do not confuse related TikTok APIs

TikTok exposes several integration surfaces that may sound similar.

Examples include:

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

They should not be treated as interchangeable.

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

Before choosing an endpoint, identify:

Account type
Product surface
Message source
Required operations
Region
Review requirements

Decision checklist

Before implementing either path, answer these questions:

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

Takeaway

Do not select a TikTok DM integration by asking only:

Which endpoint lets me receive messages?

Ask:

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

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

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

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

References

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

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

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

A WhatsApp group join request arrives.

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

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

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

The safer architecture is:

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

The key principle is:

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

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

What WhatsApp still controls

WhatsApp group approval remains a group-admin feature.

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

Your backend does not replace this permission model.

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

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

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

The three API operations

A reliable approval queue uses three separate operations.

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

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

Instead:

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

Example webhook event

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

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

Useful fields include:

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

Store the event ID so webhook retries remain idempotent.

Verify before trusting the event

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

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

A simplified Express route might look like this:

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

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

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

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

    await handleJoinRequestSignal(event);

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

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

Make the receiver fast and idempotent

The webhook handler should not wait for a moderator decision.

Its job is to:

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

For example:

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

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

    if (!inserted) {
      return;
    }

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

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

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

Do not use an in-memory queue in production

A Map or array is useful for a local example:

const pending = new Map();

It is not a reliable production queue.

The state disappears when:

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

Use durable infrastructure such as:

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

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

Fetch the current pending list

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

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

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

A Node.js worker can build the request safely:

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

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

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

  return response.json();
}

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

Persist requesters before reviewing them

The list response is the reliable source for pending requests.

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

account_id + group_id + member_id

A minimal record could contain:

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

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

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

Reconcile with upserts

A worker can upsert every currently pending request:

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

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

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

Be careful with requests missing from a later list.

Their absence might mean they were:

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

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

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

Design the moderator workflow

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

Useful fields include:

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

A simple state machine could be:

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

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

For example:

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

Continue only if exactly one record was updated.

Approve or reject exact requester IDs

To approve a requester:

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

To reject the request, change the action:

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

The value in member_ids must come from the list endpoint.

Do not substitute:

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

Wrap the decision in a service

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

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

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

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

  return response.json();
}

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

After success, save an audit record:

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

Never store the API key in the audit record.

Reconcile after the decision

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

Your local queue should still reconcile the group afterward:

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

await enqueueReconciliation({
  accountId,
  groupId,
});

The next list operation confirms which requests remain pending.

This catches situations where:

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

Webhook plus periodic polling

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

A practical strategy is:

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

The polling interval depends on:

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

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

Keep policy outside the transport layer

The webhook receiver should not contain business rules such as:

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

Transport code should verify, store, and enqueue.

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

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

For example:

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

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

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

Failure scenarios to plan for

Duplicate webhooks

Use the webhook event ID as an idempotency key.

Missed webhooks

Run periodic list reconciliation.

Multiple events for one group

Deduplicate queued work using account_id + group_id.

Two moderators act simultaneously

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

Request disappears before review

Refresh the list and mark the local record no_longer_pending.

Worker crashes after the API request

Reconcile the list before retrying the external action.

Unauthorized account

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

Security and privacy checklist

Before deploying the queue, confirm that:

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

Takeaway

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

Build the approval queue around this sequence:

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

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

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

References

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

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

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

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

Then the requirements grow:

Confirm
Cancel
Change address
Contact support

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

The real question is:

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

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

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

The short answer

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

A useful rule is:

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

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

What a confirm template is designed to do

A confirm template presents text followed by exactly two actions.

Typical examples include:

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

A simplified request looks like this:

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

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

A confirm card asks one focused question:

Do you want to proceed?

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

Use a buttons template for three or four actions

A buttons template is a separate LINE template type.

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

View order
Track delivery
Change address
Contact support

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

It is a good fit when:

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

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

Use quick replies for temporary menus

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

For example:

Where should we route your request?

Billing
Delivery
Returns
Technical support
Sales
Other

LINE supports up to 13 quick reply buttons.

That makes quick replies appropriate for:

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

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

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

If an option needs to remain available, consider:

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

Use a carousel for repeated objects

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

Examples include:

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

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

Product A
Image
Price
View
Buy

Product B
Image
Price
View
Buy

Product C
Image
Price
View
Buy

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

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

Use Flex Messages for custom hierarchy

A Flex Message is the most adaptable option.

Use it when the interaction depends on:

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

For example, an order confirmation might need to display:

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

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

The trade-off is complexity.

Flex Messages require:

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

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

A practical decision function

You can model the initial choice in application code:

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

  if (representsRepeatedItems) {
    return "carousel";
  }

  if (needsCustomLayout) {
    return "flex";
  }

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

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

  return "redesignRequired";
}

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

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

A complete decision tree

Ask these questions in order.

1. Is this one binary decision?

Examples:

Yes / No
Accept / Decline
Confirm / Cancel

Use a confirm template.

2. Are there three or four primary actions?

Use a buttons template.

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

3. Are there several temporary next steps?

Use quick replies.

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

4. Is the user comparing repeated objects?

Use a carousel.

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

5. Does the experience need a custom visual hierarchy?

Use a Flex Message.

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

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

That is a separate architectural concern.

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

Separate outbound presentation from inbound handling

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

A clean architecture separates them:

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

This matters for multi-channel systems.

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

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

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

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

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

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

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

  await routeInboundMessage(message);
}

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

Common design mistakes

Forcing a third action into a confirm flow

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

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

Using quick replies for permanent navigation

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

Using Flex for every message

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

Treating all channels as visually identical

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

Keep provider capabilities explicit.

Combining outbound UI and inbound routing decisions

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

Design those layers separately.

Implementation checklist

Before selecting a LINE message surface, confirm that:

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

Takeaway

Do not choose a LINE message component by asking:

How can I fit all these actions into one template?

Ask:

What kind of decision is the user making?

Use:

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

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

References

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

Building Reliable WhatsApp Read/Unread Sync for a Shared Inbox

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

A shared inbox receives a new WhatsApp message.

Should the conversation immediately become “read”?

Usually, no.

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

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

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

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

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

Three meanings of “read”

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

1. Local queue state

This is the workflow state stored by your application:

new
assigned
waiting
resolved

Your database should also know:

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

This is your support system’s source of truth.

2. WhatsApp conversation state

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

read
unread

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

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

3. Message read receipts

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

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

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

Define an explicit synchronization policy

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

That policy can make an unattended queue look healthy.

Instead, connect provider state to meaningful team actions:

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

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

Mark a WhatsApp conversation as read

To mark an entire conversation as read, call:

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

Pass the provider conversation identifier in the JSON body:

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

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

Mark through a specific message

For a message-level WhatsApp receipt, include both:

up_to_message_id
up_to_message_sender_id

Example:

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

These two fields form a pair.

Sending only one of them returns:

400 invalid_request

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

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

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

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

Build a small read-state helper

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

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

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

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

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

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

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

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

  return response.json();
}

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

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

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

Mark a conversation unread

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

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

Using the same helper:

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

The unread action only requires conversation_id.

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

For example:

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

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

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

Avoid synchronization feedback loops

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

A naive implementation can produce a loop:

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

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

A safer workflow is:

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

An operation record could contain:

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

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

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

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

Store webhook events idempotently

Webhook delivery can be retried.

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

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

  if (existing) {
    return;
  }

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

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

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

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

Keep local state authoritative

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

The provider does not know:

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

A practical local model might look like this:

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

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

Handle unsupported providers correctly

Read and unread conversation actions are currently supported for WhatsApp.

An unsupported provider/action combination returns:

501 unsupported_by_provider

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

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

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

If the provider is unsupported:

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

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

Implementation checklist

Before enabling read/unread synchronization, confirm that:

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

Takeaway

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

Keep these concepts separate:

Local queue state
Provider conversation state
Message receipt state

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

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

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

References

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

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

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

API key rotation sounds like a single operation:

Old key → Rotate → New key

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

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

With the UnifyPort API, calling:

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

invalidates the old key immediately.

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

For zero-downtime rotation, use a controlled overlap:

Create → Store → Test → Deploy → Verify → Deactivate

The two rotation strategies

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

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

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

401 invalid_api_key

A safer mental model

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

The application moves through four states:

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

State 2 is the overlap window that protects availability.

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

Step 1: Inventory every API caller

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

Typical callers include:

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

Do not confuse an API key with a webhook signing_secret.

They protect different directions of communication:

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

Rotating one does not rotate the other.

You can inspect existing API key records with:

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

The response includes metadata such as:

id
name
key_prefix
status

It does not return the complete secret.

Step 2: Create a second active key

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

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

A successful 201 response returns:

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

The full value is returned only once.

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

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

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

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

Step 3: Test the new key before deployment

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

Use a read-only endpoint:

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

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

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

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

Step 4: Roll out and verify every caller

Update each caller in controlled batches.

For example:

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

For each group, verify:

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

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

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

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

A simple internal checklist might look like this:

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

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

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

Step 5: Deactivate the old key

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

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

The documented API key states are:

active
inactive

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

401 invalid_api_key

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

Finally, remove the retired secret from:

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

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

When immediate rotation is the right choice

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

Examples include:

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

The incident-response sequence is different:

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

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

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

The trade-off of overlapping keys

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

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

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

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

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

Rotation checklist

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

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

Takeaway

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

Always check the endpoint’s actual contract.

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

For an ordinary rolling deployment, the safer sequence is:

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

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

References

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

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

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

Two Similar Requests, Two Different Operations

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

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

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

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

Quick Decision Table

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

The key distinction is state versus content:

Add contact
    -> changes account state

Send vCard
    -> sends conversation content

Option 1: Add a Contact to the Connected Account

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

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

The request must contain at least one of:

phone_number
username

WhatsApp-specific fields belong inside whatsapp_options:

first_name
full_name
sync_to_device_contacts

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

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

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

See the complete Add contact API reference.

Option 2: Send a vCard in a Conversation

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

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

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

The following fields are optional:

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

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

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

See the complete Send contact message API reference.

Why These Calls Should Remain Separate

Consider a customer-support handoff:

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

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

Step 1: Add customer
Result: Address-book mutation

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

Store the two results independently.

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

This separation becomes especially important during retries.

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

Model the Workflow Explicitly

A simple TypeScript workflow could look like this:

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

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

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

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

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

  result.sentMessageId = message.message_id;

  return result;
}

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

Handle Errors by Operation

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

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

A practical error-handling structure is:

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

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

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

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

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

Design a Cross-Provider Fallback

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

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

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

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

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

Keep Personal Data Minimal

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

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

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

Implementation Checklist

Before shipping, verify that:

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

Final Takeaway

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

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

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

Originally published on UnifyPort.

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

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

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

Receiving a webhook is easy.

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

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

First, Understand the Scope

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

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

Before implementation, confirm that:

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

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

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

Recommended Architecture

A reliable implementation separates webhook acknowledgement from business processing:

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

The webhook request should not wait for:

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

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

Subscribe to the New Message Event

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

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

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

Useful fields from the payload include:

tts_notification_id
shop_id
message_id
conversation_id
index
create_time
type
visibility
Sender information

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

Verify the Signature Before Parsing

TikTok Shop sends the webhook signature in the Authorization header.

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

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

The important word here is raw.

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

A Node.js implementation can look like this:

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

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

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

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

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

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

Use constant-time comparison and never log app_secret.

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

import express from "express";

const app = express();

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

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

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

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

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

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

Acknowledge Within Three Seconds

TikTok Shop requires a successful webhook response to:

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

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

That creates a strict boundary:

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

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

Make Every Delivery Idempotent

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

Use tts_notification_id as the first idempotency key:

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

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

These keys protect different stages:

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

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

Do Not Trust Arrival Order

Network delivery order is not guaranteed.

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

A simplified worker check might look like this:

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

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

Reconcile Missing Messages Through History

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

Use:

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

The Get Conversation Messages documentation specifies that:

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

Trigger reconciliation when:

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

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

Keep Routing Separate from Authentication

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

Maintain an explicit mapping:

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

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

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

Track Authorization as Its Own Lifecycle

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

Treat these as different failure domains:

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

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

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

Monitor the Pipeline, Not Just the Endpoint

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

Useful production metrics include:

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

Logs should include safe correlation fields such as:

tts_notification_id
shop_id
conversation_id
message_id
Worker job ID
Internal tenant ID

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

Common Failure Modes

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

Production Acceptance Test

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

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

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

Final Checklist

Before going live, verify that:

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

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

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

Originally published on UnifyPort.

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

DEV Community: UnifyPort

Media Send Accepted but Not Delivered? A URL-First Debugging Guide

Start with the sending contract

A local filename is not a media URL

“Works in my browser” is not enough

Use controlled media storage

Build a minimal request

Send from the server

Do not copy inbound attachments into outbound requests

Check provider support before showing the control

Check account readiness separately

Accepted is not delivered

Timeouts create uncertain outcomes

Keep diagnostic IDs for support

Debug the failing boundary

Test one variable at a time

Suggested acceptance tests

A production state machine

Optional metadata should remain optional

Takeaway

References

WhatsApp October 2026 Pricing: Build a Cost Model Before You Migrate

What changes on October 1, 2026?

The allowance belongs to each phone number

The allowance is also shared across recipient markets

October Service rates used in this example

A two-number Brazil example

Model delivered messages, not API requests

An illustrative calculator

Store rates as versioned data

Compare the correct cost components

Official WhatsApp Business Platform

UnifyPort

Why the comparison is not apples to apples

Capability differences matter

Low-volume and high-volume teams reach different conclusions

Low-volume example

Higher-volume example

Distribution example

AI creates another cost layer

Build a pre-October worksheet

Takeaway

Sources

Telegram Inline Button Keeps Loading? Fix answerCallbackQuery Correctly

Callback buttons are not text messages

Use the correct identifier

Call answerCallbackQuery

Answer promptly

Button feedback is not business success

Treat callback_data as untrusted input

Do not require callback_query.message

Check allowed_updates

Separate missing delivery from missing handling

Case 1: no callback update reaches the receiver

Case 2: the callback arrives but the loading indicator remains

Case 3: the loading indicator clears but nothing happens

Case 4: the action happens more than once

Webhook HTTP 200 is not enough

Deduplicate delivery and business actions separately

Delivery-level idempotency

Interaction-level tracking

Business-level idempotency

Decide what feedback the user should see

A production-oriented handler

Acceptance tests

Bot callbacks and account-level webhooks are different

Takeaway

References

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

Start with the observed behavior

What Privacy Mode controls

Visibility and delivery are different layers

Visibility failure

Delivery failure

Application-filtering failure

Step 1: confirm the bot identity

Check can_read_all_group_messages

Step 2: run a controlled group test

Step 3: inspect the raw receiver

Step 4: audit application filters

Call `answerCallbackQuery`

Treat `callback_data` as untrusted input

Do not require `callback_query.message`

Check `allowed_updates`

Webhook HTTP `200` is not enough

Check `can_read_all_group_messages`

Step 5: check `allowed_updates`

Long polling with `getUpdates`

Push delivery with `setWebhook`

Switching from webhook to `getUpdates`

Switching from `getUpdates` to `setWebhook`