WhatsApp product

The WhatsApp product turns a Twilio WhatsApp sender into an AI assistant for your organisation. Customers bring their own Twilio account, choose the model that should answer inbound messages, write the system prompt, and decide which plugins the assistant may use.

MVP status

This page documents the intended MVP flow end-to-end. The control-panel setup, inbound webhook, reply worker, and conversation viewer are rolling out together; sections marked “Coming soon” may not be enabled for every organisation yet.

How the MVP works

1. A customer messages your Twilio WhatsApp sender.
2. Twilio posts the inbound message to Crafted AI’s signed webhook.
3. Crafted AI resolves the organisation by the Twilio number, persists the inbound message, and enqueues a reply job.
4. The reply worker loads your WhatsApp app config: Twilio sender, default model, system prompt, and enabled plugin IDs.
5. The worker calls the same gateway path used by POST /v1/chat/completions.
6. The gateway injects only the plugins enabled for the WhatsApp app.
7. The assistant 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 for that sender.

Available now

The gateway, model catalog, credentials, plugin registry, and WhatsApp app config contracts are in place for staging organisations.

Coming soon

Managed Twilio onboarding is not part of the MVP. Bring your own Twilio account for now.

1. Create 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 used to send replies.
• Twilio Auth Token - stored encrypted and returned only as a masked value.
• Default model - the organisation model used for inbound replies.
• System prompt - the assistant instructions for this WhatsApp surface.
• Enabled plugins - the MCP or first-party plugins the assistant may call.

One WhatsApp app is supported per organisation for the MVP. If you need to change the sender or rotate Twilio credentials, update the existing app instead of creating a second one.

2. 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.

Production host

Examples use api-staging.craftedai.co while the production gateway is being provisioned. Switch Twilio to https://api.craftedai.co/webhooks/whatsapp/twilio when production is enabled.

3. Write the system prompt

The system prompt should describe the WhatsApp assistant’s job, boundaries, and handoff behaviour. Keep it specific to the messaging channel.

You are the WhatsApp assistant for Acme Support.
Answer in short, helpful messages.
Ask one clarifying question when the customer request is ambiguous.
Use enabled tools only when they help complete the request.
Do not mention internal IDs, provider names, or implementation details.
If the request needs a human, say that the team will follow up.

The MVP uses the prompt directly in the chat-completions request. Retrieval and FAQ stores are planned after the first WhatsApp release.

4. Enable plugins

Enabled plugins control what the WhatsApp assistant can do beyond text replies. Examples:

• A CRM MCP server can look up account status.
• A scheduling MCP server can create appointments.
• The first-party WhatsApp plugin can send messages or approved Twilio templates from gateway-driven tool calls.

The WhatsApp reply worker passes enabledPluginIds to the gateway. If the list is empty, no plugin tools are injected for inbound WhatsApp replies.

Safety boundary

The WhatsApp assistant does not automatically receive every plugin installed in the organisation. Only plugins selected on the WhatsApp app are exposed to that reply flow.

5. Review conversations

Open Conversations in the control panel to inspect WhatsApp threads. The MVP stores inbound and outbound messages on the shared chat timeline with channel = whatsapp, so conversation review uses the same chat primitives as the gateway.

Coming soon

Conversation review is part of the intended MVP. Manual message injection, canned responses, and advanced assignment workflows are planned for a later phase.

Control-panel API shape

Most teams should use the control panel. The underlying authenticated API uses the same org-scoped session token as the rest of the app.

Create

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",
  "defaultOrganizationModelId": "8c83dba8-7c9b-498d-8cb2-8cb7d3d6f4e9",
  "systemPrompt": "You are the WhatsApp assistant for Acme Support.",
  "enabledPluginIds": ["integration-uuid", "first_party:some-plugin"]
}

Update

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

{
  "systemPrompt": "You are the WhatsApp assistant for Acme Support. Keep replies under 500 characters.",
  "enabledPluginIds": ["integration-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.
• Dedicated /v1/whatsapp/... gateway endpoints.
• SMS, Voice, Instagram, or Messenger channels.
• Streaming partial model output directly to WhatsApp.

Next: read Plugins to understand tool access, or MCP integrations to connect external tools.