Is your feature request related to a problem?
wa/contacts pull never updates the name of a contact that already exists in ChatWoot.
ContactService.findOrCreateContact (src/apps/chatwoot/client/ContactService.ts) returns early
when the contact is found, so name is only written on creation. The "updated" counter in the
final report counts contacts that already existed, not contacts that actually changed.
This hurts multi-device setups: one ChatWoot account with several WAHA sessions (one per phone).
A contact is usually created by the first session that saw it — often before anyone had saved
the person in the address book — so it lands in ChatWoot as 5531...@c.us or with the push name.
Later, when a colleague saves the person on another phone, running contacts pull in that
session does not fix the name in ChatWoot.
Real numbers from one account (8,235 contacts, 7 sessions): 1,249 contacts are still named by
raw JID/phone, and 443 of them already have a saved name in at least one session's phone book.
Related: #1245 ("Existing contacts are not updated").
Describe the solution you'd like
A new option for contacts pull:
-n, --update-names <mode> choices: if-raw | always
(flag omitted = no name update, current behavior)
if-raw: update name only when the current ChatWoot name is "raw" — empty, equal to the
chat id / JID, a bare phone number, or equal to the push name. Names typed by agents are
never overwritten.always: replace with the phone-book name whenever it differs (opt-in, for accounts that
treat the phone book as the source of truth).
Source of the new name: the same resolution already used on creation
(saved name → push name → id), but under if-raw only a saved (address book) name should
write; push name alone must not overwrite anything.
Implementation sketch: in contacts.pull.ts#pullOneContact, after findOrCreateContact
returns created = false, call a new ContactService.updateNameIfNeeded(contact, contactInfo, mode) that does PATCH /api/v1/accounts/{account}/contacts/{id} with { name } (same client
path used by upsertCustomAttributes), and report a real renamed counter.
Describe alternatives you've considered
An external job that reads GET /api/contacts/all per session and PATCHes ChatWoot. It works
(we are building it), but every WAHA + ChatWoot user with more than one device hits this, and
the pull already has all the data in hand.
Additional context
WAHA Plus 2026.8.2, GOWS engine. Happy to open a PR if the approach is acceptable.
Is your feature request related to a problem?
wa/contacts pullnever updates the name of a contact that already exists in ChatWoot.ContactService.findOrCreateContact(src/apps/chatwoot/client/ContactService.ts) returns earlywhen the contact is found, so
nameis only written on creation. The "updated" counter in thefinal report counts contacts that already existed, not contacts that actually changed.
This hurts multi-device setups: one ChatWoot account with several WAHA sessions (one per phone).
A contact is usually created by the first session that saw it — often before anyone had saved
the person in the address book — so it lands in ChatWoot as
5531...@c.usor with the push name.Later, when a colleague saves the person on another phone, running
contacts pullin thatsession does not fix the name in ChatWoot.
Real numbers from one account (8,235 contacts, 7 sessions): 1,249 contacts are still named by
raw JID/phone, and 443 of them already have a saved name in at least one session's phone book.
Related: #1245 ("Existing contacts are not updated").
Describe the solution you'd like
A new option for
contacts pull:if-raw: updatenameonly when the current ChatWoot name is "raw" — empty, equal to thechat id / JID, a bare phone number, or equal to the push name. Names typed by agents are
never overwritten.
always: replace with the phone-book name whenever it differs (opt-in, for accounts thattreat the phone book as the source of truth).
Source of the new name: the same resolution already used on creation
(
saved name → push name → id), but underif-rawonly a saved (address book) name shouldwrite; push name alone must not overwrite anything.
Implementation sketch: in
contacts.pull.ts#pullOneContact, afterfindOrCreateContactreturns
created = false, call a newContactService.updateNameIfNeeded(contact, contactInfo, mode)that doesPATCH /api/v1/accounts/{account}/contacts/{id}with{ name }(same clientpath used by
upsertCustomAttributes), and report a realrenamedcounter.Describe alternatives you've considered
An external job that reads
GET /api/contacts/allper session and PATCHes ChatWoot. It works(we are building it), but every WAHA + ChatWoot user with more than one device hits this, and
the pull already has all the data in hand.
Additional context
WAHA Plus 2026.8.2, GOWS engine. Happy to open a PR if the approach is acceptable.