WhatsApp

WhatsApp threads run through a Bot. When a message arrives on your Twilio WhatsApp number, the reply worker resolves the bound bot and calls the gateway with the bot’s system prompt, skills, and plugin allowlist applied. You get the same bot behaviour on WhatsApp as on the gateway API — no separate configuration.

Read Concepts and Bots first.

How it works

A customer messages your Twilio WhatsApp sender.
Twilio posts the inbound message to Crafted AI’s signed webhook.
Crafted AI resolves the organisation by the Twilio number and persists the message.
A reply job is enqueued. The reply worker loads the WhatsApp app config and reads the bound bot_id.
The worker calls the gateway using the bot’s configuration — system prompt, skills, and allowed plugins.
The gateway resolves the bot, runs the tool loop if needed, and returns the assistant response.
The response is sent back through Twilio and saved in the conversation history.

Prerequisites

An owner account in the Crafted AI control panel.
At least one provider key and model configured for the organisation.
A Twilio account with WhatsApp enabled.
A Twilio sender number formatted as whatsapp:+15551234567.
Twilio Account SID and Auth Token.
A Bot created and configured for your WhatsApp use case.

1. Create or select a Bot

Before configuring WhatsApp, decide which bot should handle inbound threads. Options:

Install an Industry Pack from Marketplace — creates a fully configured bot in one step.
Create a Bot manually under Bots → New Bot — write the system prompt, pick skills, attach MCP plugins.

The bot’s system prompt should be written for the conversational WhatsApp channel — short replies, mobile-friendly, focused on a single surface.

2. Configure the WhatsApp app

Open app.craftedai.co, switch to the target organisation, then go to WhatsApp.

Configure:

Twilio number — the sender number, including the whatsapp: prefix.
Twilio Account SID — the Twilio credential for sending replies.
Twilio Auth Token — stored encrypted; masked on all subsequent reads.
Bot — select the bot that should handle inbound replies.

One WhatsApp app is supported per organisation. To change the sender or rotate Twilio credentials, update the existing app.

3. Connect Twilio

Set your Twilio WhatsApp inbound message webhook to:

https://api-staging.craftedai.co/webhooks/whatsapp/twilio

Use POST with Twilio’s default application/x-www-form-urlencoded payload. Crafted AI verifies the X-Twilio-Signature header before accepting the message.

4. Review conversations

Open Conversations in the control panel to inspect WhatsApp threads. Messages are stored with channel = whatsapp on the shared chat timeline, so the same conversation viewer shows both WhatsApp and gateway API threads.

POST /whatsapp-app
Authorization: Bearer <control-panel-access-token>
X-Org-Id: <organization-uuid>
Content-Type: application/json

{
  "twilioNumber": "whatsapp:+15551234567",
  "twilioAccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "twilioAuthToken": "twilio-auth-token",
  "botId": "<bot-uuid>"
}

PATCH /whatsapp-app/{appId}
Authorization: Bearer <control-panel-access-token>
X-Org-Id: <organization-uuid>
Content-Type: application/json

{
  "botId": "<new-bot-uuid>"
}

Twilio SID and token must be supplied together when rotating credentials. Responses include masked Twilio credential fields; plaintext values are never returned after creation or update.

What’s not in the MVP

Managed Twilio account provisioning.
Multiple WhatsApp apps per organisation.
RAG retrieval and FAQ document stores.
SMS, Voice, Instagram, or Messenger channels.
Streaming partial model output directly to WhatsApp.

Next: read Plugins to understand tool injection, or Bots to configure the bot bound to your WhatsApp app.