WhatsApp

Drive your CAD from WhatsApp with your own Twilio number — just for you, or one company number on your organisation server — or, just for you, your own phone paired by QR code.

WhatsApp: you use your own Twilio number. Each message is passed through SphereHarness, unchanged, to your PC (or your organisation’s server) and is never stored. Your Twilio auth token never leaves your PC or your organisation’s server, and we keep no phone number. Privacy policy, section 11.

Which one? See WhatsApp and Telegram: two modes. The channel setup dialog (status window → Company channels → WhatsApp → Set up…, or ask the chat “set up WhatsApp”) asks “Who is this for?” first. The relay needs the desktop agent version 1.3.5 or later.

How Twilio reaches you: one permanent SphereHarness address

The agent gives each Twilio number one permanent web address, https://sphereharness.io/api/whatsapp/relay/<id> (the id is random and names neither you nor the number). You set it once in Twilio as When a message comes in (method POST). When Twilio calls it, the SphereHarness server answers Twilio at once and hands the request over — unchanged, with Twilio’s X-Twilio-Signature — to your PC or your organisation server, over the connection that PC or server opened to SphereHarness. Your PC or server checks the signature with your auth token, runs the request and answers Twilio directly. No tunnel, no public address and no open port anywhere on your side.

  • Rotate gives the number a new address at once; the old one stops working the same moment. Write the new one into Twilio (the agent does it for a registered number).
  • Disconnect ends the address; Twilio then gets 404 and nothing is delivered.
  • Your PC is not connected: SphereHarness answers Twilio with one fixed sentence, which Twilio sends from your number: “Your SphereHarness PC NAME is not connected right now. Start the SphereHarness agent there and send your message again.” For a company number whose organisation server is not connected: “Your organisation’s SphereHarness server is not connected right now. Please try again later.” These are the only words SphereHarness ever sends on your number (Twilio may charge for them as for any message).
  • Pictures in an answer: your PC or server places the picture in the SphereHarness server’s memory for at most one hour behind an unguessable link, and Twilio fetches it from there. Never written to disk.

Twilio: sandbox or a registered sender

Sandbox (to try)Registered WhatsApp sender (real use)
NumberOne shared Twilio number (+14155238886)Your own number on a WhatsApp Business Account
Before useEach phone sends join <code>; the join expires after 3 days (send it again)Meta business verification — several weeks, by region
The relay address in TwilioPasted by hand: Twilio Console → Messaging → Try it out → Send a WhatsApp message → Sandbox settings (the dialog’s Copy)Written by the agent or the organisation server through the Twilio API (Write it to my Twilio number)
MessagesOur replies always fall inside WhatsApp's 24-hour window after the person's message, so no template is needed; a message the business starts outside that window must be a pre-approved template
CostUS$0.005 per message in or out + Meta's conversation fee (by category and country)

From the Twilio Console home you need the Account SID (AC…, 34 characters) and the Auth token — the token goes only into the dialog's password box, never into the chat, and never to SphereHarness.

The company number on your organisation server Tenant admin

Twilio calls the company number’s SphereHarness relay address; SphereHarness hands each request, unchanged, to your organisation server over a connection the server opens out to SphereHarness. The organisation server checks Twilio’s X-Twilio-Signature with the company auth token, reads the sender’s number, finds the PC that person paired, and keeps the message until that PC collects it over the connection it already has (no inbound port on any PC). The auth token exists once, on the organisation server, encrypted. SphereHarness never has it and keeps no phone number.

Administrator: once

  1. In the dialog choose Organisation - one bot for everyone, run on our organisation server (the administrator signs in first in Settings → Organisation → Sign in as administrator; saving is a licensed write under the Tenant Admin licence), then sandbox or sender.
  2. Account SID, the company WhatsApp number (E.164), the auth token in the password box — sent once to the organisation server over HTTPS and stored there encrypted. On a plain-http server the dialog shows the line to run on the server instead: install-organisation-server.ps1 -TwilioAuthToken (typed hidden).
  3. The relay address: the dialog gets the company number’s permanent SphereHarness address and gives the organisation server the token it connects with (over HTTPS, or install-organisation-server.ps1 -SphereHarnessRelayToken on a plain-http server). A registered number gets the address written by the organisation server; for the sandbox, paste it into When a message comes in (POST).
  4. Save. The checklist ends “Members: nothing to install - each PC pairs once from Settings → Organisation”.

Each person: pair once

  1. Sandbox only: send join <code> to the sandbox number (again every 3 days).
  2. Settings → Organisation → Company channels shows “Send ABC123 to +number on WhatsApp” (6 characters, 15 minutes, 5 tries).
  3. Send just the code. The reply: “Connected: your messages now reach PcName.”

