Let your team message the company's WhatsApp number and have it drive their CAD workstation. CADCoPilot connects to WhatsApp through Twilio.
New to channels? Read Channels & Messaging first for the overall picture. This page is the complete WhatsApp walkthrough.
The connection at a glance
Twilio owns the WhatsApp number and posts every inbound message to a CADCoPilot webhook. The webhook works out which company the message belongs to from the number it was sent to, and who sent it from the sender's phone number.
Step by step
IT admin Set up the Twilio side
Everything here happens in the Twilio Console. You need a Twilio account and, for a production number, a Meta Business account to verify against.
-
Create or sign in to a Twilio account. From the Console home page, note the two values on the account card:
- Account SID — starts with
ACfollowed by 32 hexadecimal characters. This is an identifier, not a secret. - Auth Token — 32 hexadecimal characters, hidden behind a Show button. This is a secret.
If you use a Twilio subaccount per customer or department, take the subaccount's SID and token — CADCoPilot authenticates with exactly the pair you give it.
- Account SID — starts with
-
Choose sandbox or a real number.
- Sandbox (Messaging → Try it out → Send a WhatsApp message): free, instant, shared. Twilio gives you a shared number —
+14155238886at the time of writing — and a join phrase. Every person who wants to use it must first send that join phrase from their own WhatsApp. Sandbox sessions lapse after a period of inactivity and have to be re-joined. - Your own WhatsApp sender (Messaging → Senders → WhatsApp senders): a real business number, your company display name, and Meta business verification. Takes days rather than minutes but is the only production-grade option.
- Sandbox (Messaging → Try it out → Send a WhatsApp message): free, instant, shared. Twilio gives you a shared number —
-
Point the inbound webhook at CADCoPilot. On the sandbox settings page, or on your WhatsApp sender's configuration page, set:
When a message comes in →
HTTP POST→https://www.cadagent.plmcadutilities.com/api/channels/whatsapp/inboundUse exactly that URL, with
httpsand no trailing slash. Twilio signs each request against the URL it called, so a mismatch (extra slash,http, a different host name) makes the signature check fail and messages are rejected. -
Leave the status-callback field empty. CADCoPilot does not consume delivery receipts.
Org admin Save the credentials in the org portal
-
Sign in to the org portal as an organization admin and open Messaging Channels.
-
Fill in the WhatsApp (Twilio) panel:
- Enabled — ticked (it is by default).
- Twilio Account SID — the
AC…value. - WhatsApp phone number — the number Twilio receives on, in E.164 form:
+14155238886. This is what CADCoPilot matches an incoming message against to know it is yours, and what it sends replies from. - Twilio auth token — the secret. It is also what verifies Twilio's signature on every inbound message, so it must be the token belonging to the same account or subaccount as the number.
The WhatsApp panel: Account SID, the WhatsApp number, and the Twilio auth token. -
Leave User self-connect ticked so people can link their own phones. WhatsApp has no automatic linking — without self-connect nobody can connect themselves.
-
Press Save. WhatsApp needs no restart: the webhook reads the saved credentials on every message, so the channel is live as soon as the save completes.
+14155238886.
CADCoPilot strips WhatsApp's whatsapp: prefix before matching, and adds it back when replying, so
either form is accepted — but the digits, including the country code and the leading +, must
match the number Twilio is actually receiving on. A mismatch shows up as inbound messages being silently ignored.
End user Connect your own WhatsApp
Unlike Telegram there is no deep link — you send a one-time code from the phone you want to use. That is what tells CADCoPilot which phone number is you.
-
Sandbox only: first join the sandbox. Send the join phrase your IT admin gives you (Twilio shows it on the sandbox page, in the form
join <two-words>) to the sandbox number from your own WhatsApp. Skip this step if your company uses its own WhatsApp number. -
Open Settings → Messaging Channels in the CAD add-in, or the tray Agent status window. WhatsApp should read enabled.
Settings → Messaging Channels. WhatsApp shows enabled/connected status and a Connect button. -
Press Connect next to WhatsApp. CADCoPilot shows the company number and a one-time code:
“Send this message from WhatsApp to +14155238886 to connect: 3f9c1a7e5b2d4c8e9a0f6b1d7e2c5a48”
The code is 32 hexadecimal characters, valid for 30 minutes, single use.
-
From the phone you want to drive your CAD with, open WhatsApp, start a chat with that number, and send the code on its own — nothing else in the message.
-
You get back:
“Linked! You can now drive your CAD from here.”
Press Refresh status in Settings — WhatsApp now reads connected.
End user Your first test message
Make sure the tray Agent is running and connected, then send something small:
Then something that builds geometry:
And verify the result rather than trusting the wording:
Exact values
| Where | What goes in it | Format / example |
|---|---|---|
| Twilio → When a message comes in | The CADCoPilot inbound webhook, method HTTP POST |
https://www.cadagent.plmcadutilities.com/api/channels/whatsapp/inbound |
| Portal → Twilio Account SID | Account (or subaccount) SID | AC + 32 hex characters. Not secret. |
| Portal → WhatsApp phone number | The number Twilio receives on | E.164, e.g. +14155238886. whatsapp:+14155238886 is also accepted. |
| Portal → Twilio auth token | The account's auth token | 32 hex characters. Secret. Also used to verify Twilio's request signature. |
| User link code | Sent as a WhatsApp message to the company number | 32 lower-case hex characters, single use, 30 minutes |
Re-saving and rotating credentials
- Blank means keep. Once the auth token is stored, the field shows (stored) and a masked placeholder. Saving with it blank keeps the stored token, so you can correct the number or the SID without retyping the secret.
- Non-secret fields are different: the SID and the phone number are saved exactly as typed, and clearing one clears it. Do not empty them by accident while editing something else.
- To rotate the auth token: create the new token in Twilio, paste it into the portal and save before retiring the old one in Twilio. Inbound signature checks use whatever CADCoPilot has stored, so a token rotated in Twilio but not in the portal makes every message fail verification.
- To take WhatsApp out of service, untick Enabled and save. Inbound messages are then ignored and no replies are sent.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Nothing comes back at all, and Twilio's log shows the webhook was called. | The destination number in the portal does not match the number Twilio received on, so no organization is matched. | Copy the number exactly as Twilio shows it, in E.164 with the leading +, and save. |
| Twilio's log shows 401 Unauthorized from the webhook. | The signature check failed: the stored auth token is wrong (or belongs to a different subaccount), or the webhook URL configured in Twilio differs from the one the signature was computed against. | Re-copy the auth token for the same account that owns the number, and set the webhook to the exact URL above — https, no trailing slash, no query string. |
| Twilio's log shows nothing at all when you message. | The webhook is not configured on that number, or (sandbox) your phone has not joined / its session lapsed. | Set the inbound webhook on the number you are messaging. For the sandbox, send the join <two-words> phrase again. |
| It worked in the sandbox, then broke after moving to the company number. | The portal still holds the sandbox number, and users are still linked by the phone they used — that part carries over, but the destination did not. | Update the number (and the SID/token if the sender lives in a different account), set the webhook on the new number, and re-test. Existing user links are unaffected. |
| “This account isn't linked to CADCoPilot.” | That phone number has never sent a valid link code. | Press Connect in the add-in or tray Agent and send the code from that phone. |
| The code was sent but nothing linked. | More than 30 minutes had passed, the code was already used, or it was sent with extra text around it. | Get a fresh code and send it on its own, with nothing before or after it. |
| A colleague's messages are driving your CAD. | Your code was sent from their phone, so their number is linked to your account. | Have them press Connect in their own CADCoPilot and send their own code from that phone — the number is repointed to them. |
| “No active CADCoPilot agent found on your PC.” | The tray Agent is stopped, or lost its connection after a server restart and its retries ran out. | Open the tray Agent, press Stop then Start. Your WhatsApp link is stored in the database and survives. |
| No screenshot came back. | By design — attachments are not delivered over WhatsApp. | Use Telegram, or open the CAD chat panel on the workstation. |
| A long reply arrives split across messages. | Not a fault — replies are split into 1500-character parts. | Ask for shorter answers, or read the transcript in the CAD chat panel. |
| Replies stop arriving after a long quiet period, but Twilio reports success. | WhatsApp only allows free-form business replies within 24 hours of the user's last message. | Send a new message to the bot and retry. In normal use the reply follows your message immediately, so this only bites when a request stalls for many hours. |
Security
- The auth token is encrypted at rest with a key scoped to your organization, and is decrypted only inside the server — to verify Twilio's signature on the way in and to authenticate the reply on the way out. It never reaches a workstation.
- The portal never shows it back. After saving, the field shows (stored) and a masked placeholder. The Account SID and phone number are identifiers, not secrets, and stay visible to organization admins.
- Every inbound message is authenticated. CADCoPilot checks the
X-Twilio-SignatureHMAC against your auth token before trusting the sender, so a forged “From” cannot impersonate a linked colleague. Requests that fail the check are rejected with 401 and never reach a workstation. - Your phone number is your identity here. Anyone who can send from that number can drive the linked user's CAD — treat a lost or recycled phone number the same way you would treat a lost password, and re-link or ask for the link to be removed.
- Link codes are single-use and expire in 30 minutes. Never forward one; whoever sends it first becomes the linked phone.
- To stop new links across the company, untick User self-connect and save. To take the channel out of service, untick Enabled and save — this takes effect immediately, with no restart.
- To revoke one person's link, the reliable route today is to have the correct user re-link that number to themselves, which overwrites the link. There is no self-service “disconnect” button yet — for a permanent removal (a lost phone, a leaver), ask CADCoPilot support to delete the identity link.
Related
- Channels & Messaging — the shared architecture and the tray Agent
- Telegram setup · Microsoft Teams setup
- Verifying Results — always confirm geometry, never trust the wording of a reply