Upgrading to SocialMate 3

SocialMate 3 adds the Claude Agent (Pro) and a free WordPress plugin, SocialMate – Messaging & AI Agent. Upgrading keeps your linked numbers, messages, settings, API keys, webhooks and license — the database is migrated on the first start. Pick your setup below.

Desktop app (Windows, macOS, Linux)

• Windows installer and Linux AppImage: the app updates itself. (The portable Windows build and the Linux .deb update by downloading the new version.) When SocialMate 3 is available it shows a download banner and installs the update on the next restart.
• macOS: SocialMate tells you when a new version is out. Download it from the macOS download page and drag it into Applications to replace the old one.

Your numbers stay linked — there is no QR code to scan again.

Docker

Migrations are forward-only, so back up first. Stop the server so the database isn’t copied mid-write, and keep the archive private — it holds the vault key, the database and your WhatsApp sessions. --volumes-from socialmate finds the container’s own data volume whatever it is called, and the archive is saved with mode 600, owned by you:

docker stop socialmate
docker run --rm --volumes-from socialmate -v "$PWD":/backup busybox 
  sh -c "umask 077 && tar czf /backup/sm-data-backup.tgz -C /data . && chown $(id -u):$(id -g) /backup/sm-data-backup.tgz"
docker start socialmate

How to restore it is in Keep your server running. Then pull the new image and recreate the container. Your data lives in the volume, so accounts, messages and your license seat carry over:

docker compose pull && docker compose up -d

Started it with a docker run command instead? Pull, remove the container, and run it again on the same volume — with exactly the flags you used the first time:

docker pull ghcr.io/micbwilliam/socialmate-server:latest
docker rm -f socialmate
# then re-run YOUR original docker run command, every -p and -e flag included, e.g.:
docker run -d --name socialmate --restart unless-stopped -p 3456:3456 -v sm-data:/data ghcr.io/micbwilliam/socialmate-server:latest

A dropped flag is not harmless: without -p 127.0.0.1:3456:3456 plain HTTP is published on every interface again, and without your -e SOCIALMATE_VAULT_KEY=… saved tunnel tokens can’t be read.

The 3.0 image includes ffmpeg (the agent’s voice replies arrive as real voice notes) and is built for amd64 and arm64.

systemd (bare metal)

A 2.0.x install still has the old updater, which cannot install the new service unit or move the server to Node.js 22. Re-run the installer once:

curl -fsSL https://github.com/micbwilliam/socialmate-releases/releases/latest/download/install.sh | sudo bash

It keeps your data, settings and admin password. To add HTTPS on your own domain at the same time, append -s -- --domain <name> (new in 3.0); to keep usage analytics off, append -s -- --no-telemetry. From then on, sudo socialmate-update installs each new release together with its service unit (and keeps the private Node.js 22 copy up to date, if the installer made one). See Install SocialMate without Docker (systemd) and Keep your server running.

The old WordPress plugin (wp-socialmate)

The earlier “SocialMate for WordPress” plugin (wp-socialmate) is replaced by SocialMate – Messaging & AI Agent 1.0.0. The two never share settings or data, so set the new one up fresh:

1. Update SocialMate to 3 first. Messages from the new plugin need SocialMate 2.0.2 or later; the Claude Agent and its approvals need SocialMate 3.
2. In wp-admin, deactivate “SocialMate for WordPress”.
3. Install SocialMate – Messaging & AI Agent and connect it with a new token from API & Integrations → WordPress — see How do I install and connect the WordPress plugin?
4. On the new plugin’s Events tab, choose what each moment sends — your order-update wording does not carry over, so copy it across from the old plugin before you delete it.
5. When a test message arrives, delete the old plugin, and revoke the API key it used in SocialMate.

Messages from the plugin work on every plan, Free included. The agent half needs Pro.

What changes

• New numbers send from minute one. The 2-hour wait before a new number’s first message is gone. Replies to someone who wrote to you first, and messages to your own number, never count toward warming. Messages to people who have not written first still ramp up over 3 days: 20 in the first 6 hours, 20 more in the rest of day 0, 50 on day 1 and 100 on day 2, then your plan’s normal limits. Group messages always count. See Warming new numbers.
• Usage analytics are on by default for new installs. They are pseudonymous — identified by a one-way hash of your device ID (the one licensing uses, so it can be linked to your trial or license), never your messages, phone numbers, contacts or API keys. An upgrade keeps the choice you made before; an install that finished setup without choosing stays off. Switch them off any time in Settings → Privacy & data (on a server, in /admin, or set SOCIALMATE_TELEMETRY=0).
• The Claude Agent is new under Agents (Pro). Start in Observe mode (it only drafts) or Copilot (every action waits for your approval) until you trust it — see How do I set up the Claude Agent?
• A setup checklist on the Dashboard lists what is left for what you said you want, and ticks each step from what is really done.

What stays the same

• Your plan, your price and your license key. Free stays free.
• The per-minute, hourly and daily limits for each plan, pacing, quiet hours and risk cooling — they apply to every message, as before.
• Your data stays on your machine or server. Nothing about your chats is sent to us.
• The local API, webhooks, the n8n node and the MCP server keep working; SocialMate 3 adds the agent endpoints and agent.* events on top.

Everything that changed is in the changelog and on What’s new in SocialMate 3.