Quickstart

Prerequisites

A WhatsRB Cloud account with an API key (Dashboard)
A connected WhatsApp Business Account
A webhook endpoint (use webhook.site for testing)

1. Get your API key

2. Register a webhook endpoint

cURL
Python
Ruby
TypeScript

curl -X POST https://whatsrb.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "url": "https://your-webhook-url.com/whatsrb",
      "events": ["agent_run.completed", "agent_run.failed"]
    }
  }'

import whatsrb_cloud

whatsrb_cloud.configure(api_key="wrb_live_xxx")
client = whatsrb_cloud.client()

client.webhooks.create(
    url="https://your-webhook-url.com/whatsrb",
    events=["agent_run.completed", "agent_run.failed"]
)

require "whatsrb_cloud"

WhatsrbCloud.configure { |c| c.api_key = "wrb_live_xxx" }
client = WhatsrbCloud::Client.new

client.webhooks.create(
  url: "https://your-webhook-url.com/whatsrb",
  events: ["agent_run.completed", "agent_run.failed"]
)

import WhatsrbCloud from "@whatsrb/cloud";

const client = new WhatsrbCloud({ apiKey: "wrb_live_xxx" });

await client.webhooks.create({
  url: "https://your-webhook-url.com/whatsrb",
  events: ["agent_run.completed", "agent_run.failed"],
});

3. Create an agent

cURL
Python
Ruby
TypeScript

curl -X POST https://whatsrb.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "name": "Support Agent",
      "business_account_id": "YOUR_BA_ID",
      "system_prompt": "You are a customer support agent for an e-commerce store. Classify requests and extract relevant fields.",
      "auto_run_inbound": true,
      "allowed_actions": [
        "support.refund.process",
        "support.ticket.create",
        "support.order.status"
      ],
      "payload_schema": [
        { "name": "order_id", "field_type": "text", "required": true },
        { "name": "reason", "field_type": "text", "required": true },
        { "name": "amount", "field_type": "number", "required": false }
      ]
    }
  }'

agent = client.agents.create(
    name="Support Agent",
    business_account_id="YOUR_BA_ID",
    system_prompt="You are a customer support agent for an e-commerce store. Classify requests and extract relevant fields.",
    auto_run_inbound=True,
    allowed_actions=[
        "support.refund.process",
        "support.ticket.create",
        "support.order.status"
    ],
    payload_schema=[
        {"name": "order_id", "field_type": "text", "required": True},
        {"name": "reason", "field_type": "text", "required": True},
        {"name": "amount", "field_type": "number", "required": False}
    ]
)

agent = client.agents.create(
  name: "Support Agent",
  business_account_id: "YOUR_BA_ID",
  system_prompt: "You are a customer support agent for an e-commerce store. Classify requests and extract relevant fields.",
  auto_run_inbound: true,
  allowed_actions: [
    "support.refund.process",
    "support.ticket.create",
    "support.order.status"
  ],
  payload_schema: [
    { name: "order_id", field_type: "text", required: true },
    { name: "reason", field_type: "text", required: true },
    { name: "amount", field_type: "number", required: false }
  ]
)

const agent = await client.agents.create({
  name: "Support Agent",
  businessAccountId: "YOUR_BA_ID",
  systemPrompt:
    "You are a customer support agent for an e-commerce store. Classify requests and extract relevant fields.",
  autoRunInbound: true,
  allowedActions: [
    "support.refund.process",
    "support.ticket.create",
    "support.order.status",
  ],
  payloadSchema: [
    { name: "order_id", fieldType: "text", required: true },
    { name: "reason", fieldType: "text", required: true },
    { name: "amount", fieldType: "number", required: false },
  ],
});

4. Send a test message

Send a WhatsApp message to your connected business number:

“My order #ORD-1234 arrived broken, I want a refund of $49.90”

5. Receive the webhook

Within seconds, your webhook endpoint receives:

{
  "event": "agent_run.completed",
  "data": {
    "run_id": "run_abc123",
    "agent_id": "agt_def456",
    "status": "completed",
    "from": "33612345678",
    "output": {
      "intent": "refund_request",
      "confidence": 0.95,
      "actions": [
        {
          "type": "support.refund.process",
          "payload": {
            "order_id": "ORD-1234",
            "reason": "Product arrived broken",
            "amount": 49.90
          }
        }
      ],
      "language": "en",
      "suggested_reply": "I'm sorry about that! I'll process your refund of $49.90 for order #ORD-1234 right away.",
      "analysis_summary": "Customer requests refund for broken product"
    },
    "tokens": { "input": 850, "output": 120 },
    "duration_ms": 450
  }
}

The type is guaranteed to be one of your allowed_actions. The payload fields match your payload_schema. Your backend can safely parse and execute.

6. Handle it in your backend

Python
Ruby
TypeScript

# Your webhook handler
action_type = action["type"]
payload = action["payload"]

if action_type == "support.refund.process":
    process_refund(
        order_id=payload["order_id"],
        amount=payload["amount"],
        reason=payload["reason"]
    )
elif action_type == "support.ticket.create":
    create_ticket(payload)
elif action_type == "support.order.status":
    check_order_status(payload)

# Your webhook handler
case action["type"]
when "support.refund.process"
  Refunds::Process.call(
    order_id: action.dig("payload", "order_id"),
    amount: action.dig("payload", "amount"),
    reason: action.dig("payload", "reason")
  )
when "support.ticket.create"
  Tickets::Create.call(action["payload"])
when "support.order.status"
  Orders::CheckStatus.call(action["payload"])
end

// Your webhook handler
const { type, payload } = action;

switch (type) {
  case "support.refund.process":
    await processRefund({
      orderId: payload.order_id,
      amount: payload.amount,
      reason: payload.reason,
    });
    break;
  case "support.ticket.create":
    await createTicket(payload);
    break;
  case "support.order.status":
    await checkOrderStatus(payload);
    break;
}

Next steps

Agents Overview

Understand the full inbound pipeline and agent output structure.

Allowed Actions

Constrain what your agent can return.

Conversation Context

Give your agents memory across messages.

Webhooks

Configure webhook endpoints and event filtering.

Getting Started

Core Concepts

Widget

Agent & Workflows

Prerequisites

1. Get your API key

2. Register a webhook endpoint

3. Create an agent

4. Send a test message

5. Receive the webhook

6. Handle it in your backend

Next steps

Agents Overview

Allowed Actions

Conversation Context

Webhooks

​Prerequisites

​1. Get your API key

​2. Register a webhook endpoint

​3. Create an agent

​4. Send a test message

​5. Receive the webhook

​6. Handle it in your backend

​Next steps

Agents Overview

Allowed Actions

Conversation Context

Webhooks

Prerequisites

1. Get your API key

2. Register a webhook endpoint

3. Create an agent

4. Send a test message

5. Receive the webhook

6. Handle it in your backend

Next steps