WhatsApp Cloud API

CraftBot integrates directly with Meta’s WhatsApp Cloud API — no BSP middleman, no per-message markup, full visibility into the channel.

Prerequisites

Before adding a WhatsApp number to CraftBot you need, from Meta’s Business Manager:

• A WhatsApp Business Account (WABA).
• A verified Phone Number registered to your WABA.
• A Meta App (under your Business Manager) with the WhatsApp product enabled.
• The following five values from that app:
  • Phone Number ID (per phone number)
  • WABA ID
  • App ID
  • App Secret
  • Access Token (system-user permanent token recommended)

Plus a self-chosen Webhook Verify Token — any random 16+ character string you’ll paste into the Meta webhook subscription dialog. CraftBot stores it alongside the other secrets and uses it to answer Meta’s verification handshake.

Adding a number to CraftBot

1. Go to Settings → Channels → WhatsApp Numbers.
2. Click + Add Number in the top-right. The create page opens.
3. Fill in the three sections:
   • Basic Info — Display name, default language (en / ar / en_US / ar_SA / ar_AE), an optional Linked team for routing inbound chats, and the Set as default channel checkbox (one default per workspace, used when a recipe doesn’t pin a specific number).
   • Meta Identifiers — Meta App ID, Phone Number ID, WABA ID (all numeric, copied from the Meta App dashboard).
   • Credentials — App Secret, Access Token, Webhook Verify Token. All three are encrypted at rest with AES-256-GCM and never returned in plaintext after Save.
4. Click Save. You land on the channel’s detail page.
5. Expand Webhook Setup at the bottom of the detail page and follow the Webhook setup guide to point Meta at CraftBot.
6. Use Test Connection to verify the credentials work against Meta’s Graph API — on success it shows the phone’s display name, verified name, and quality rating.
7. Use Send Test Message to deliver a real WhatsApp message to a phone you control. You can pick an approved template (or fall back to Meta’s built-in hello_world) and watch the outbound status poll from sent → delivered → read in real time.

The channel list shows a Status pill per row — Connected (green), Failed (red — hover for error detail), or Untested (grey). The pill reflects the most recent Test Connection result.

Editing credentials

Open the channel → Edit. Each secret field renders as a read-only masked tail (e.g. ••••••••XXXX) showing the last four characters of the stored value, plus a Replace button.

• Leave a field as the masked tail to keep its existing value unchanged.
• Click Replace to flip the field into an editable input, paste the new value, then Save. Only fields you actually replaced are sent to the server.
• Click Cancel next to a replaced field to discard the new value and restore the mask.

Non-secret fields (display name, identifiers, linked team, default flag) behave as normal — type to change them.

Multiple numbers

CraftBot supports any number of WhatsApp configurations per workspace. Each row is independent. The DEFAULT badge on the list page marks the default channel; only one can be default at a time. Outbound that doesn’t pin a specific channel uses the default.

Removing a number

On the list page, click Delete on the row (or the Delete button on the detail page). Confirm the dialog. The configuration is soft-deleted — historical conversations remain readable, but you cannot send to or from this number afterwards. Vault rows for the deleted channel are kept (the FK is ON DELETE SET NULL), so an admin can restore the row at the database level if needed.

Operational considerations

• The 24-hour customer-service window applies — outside of it, the next outbound must be a pre-approved HSM template.
• Meta enforces per-number rate limits (typically 80 messages/sec for high-tier numbers). CraftBot respects these via a shared Redis token-bucket across all outbound queues.
• Status callbacks (delivered / read / failed) flow back to the conversation timeline automatically — there is no separate webhook field to subscribe to for them; they arrive on messages.