Before you pair: “Open Settings → Organisation on your SphereHarness PC and send me the code shown there.” Your PC off: “Your PC NAME is not reachable right now (last seen when). Start SphereHarness on it and send your message again.” (sent by the organisation server from the company number). Licence expired: the reply names the expired licence; your pairing is kept.

Just me: your own WhatsApp on your own PC

The dialog asks “Your own phone by QR code, or your own Twilio account?”

Your own Twilio account

  1. Account SID, the auth token (password box; stored encrypted for your Windows user, never sent to SphereHarness), the Twilio WhatsApp number (the sandbox number pre-filled), and your own WhatsApp number — the only allowed sender.
  2. Your webhook URL: the dialog shows your permanent SphereHarness relay address with Copy, Write it to my Twilio number (a registered number), Rotate and Disconnect.
  3. Sandbox: send join <code> from your phone first, then paste the address into Sandbox settings → When a message comes in (POST). Open the WhatsApp sandbox opens that page of the Twilio Console, console.twilio.com … /try-it-out/whatsapp-learn; Twilio’s guide is twilio.com/docs/whatsapp/sandbox.

Every request must carry a valid X-Twilio-Signature for your relay address, checked on your PC with your token, or it is refused. With several PCs signed in as you, the request goes to your preferred PC, else the one that answered last, else the newest.

Your own phone by QR code

The agent pairs your number like WhatsApp Web (Linked devices → Link a device → scan the QR code). Free, no address, and nothing passes through SphereHarness — but not an official WhatsApp integration and against WhatsApp's automation terms, so use it for yourself only. Allowed senders: your own number (empty refuses everyone). Status window → My channels (this PC) → WhatsApp → Connect (QR); the first time it downloads a small Node.js runtime.

If your company runs a company number, you may still choose Just me unless the administrator switched that off; one binding per channel per PC.

Replies

Plain text in 1,500-character parts. Through Twilio a screenshot comes as a one-hour link; the QR path sends text only.

One conversation with your PC (1.3.7): a message from you — the account holder (with your own Twilio account or QR pairing, the number set as Account holder (you); with the company number, the person paired to this PC) — continues the conversation in the SphereHarness chat on that PC, exactly as if you had typed it there: the same AI session and history, your saved memories, the CAD session chosen in the chat’s Target box, the same model and the same commands. Your message appears in the chat on the PC marked [from WhatsApp], and the answer is shown there and sent back to WhatsApp, as complete as in the chat (only what WhatsApp cannot show — tables, code blocks, diagrams, Markdown — is left out). A message sent while an answer is still running is passed into it, like typing in the chat; /stop stops the running answer at once (and everything it started), /pause pauses it (it saves and says what was left), a long request continues by itself, /clear starts the conversation over (on the PC too), and /unattended always / /unattended off switch unattended mode on that PC (shown in its chat and written to its unattended log). Approvals are asked in the chat on the PC, as always — nothing is approved for you; WhatsApp shows no progress lines, so look at the PC when an answer takes long. Any other allowed number keeps a conversation of its own and cannot switch unattended mode.

Pictures, files and voice messages (1.3.7, Twilio): send them and they reach the chat on your PC like a file you attach there (up to 5 per message, 10 MB each, 20 MB together; anything over is named in the message instead; a caption is the message). They are fetched from Twilio with the account’s own credentials — on your PC for your own Twilio account, on the organisation server for the company number — in memory only, and only from the account holder. A voice message is turned into text on your PC, with the speech-to-text you chose for the chat’s microphone, and sent as your message; the answer starts with “🎤 Heard: …”. The QR path passes text only.

Troubleshooting

SymptomCause and fix
Nothing arrivesTwilio does not have the current relay address (after Rotate, write the new one), or the sandbox join lapsed (send join <code> again)
“Your SphereHarness PC … is not connected right now”The agent is not running or not signed in on that PC, or WhatsApp is switched off there
Messages refused on your PC / organisation server (invalid X-Twilio-Signature)Wrong auth token (re-type it in the password box, or -TwilioAuthToken on the server), or Twilio calls another address than the current relay address
Twilio’s debugger shows error 11200 / 404The address was rotated or disconnected: write the current one into Twilio
“Open Settings → Organisation … send me the code”Not paired: send the code
“Your PC … is not reachable right now”Start SphereHarness; check Settings → Organisation → Test
Registered sender not usable yetMeta verification takes weeks; use the sandbox meanwhile
The QR never appears / stopped workingNode.js still downloading; or the phone unlinked the device — Connect (QR) again

No longer offered: a Cloudflare tunnel or public address for WhatsApp, on your PC or on the organisation server, and a Twilio account stored in the SphereHarness org portal.

Related