Everything you need

How It Works

When a customer sends a message to your WhatsApp Business number, here's what happens:

1. Meta's WhatsApp API receives the message and sends it to Ricky via webhook
2. Ricky identifies which agent handles that phone number
3. The agent receives the message along with conversation history and available tools
4. The agent reasons about what the customer needs and formulates a response
5. If needed, the agent uses tools (checking inventory, booking appointments, etc.)
6. The response is sent back to the customer via WhatsApp

The entire process typically takes 2-5 seconds, depending on complexity.

Prerequisites

Before you can use Ricky, you'll need:

• A WhatsApp Business Account (WABA) connected to Meta Business Manager
• A verified Meta Business Manager account
• A phone number that isn't already registered with WhatsApp

Quick Start

Metrics

Recent Conversations

The dashboard shows your five most recent conversations. Each entry displays the customer's phone number, which agent handled it, the conversation status, and when it was last active. Click any conversation to view the full message history.

Onboarding Checklist

If you haven't completed setup, the dashboard shows a checklist with your remaining steps: connecting WhatsApp, creating an agent, and sending your first message. Each item links to the relevant section of the portal.

Creating an Agent

Writing Effective System Prompts

A good system prompt clearly defines four things: identity, knowledge, behavior, and constraints.

• Identity: Who the agent is. Give it a name and role. "You are Ana, a customer service agent for TechStore."
• Knowledge: What the agent knows about your business—products, services, policies, pricing, locations, hours.
• Behavior: How to handle common scenarios, when to escalate, tone of voice, language preferences.
• Constraints: What the agent should never do or say. What topics to avoid. When to refuse a request.

Here's an example:

You are Ana, a friendly customer service agent for TechStore,
an electronics retailer in Panama City.

Your responsibilities:
- Answer questions about products, pricing, and availability
- Help customers track their orders using the order_lookup tool
- Schedule store visits using the booking tool
- Handle complaints professionally and offer solutions

Guidelines:
- Be warm and helpful, use casual but professional Spanish
- If you don't know something, say so honestly
- For refunds or complex issues, collect details and escalate
- Never share customer data or make promises you can't keep

Assigning Tools to Agents

Tools extend what your agent can do. To assign tools:

1. Open the agent's detail page by clicking on it in the Agents list
2. Scroll down to the "Assigned Tools" section
3. Click "Manage Tools" to see available tools
4. Toggle on the tools you want this agent to have access to

The agent will automatically know how to use any assigned tools based on their descriptions. You don't need to explain tool usage in the system prompt.

Activating and Pausing Agents

Agents can be active or inactive. An inactive agent won't respond to any messages—they'll queue until the agent is reactivated.

To toggle an agent's status, click the toggle switch next to its name in the Agents list, or use the "Active" toggle on the agent's detail page.

Viewing Agent Conversations

From an agent's detail page, click "View Conversations" to see all conversations handled by that specific agent. You can filter by status (active, closed) and search by customer phone number.

Deleting Agents

To delete an agent, open its detail page and click the delete button. You'll be asked to confirm. Deleting an agent does not delete its conversation history—that data is retained for your records.

Conversation List

The left panel shows all conversations, sorted by most recent activity. Each entry displays:

• Customer phone number (last 4 digits visible, full number on hover)
• Which agent is handling the conversation
• Status indicator (active, paused, or closed)
• Time of last message

Conversation Statuses

Viewing Message History

Click any conversation to view the full message history. Messages are displayed chronologically with timestamps. Customer messages appear on the left, agent responses on the right. Tool calls (like checking inventory) are shown inline so you can see exactly what the agent did and why.

Human Takeover

Sometimes the agent needs to hand off to a human. This happens when:

• The agent calls the handoff_to_human tool
• A human operator manually pauses the conversation

When a conversation is paused, you can send messages directly to the customer. Type your message in the input field and click Send. Your messages are marked as coming from "Operator" so you can distinguish them from agent messages later.

To resume agent handling, click "Resume Agent" in the conversation header. The agent will pick up where it left off, with full context of the human intervention.

Platform Tools

These built-in tools are available to all agents:

Creating Custom Tools

