WAHA
Get Started

WhatsApp + ChatWoot - Contacts

October 29, 2025 in ChatWoot, Apps by devlikeapro4 minutes

Image for WhatsApp + ChatWoot - Contacts

Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp, ChatWoot, or any of their respective subsidiaries or affiliates. The official websites can be found at https://whatsapp.com and https://chatwoot.com.

For businesses seeking to integrate with WhatsApp for critical applications, we strongly recommend using officially supported methods.

ChatWoot Articles

Series of articles about WhatsApp and ChatWoot integration using 🧩 ChatWoot App:

You can follow them one by one or skip some parts if you don’t need them.

Overview

By default, when a new message comes from WhatsApp to ChatWoot, it creates a new contact if there isn’t one yet.

ChatWoot contact

Sometimes you want to have all your contacts in ChatWoot right away or pull new customers to run a campaign. This is where wa/contacts commands come in handy!

Contacts Actions

Three actions are available:

  • wa/contacts help prints the full list of options.
  • wa/contacts status shows the latest counters for the running or last finished job.
  • wa/contacts pull starts a new import with default settings.

You can use ‘wa/’ prefix to execute commands in any chats

You can run commands into 2 ways, depending on the conversation you’re in:

  1. WhatsApp Integration chat - use command or wa/command.
  2. Any other conversation in the Inbox - use wa/command only.
# In WhatsApp Integration chat - use either with or without
help
wa/help

# In Any conversation for the Inbox - use wa/ prefix
wa/help

👉 We use the wa/ prefix in the guides, but you can omit it in the WhatsApp Integration chat:

⚙️ Override the prefix by setting the WAHA_CHATWOOT_COMMAND_PREFIX=wa/ environment variable.

Contacts Sync

Use the wa/contacts pull command to sync contacts from WhatsApp to ChatWoot. It copies your WhatsApp contact list into a chosen ChatWoot inbox so agents see fresh names, avatars, and identifiers.

  • It only reads from WhatsApp, so nothing changes on the phone and it pulls contacts rather than syncing them.
  • Each run updates existing profiles in ChatWoot and adds contacts you have not imported yet.

Open the WhatsApp Integration conversation inside ChatWoot (the same thread you use for other WAHA commands).

wa/contacts help

ChatWoot help

Then run a simple contacts pull like this:

wa/contacts pull

ChatWoot replies that the job is queued and processes the contact list in the background.

ChatWoot - contacts pull

One pull per WAHA session

Run a new wa/contacts pull only after the previous job for the same WAHA session has finished. Other sessions can sync their own contacts at the same time, but overlapping pulls within one session cancel each other out.

Check the current status with wa/contacts status.

👇 Check Examples below for common use cases and advanced options.

Use Canned Responses

You can create Canned Responses in ChatWoot with shortcuts for common WAHA commands.

  1. In ChatWoot go to Settings → Canned Responses.
  2. Click Create canned response and set a memorable shortcut like wa-contacts-pull.
  3. Add the command in the body, for example wa/contacts pull --avatar if-missing.
Canned Responses


  1. Start typing /wa in the conversation to see the list of available shortcuts.
Canned Responses Usage

Examples

Refresh contact basics

Keep the defaults and let WAHA import everyone with missing profiles:

wa/contacts pull

Update avatar

Ideal when you want the profile photos in ChatWoot:

wa/contacts pull --avatar

By default, it uses the --avatar if-missing option, so it only pulls avatars for contacts without photos in ChatWoot.

You can update avatars for all contacts by specifying the --avatar update flag:

wa/contacts pull --avatar update

Keep an eye on avatars

Refreshing avatars can trigger some backoff mechanisms on the WhatsApp side, especially if you have many contacts with profile photos.

The --avatar if-missing setting is the safest option to avoid issues.

Include groups and hidden numbers

Bring in WhatsApp groups and LID contacts (users who hide their phone number) in the same run:

wa/contacts pull --groups --lids --avatar

Full options

This command shows every available flag, but use wa/contacts help to explore all latest options.

Adjust the numbers to match your environment:

wa/contacts pull
  --avatar if-missing
  --groups
  --lids
  --no-attributes
  --batch 50
  --progress 50
  --delay-contact 250ms
  --delay-batch 2s
  --attempts 8
  --timeout 15m

Related posts