WhatsApp Pin Chat vs Pin Message: Choose the Right API

Pin a WhatsApp chat to keep the conversation easy to find in the chat list. Pin a message to highlight specific content inside that conversation. They are different operations, not two names for the same setting. In an API-backed inbox, select the target first: a conversation needs its conversation ID; a message also needs its own ID and, when it belongs to someone else, its sender ID.

Key takeaways

• Chat pinning organizes the connected account’s chat list; message pinning selects content inside a chat.
• UnifyPort exposes separate routes and different undo operations for the two actions.
• The conversation-pin contract has no duration parameter. The message-pin contract offers duration_seconds.
• A conversation.updated event containing pinned describes chat-list state, not a pinned message.

WhatsApp pin chat vs pin message

WhatsApp’s message-yourself guide describes pinning a chat to the top of the chat list. Its message-pinning guide describes selecting an individual message and a pin duration. These are distinct surfaces even though both use the word “pin.”

Goal	Target	What not to assume
Keep a customer conversation easy to find	Chat-list entry	A particular customer message becomes highlighted
Highlight instructions inside a group	Individual message	The group moves to the top of your inbox
Assign urgent work to an agent	Your application’s ticket or queue	Either provider pin operation creates an owner or deadline

WhatsApp’s message-pinning help also says that pinning in a group produces a system message identifying who pinned the message. Group admins can control whether members may pin messages. Do not present a group message pin as a private agent bookmark. The same help warns that missing history can prevent someone from seeing a pinned message; pinning is not a way to restore unavailable content.

For a personal reminder visible only in your support application, use an application-owned bookmark rather than silently changing provider state. This is a design recommendation, not an additional API feature.

Match the target to the UnifyPort contract

The following contracts belong to UnifyPort’s unofficial interface, not Meta’s Cloud API.

Detail	Pin conversation	Pin message
Method and route	POST /v1/accounts/{account_id}/conversations/pin	POST /v1/messages/pin
Account selection	account_id in the URL	account_id in JSON
Target in JSON	conversation_id	conversation_id, message_id; set sender_id for someone else’s message
State selection	The route requests pinning	pinned: true pins; pinned: false unpins
Duration	No duration parameter	Optional duration_seconds when pinning
Undo	Separate conversation unpin route	Same message route with pinned: false

See the Pin conversation reference, Unpin conversation reference, and Pin / unpin message reference before building the request.

Do not copy a duration option from a native app screen into the conversation API. Equally, do not send a message’s pinned: false body to the conversation-pin route and expect it to undo the action. Follow the contract of the exact operation.

The provider action matrix currently maps conversation pin and unpin to WhatsApp and LINE, but message pinning only to WhatsApp. An unsupported combination returns 501 unsupported_by_provider; a common interface does not imply identical channel capabilities. In particular, a LINE chat-pin button does not justify enabling a LINE message-pin button.

Preserve the selected message, not the latest message

For a message selected from a stored message.received event, the documented mapping is:

• account_id from the event envelope;
• conversation_id from data.conversation.id;
• message_id from data.message.id;
• sender_id from data.sender.id.

The message-pin reference says omitted sender_id defaults to the connected account itself. Set it explicitly for another participant’s message. In a group, the conversation identifies the group and the sender identifies the author; substituting one for the other changes the target context.

Save that selection while an agent considers the action. A new incoming message must not replace the selected message ID. Check that the operator is authorized to act on the selected messaging account and conversation before dispatch.

A quoted message introduces another possible mix-up: its parent ID is not its own ID. The WhatsApp quoted-reply guide explains that relationship. Pinning uses the selected message ID, not a reply_token and not an automatically chosen parent.

Interpret confirmation at the correct level

Both mutation references show a successful result with data.ok: true. Record the requested target and actual response separately from the agent’s click. A timeout leaves the result uncertain; do not display confirmed success or send the opposite action as an automatic correction.

The event reference documents conversation.updated with data.conversation.id and, for a pin-state change, data.pinned. This is local chat-list state for the connected account. It does not identify which message was pinned inside the chat.

Apply only settings present in the event: a mute update that omits pinned should not clear your stored pin state. Treat received changes as observations, not a guarantee that every API action produces a confirmation event. The current public catalogue does not document a dedicated message-pin event, and the provider event matrix does not map conversation.updated to LINE.

If consuming these events, verify signatures and handle duplicate deliveries according to the webhook delivery contract. A webhook update should reconcile the view, not automatically issue the same mutation again.

Keep pins separate from support priority

A hypothetical team may want a chat pinned while a customer waits for an answer. Keep the assigned agent, due time, and resolution status in the application. Removing the pin should not silently resolve the ticket.

The same separation applies to WhatsApp read/unread state and mute versus block: visibility, acknowledgement, notification preferences, and contact restrictions serve different purposes.

Before enabling the controls, test a chat pin, its separate unpin operation, another participant’s group message, an unsupported provider, and a lost HTTP response. These are proposed checks, not reported test results. Use native app controls when a manual workflow is sufficient; evaluate an official integration separately when that is a requirement.

FAQ

Does pinning a chat also pin its latest message?

No. They target different objects and use separate API operations.

Can I use duration_seconds for conversation pinning?

Not in UnifyPort’s documented conversation-pin contract. That field belongs to the message-pin operation.

Does conversation.updated with pinned confirm a message pin?

No. It reports the connected account’s chat-list setting, not an individual message’s pin status.

Can LINE use both pin controls through UnifyPort?

The current matrix supports conversation pin/unpin for LINE, not message pinning. Check each action independently.

Next step and sources

Start with the Pin conversation reference and label your UI controls by their target before enabling them.

Sources checked on 2026-10-08:

• WhatsApp: How to message yourself
• WhatsApp: How to pin a message
• UnifyPort: Pin / unpin message
• UnifyPort: Provider action support