Skip to main content

WhatsApp Personal

WhatsApp Personal lets an agent answer on your own WhatsApp number. You link CatalEx as a device on your phone, the way WhatsApp Web is linked, and the agent reads and replies through it. To use a business number with Meta credentials instead, see Connect WhatsApp.

:::warning Experimental WhatsApp Personal is experimental and available on CatalEx Cloud only. WhatsApp doesn't officially support linking automation tools, and it may temporarily or permanently restrict a number that uses them. :::

Before you begin​

  • An agent with a verified native reply.
  • CatalEx signed in to your CatalEx account on a computer trusted for changes. An untrusted sign-in is refused with CLIENT_NOT_TRUSTED.
  • Your phone, with WhatsApp on the number you want to link.

  1. Open the agent's Add channel (the + on its tile, or Add channel on the Channels tab of its settings page). Choose WhatsApp Personal, then New.

  2. Read the risk notice, select I accept the risks, then choose Continue.

  3. Choose Link WhatsApp. CatalEx shows a QR code. It is replaced by a new one every few seconds while the link runs, and a timer shows how long the current code lasts.

  4. On your phone, open WhatsApp, choose Settings › Linked devices › Link a device, and scan the code. Open WhatsApp's help for linking a device opens WhatsApp's instructions.

    To link without scanning, choose Link with a phone number instead, enter Your phone number with its country code (such as +15551234567), and type the pairing code CatalEx shows into WhatsApp after choosing Link with phone number instead on the phone.

  5. When CatalEx says WhatsApp Personal linked: +NUMBER (NAME), choose who it answers (below), then Done. The agent now has the channel.

If the code expires before you scan it, choose Show a new code. Your phone lists the new device as CatalEx - AGENT.

From the terminal:

catalex channels add --agent AGENT_ID --type whatsapp_personal --new
catalex destinations setup ACCOUNT_ID --whatsapp_personal --action link

Add --value phone=+15551234567 to link for a pairing code instead of a QR code. Expected: Linked +<number> (<name>). If you press Ctrl-C, the command prints how to resume with --operation-id.

Verify a reply​

Your own number is always admitted, so message yourself in WhatsApp ("Message yourself") and check that the agent answers there. The chat also appears under the agent's WhatsApp Personal channel in CatalEx.

Choose who the agent answers​

Under Who can reach your agent, choose:

  • Anyone who messages you: the agent replies to everyone who writes to your number in a direct chat.
  • Only people I choose: pick people and groups. Choose from Recent chats, search your contacts, or add a number such as +15551234567. A prefix such as +44* matches every number starting with those digits. Your own number appears as You.

People who aren't admitted, and anyone you block, get no reply, and their media is never downloaded. Your own number can't be blocked.

From the terminal, list people and groups with the entry to use, then set the lists:

catalex accounts candidates ACCOUNT_ID --search family --limit 10
catalex accounts access set ACCOUNT_ID --allow +15551234567,+44*
catalex accounts access set ACCOUNT_ID --groups group:120363001
catalex accounts access set ACCOUNT_ID --block +15557654321

--allow and --block take people only; groups go in --groups (none clears a list).

Groups​

The agent works in a group only when you allowed that group, and then only when someone mentions (tags) you in it. Other group messages are ignored and not stored. Your own messages in the group don't start work. A tag counts only from WhatsApp's mention list, so typing @name as text doesn't wake the agent.

Each reply in a group quotes the message that tagged you. An approval in a group is decided by a quoted reply or a reaction from the person who tagged you, or by you in the CatalEx app. In the picker, a group shows a Group tag with its size; one you have left shows You're not in this group, and the agent can no longer send to it.

Pause when you reply​

When you write in a contact's chat yourself, the agent stays quiet in that chat for a number of minutes (15 by default). Change it from the terminal, with a whole number from 0 to 1440, or off:

catalex accounts settings show ACCOUNT_ID
catalex accounts settings set ACCOUNT_ID owner_pause_minutes=30
catalex accounts settings set ACCOUNT_ID owner_pause_minutes=off

If the settings changed elsewhere since they were read, nothing is changed (SETTINGS_CHANGED); show them and try again.

  • If you unlink CatalEx on your phone, or another CatalEx account links the same number (the latest link wins), the channel stops. Link it again with catalex destinations setup ACCOUNT_ID --whatsapp_personal --action link. Your access rules, settings and conversations stay.
  • If another session took over the connection (PROVIDER_CONNECTED_ELSEWHERE), take it back with --action reconnect.

Remove the channel​

Select the agent's WhatsApp Personal channel in CatalEx and choose Unlink WhatsApp Personal under the chat list, then confirm. From the terminal, catalex channels remove CHANNEL_ID names the linked number and asks first (default No). Deleting the agent with catalex agents delete does the same.

Removing it stops the agent answering on your number, removes CatalEx from your phone's Linked devices and removes its conversations from CatalEx. Chats on your phone are not touched, and the access list is cleared.

Limits​

  • The agent only answers chats that wrote to it. It can't start a new conversation (DELIVERY_RESTRICTED).
  • Text, images, voice notes, video and documents work in direct chats and allowed groups. Any other file the agent sends goes as a document.
  • CatalEx sends no read receipts, presence or typing indicators.
  • One number belongs to one CatalEx account at a time.
  • Final replies carry no View conversation link.

Codes​

CodeMeaningWhat to do
LINK_TIMEOUTNobody scanned in time.Choose Show a new code, or run --action link again.
LINK_NUMBER_MISMATCHThe scanned number is not this account's.Link the account's own number.
ACCOUNT_ALREADY_BOUNDA WhatsApp business account in CatalEx holds the number.Use another number or remove that account.
PROVIDER_LINK_LOSTThe device was unlinked on the phone.Link again.
PROVIDER_NUMBER_RELINKEDAnother CatalEx account linked this number.Link again to take it back.
PROVIDER_CONNECTED_ELSEWHEREAnother session took over the connection.Run --action reconnect.
PROVIDER_SUSPENDEDWhatsApp temporarily restricted the number.Wait until the time shown.
LINK_CLIENT_OUTDATED, PROVIDER_CLIENT_OUTDATEDWhatsApp refuses the service's client version.Wait for a CatalEx update.
Last updated on