WhatsApp Contact Notes: Set or Clear a Private Display Name

To set a private custom display name for a WhatsApp contact through UnifyPort, use POST /v1/accounts/{account_id}/contacts/note with contact_id and a string note. To clear it, send note: "" explicitly. This changes an account-side contact note, not the customer’s public profile, a chat message, or an individual support agent’s private CRM alias.

Key takeaways

• The documented action currently supports whatsapp, not every provider or whatsapp-protocol.
• note is required. An empty string means clear; an untouched form should make no request.
• “Visible only to the account” is not a per-agent access-control guarantee inside your shared inbox.
• Keep note writes separate from address-book name synchronization and message sending.

Choose which name you actually want to change

WhatsApp’s contact-management announcement describes contact management across linked-device surfaces. It is background for account-side contact data, not a specification for this UnifyPort operation.

Use the following boundaries when designing an inbox editor:

Intended change	Appropriate layer
A custom contact name for the connected account	UnifyPort contact note
A nickname only one agent should see	Your application’s own alias storage and permissions
Address-book names received from the provider	A separate name-sync projection
Share someone’s details in a chat	A contact-card message

For incoming address-book changes, follow contact.updated name synchronization; that event does not overwrite nicknames and is not a documented confirmation signal for this note write. If the task is saving or sharing a contact instead, use add contact vs send vCard.

A useful UI therefore separates account note from my alias. Do not label both controls “private name” and silently choose where to save them.

Set and clear a WhatsApp contact note

The Set contact note reference defines the method, request, and success response. Check the provider action matrix before showing an enabled save button for a channel.

Prepare a server-side workspace API key and the selected messaging account. Resolve the intended contact under that same account using the contact reference. Preserve identifiers as opaque strings; do not construct them from a display name or assume every operation accepts the same identifier format.

The request body has only these two inputs:

Field	Meaning
contact_id	The contact targeted by this operation
note	Custom display-name text; "" clears the existing note

This JavaScript helper illustrates the documented call. Pass the actual account and contact identifiers selected by your backend, and load the API key from protected configuration. It does not add automatic retries or claim to be a complete inbox application.

async function setContactNote({ apiKey, accountId, contactId, note }) {
  if (typeof note !== 'string') throw new TypeError('note must be a string');
  if (!accountId || !contactId) throw new Error('Select account and contact');

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/contacts/note`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ contact_id: contactId, note })
    }
  );
  const result = await response.json();
  return { httpStatus: response.status, result };
}

For a save, pass the user-approved string. For a clear, call the same helper with an empty string. Do not convert a missing form value into an empty string: that can turn “no edit” into a destructive clear. Reject null locally rather than inventing another clearing convention.

The documented success is 200 OK with data.ok: true. Inspect the result before marking the form saved; completion of fetch alone is not success.

Protect newer edits from older requests

The following are application recommendations, not extra API fields or concurrency guarantees:

1. Scope the editor and queued work by workspace, messaging account, and contact. A matching name is not an identity key.
2. Separate unchanged, edited, and explicitly cleared form states. Ask for confirmation before a clear when appropriate.
3. Serialize writes for the same target in your application. Suppress duplicate clicks and reject stale local jobs before dispatch.
4. Record the requested value, outcome, and request_id under an appropriate retention policy. Never log the API key.
5. If a request times out, show an unknown outcome rather than announcing failure or replaying the old value automatically. Another editor may already have saved a newer note.

Local serialization cannot coordinate every linked client. The public note reference does not document a version precondition, a dedicated note readback field, or a guaranteed note-change webhook. Do not build a confirmation loop around invented fields. Verify the account-side behavior in a controlled test, and retain uncertainty when you cannot observe the result.

The error reference identifies set_contact_note_failed for server-side or upstream failures and unsupported_by_provider for unsupported actions. A capability error is not a reason to retry the same request indefinitely.

Acceptance checks and FAQ

Test setting, replacing, explicitly clearing, leaving a form untouched, rejecting non-string input, two competing edits, an unsupported provider, and a timeout. These are proposed tests, not reported production results.

Is this a private support-ticket note?

No. The reference describes a private contact note as a custom display name. Keep long case histories and sensitive agent commentary in a permission-controlled CRM, not in a display-name field.

Does clearing the note delete the contact?

No. The documented operation clears the note. It is not a contact-deletion or message-deletion action.

Can I use it for LINE, Zalo, or WhatsApp Protocol?

The current action matrix documents this write for whatsapp only. UnifyPort’s unofficial interface has a shared API shape, not identical capabilities across channels.

Should contact.updated mark my note save as confirmed?

No. That event describes address-book name changes, not a guaranteed receipt for setting a custom note.

Next step and sources

Review Set contact note and test one controlled contact before enabling account-side edits in a shared inbox.

References checked on 2026-10-13:

• UnifyPort: Set contact note
• UnifyPort: Provider action support
• UnifyPort: Standard events
• WhatsApp: Making it Easier to Add and Manage Contacts