WhatsApp paid

Give your agent a WhatsApp number and it answers chats through the same on_message handler as every other channel. Run on Caspian's Meta Cloud number, bring your own Twilio, or hand a customer a single link to connect their own WhatsApp Business number, no tokens to copy.

Two ways to connect

WhatsApp is served by two providers. Same handler either way. You only pick where the number comes from:

Pass your choice as provider= on connect. Omit it to use the deployment's default WhatsApp provider.

Option A: Caspian's Meta number

The fastest managed path: connect and start replying on a Caspian-operated WhatsApp number.

from caspian_sdk import CommClient

client = CommClient()                                   # reads COMM_API_KEY / COMM_BASE_URL

wa = client.connect_whatsapp(provider="meta-whatsapp")  # Caspian's Meta Cloud number
print("WhatsApp on:", wa["address"])

@client.on_message
def handle(message):
    message.reply(f"You said: {message.text}")

client.listen()

import { CommClient } from "caspian-sdk";

const client = new CommClient();                          // reads COMM_API_KEY / COMM_BASE_URL

const wa = await client.connectWhatsapp({ provider: "meta-whatsapp" });  // Caspian's Meta number
console.log("WhatsApp on:", wa.address);

client.onMessage(async (message) => {
  await message.reply(`You said: ${message.text}`);
});

await client.listen();

Option B: your own Twilio

Bring your own Twilio account. The shared sandbox works in minutes; a dedicated production number needs Twilio's WhatsApp sender approval.

wa = client.connect_whatsapp(provider="twilio-whatsapp")
print("WhatsApp on:", wa["address"])   # your Twilio number (sandbox by default)

const wa = await client.connectWhatsapp({ provider: "twilio-whatsapp" });
console.log("WhatsApp on:", wa.address);   // your Twilio number (sandbox by default)

For inbound to reach your agent, do two one-time things in the Twilio Console (Messaging → Try it out → Send a WhatsApp message):

• Set When a message comes in to https://api.trycaspianai.com/internal/providers/twilio-whatsapp/webhooks (HTTP POST), and Save.
• From your own WhatsApp, send the shown join <two-words> to the sandbox number (+1 415 523 8886) to opt in.

Any message you then send that number reaches the same handler and gets a reply.

Let a customer connect their own number

To put a customer's own branded WhatsApp Business number on your agent (self-serve, with no tokens to copy), start a Meta Embedded Signup session. It returns a launcher_url you hand to whoever owns the number.

session = client.start_whatsapp_onboarding(
    customer_id="acme-corp",          # optional: target a specific customer + agent
    display_name="Acme Support",
)
print("Send this to the number owner:", session["launcher_url"])
print("Link expires in:", session["expires_in"], "seconds")

const session = await client.startWhatsappOnboarding({
  customerId: "acme-corp",            // optional: target a specific customer + agent
  displayName: "Acme Support",
});
console.log("Send this to the number owner:", session.launcher_url);
console.log("Link expires in:", session.expires_in, "seconds");

The owner opens launcher_url, clicks through Meta's popup once, and their number provisions onto the agent. Your API key never reaches the browser; the session token stands in for it. Poll get_connection() / getConnection() (or watch for a connection.active event) until the connection is active.

The 24-hour customer-service window

WhatsApp business rules apply on every provider. After a user messages your number, you can reply with free-form text for 24 hours. That window covers almost all agent work: someone messages, your on_message fires, you reply.

To start a conversation cold, or to reply after the 24-hour window has closed, WhatsApp requires a pre-approved message template. Your handler code doesn't change; the gateway enforces the difference. Design your agent to respond within the window and you rarely touch templates at all.

Next steps