Custom tools connect your agent to your business systems. There are two types:

• Webhook tools: Call your API endpoint when the agent needs information or wants to take an action
• Data query tools: Query a database or data source you've connected (coming soon)

Parameter Schema Format

Parameters are defined using JSON Schema. Here's an example for an inventory check tool:

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "The SKU or product ID to check"
    },
    "location": {
      "type": "string",
      "description": "Store location (e.g., 'panama-city', 'colon')"
    }
  },
  "required": ["product_id"]
}

The description field is important—it helps the agent understand what each parameter means and how to fill it in based on the conversation.

Testing Tools

Before assigning a tool to agents, test it. On the tool's detail page, click "Test Tool." Enter sample parameter values and click "Execute." You'll see the raw request sent to your endpoint and the response received. This helps debug issues before they affect live conversations.

Assigning Tools to Agents

Tools are organization-wide by default. To make a tool available to an agent, go to the agent's detail page, scroll to "Assigned Tools," and toggle on the tools you want. An agent can only use tools that are explicitly assigned to it.

Request Format

When an agent invokes a webhook tool, Ricky sends a POST request to your endpoint:

POST https://your-api.com/inventory
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "tool_name": "check_inventory",
  "arguments": {
    "product_id": "SKU-12345",
    "location": "panama-city"
  },
  "context": {
    "conversation_id": "conv_abc123",
    "customer_phone": "+507XXXXXXXX",
    "agent_id": "agent_xyz789"
  }
}

The context object provides information about the conversation, which you can use for logging or to customize responses based on the customer.

Response Format

Return a JSON response. The agent will use this information to formulate its reply to the customer:

{
  "success": true,
  "data": {
    "product": "iPhone 15 Pro 256GB",
    "available": true,
    "quantity": 12,
    "price": 1199.00,
    "location": "Panama City - Multiplaza"
  }
}

Keep responses concise. The agent needs facts, not prose. Include relevant data in a structured format.

Error Handling

If something goes wrong, return an error response:

{
  "success": false,
  "error": "Product not found"
}

The agent will see this error and can explain to the customer that the information isn't available or suggest alternatives.

Authentication Options

Credentials are stored securely and encrypted at rest. They're never exposed in logs or to agents.

Timeouts and Retries

Webhook requests time out after 30 seconds. If your endpoint doesn't respond, the tool call fails and the agent proceeds without that information. We don't retry failed requests automatically—the agent may attempt the tool call again based on conversation flow.

Prerequisites

Before connecting WhatsApp, ensure you have:

• A Meta Business Manager account (verified preferred, but not required)
• A phone number that isn't currently registered with WhatsApp (personal or Business)
• Access to receive SMS or calls on that phone number for verification

Connecting Your WhatsApp

After Connection

Once connected, your phone number appears in Settings → WhatsApp. You can:

• Assign an agent to handle messages for that number
• View the phone number's quality rating and status
• See message statistics for that number

Quality Rating

Meta assigns quality ratings to phone numbers based on customer feedback and message patterns. Ratings are:

To maintain a good rating, ensure your agents are helpful and relevant, avoid spammy behavior, and honor customer opt-out requests.

Organization Settings

View and update your organization name and basic information. If you manage multiple organizations, you can switch between them using the organization selector in the header.

WhatsApp Connections

Manage your connected WhatsApp Business Accounts and phone numbers. Assign agents to phone numbers, view quality ratings, and disconnect numbers if needed.

Account Security

Update your email and password. We recommend using a strong, unique password and enabling two-factor authentication when available.

Billing

View your current plan, message usage, and billing history. Upgrade or change plans as your needs grow. See the Pricing page for plan details.

Webhook Payload (Incoming)

When your webhook tool is invoked, the request body contains:

{
  "tool_name": "check_inventory",
  "arguments": {
    "product_id": "SKU-12345",
    "location": "panama-city"
  },
  "context": {
    "conversation_id": "conv_abc123",
    "customer_phone": "+507XXXXXXXX",
    "agent_id": "agent_xyz789"
  }
}

Message Types

Agents can send different types of messages to customers:

Context Object

The context object included in webhook requests:

General Questions

Troubleshooting