Skip to main content
stateset-whatsapp is a long-running process that links a WhatsApp account as a device, receives messages, hands them to an iCommerce agent, and sends the agent’s reply back. It is the same pattern as the Discord, Telegram and Slack gateways — only the link step differs.

​
Prerequisites

  • A WhatsApp account you can reach Linked Devices on (the phone stays the primary device; the gateway is a second one).
  • The iCommerce CLI installed and authenticated.
  • A local iCommerce database, passed with --db.

​
Connect WhatsApp and run the gateway

1

Start the gateway

On first run it prints a QR code to the terminal and waits.
2

Link the device

On your phone: WhatsApp → Settings → Linked Devices → Link a device, and scan the code in your terminal.
3

Confirm the credentials were stored

The session is written here, so subsequent runs reconnect without a QR code. Delete this directory to force a re-link — for example when moving the gateway to another machine.

​
Configuration

The gateway reads channel credentials from ~/.stateset/channels.json, shared with the other channel gateways:
Run several channels against one database by starting each gateway separately, or all of the enabled ones at once:

​
Read-only until you say otherwise

By default the gateway answers questions but takes no action that changes data. Write actions — cancelling an order, issuing a refund, editing an address — require --apply:
--apply grants the agent write access to real commerce data, driven by whatever arrives over WhatsApp. Run without it until you have watched the gateway answer real messages for a while, and never enable it on an account that anyone can message.

​
Verify the result

Send a message to the linked WhatsApp account from another phone and confirm the agent replies:
If nothing comes back, the usual causes are, in order: the device link expired (re-run and re-scan), the --db path points at a database with no order data, or the account was messaged from a number the agent has no customer record for.

Messaging channels

The general pattern this gateway is one instance of — routing any channel into an iCommerce agent.

iCommerce agent

What the gateway hands messages to, and how to shape its answers.

CLI workflows

The commands the agent runs when --apply is enabled.

Agent sandbox

Rehearse write actions against a sandbox database before enabling —apply.
Last modified on August 29, 2026