Meta Business Agents

Meta Business Agents is in beta. Meta is still building the platform, so features, limits, and API behavior can change without notice.

A Meta Business Agent is an AI agent that Meta hosts and runs on your WhatsApp number. Kapso is where you set it up, configure it, publish changes, and pick up the conversations it hands off.

Before you start

A connected production number. Sandbox numbers aren’t supported.
Owner or admin role in the Kapso project.
Admin access to the Meta business portfolio and WhatsApp Business Account that own the number.

Create an agent

Open Meta Agents in the sidebar and click Add Meta Agent.

Choose a phone number. Numbers that already have an agent aren’t listed.
Create the agent in WhatsApp Manager. Click Continue to WhatsApp Manager, accept Meta’s terms, and create the agent there. Kapso detects it automatically. If it doesn’t show up, click I’m having trouble.

If the number already has an agent, Kapso connects to it instead of creating a new one. Meta prepares new agents in the background, so they show Preparing for a while.

Configure

Every edit is saved as a draft. Nothing changes on Meta until you publish. Kapso Agent can make these edits for you. It’s most useful for connectors and tools.

Settings

Setting	Effect
Agent rollout	Lets the agent reply to new conversations
Restrict to specific numbers	Only replies to numbers on the allowlist (E.164, for example `+15551234567`). Turn it off to reply to everyone, which needs a payment method on Meta’s side
Release control on handoff	Hands the conversation to your team after the handoff message. Pick Meta’s standard message, one written by the agent, or your own
Follow-up	Messages the customer after 5 minutes to 24 hours of inactivity

The Active / Inactive badge shows the rollout state Meta has, not your draft.

Knowledge

Source	Notes
Business information	Description, payment methods, returns, shipping, contact info
FAQs	Question and answer pairs
Files	PDF, DOC, DOCX, PNG, JPG, JPEG, CSV, XLSX up to 100 MB
Websites	Meta crawls the URL. Crawl status shows after you publish
Skills	Instructions for a specific situation. Meta reviews each published skill and can block it
UI skills	Interactive replies the agent can send: buttons, lists, carousels, images, locations, and WhatsApp Flows

Connectors and tools

A connector is an HTTP API the agent can call. A tool is one operation on that API: a method, a path like /orders/{order_id}, and its inputs.

Authentication: none, API key, or OAuth client credentials. You can add a client certificate (mTLS) to any of them.
Customer authentication: Meta injects the signed-in customer’s token into tool calls.
Input values: the agent decides, a fixed default, or the customer’s WhatsApp phone number, identity hash, or current status ID.

Logs on a connector shows tool activity and API failures from the last 24 hours.

Publish

Publish sends your changed items to Meta and creates a numbered version in Versions.

Partially applied: some changes failed. Fix the cause and click Retry remaining.
Discard unpublished edits resets the draft to what’s live on Meta.
Restore as draft copies an earlier version into your draft. Publish it to apply it. Connector credentials aren’t restored.
Refresh from Meta pulls the agent’s current configuration from Meta. Items with unpublished edits are kept.

Test

The Test tab chats with the live agent without messaging a customer. It uses the published version, not your draft, and is unavailable while a publish is running or after one fails. To test a single tool, open it in Connectors. Only published tools can be tested.

Monitor

Insights: conversations the agent replied to, and conversations waiting on your team.
Tool insights: daily calls, latency, and success, error, and timeout rates per tool, for up to 30 days.
Inbox: the Meta agent tab in a conversation’s sidebar shows routing changes and the agent’s turns, including tool inputs and outputs. Turns come from Meta and can lag behind the conversation.

Conversations

A number with a Meta agent is a shared number. Meta’s agent and Kapso are separate apps, and only one handles a conversation at a time. While the agent handles a conversation:

Customer messages and the agent’s replies show up in the Inbox. Agent replies have origin: "meta_business_agent".
Regular messages from workflows and the API fail with 409 and code: "meta_business_agent_control". Templates are always allowed.

{
  "error": "Meta Business Agent controls this conversation. Automated Service messages are blocked; templates are still allowed.",
  "code": "meta_business_agent_control",
  "thread_error": "thread_not_owner"
}

Customer messages on these numbers don’t start new workflows or agents. To automate after a handoff, use the whatsapp.thread.control_received trigger.

Take over

Click Take over in the Inbox.
Send from the API to the conversation. The conversation switches to Kapso once the send succeeds:

curl -X POST "https://app.kapso.ai/api/v1/whatsapp_conversations/$CONVERSATION_ID/whatsapp_messages" \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": { "content": "Hi, this is Dana from support." } }'

Send through the proxy with X-Kapso-Take-Control: true. See Sending messages.

Hand back

In the Inbox, open Transfer conversation and pick Meta AI agent. From the API, call thread control with "action": "pass" and "control_pass": { "target_role": "ai_agent" }. Release to routing doesn’t hand back to the agent. It leaves the conversation idle until Meta routes the customer’s next message.

Webhooks

Subscribe to whatsapp.thread.ownership_changed. A handoff from the agent has previous_owner_role: "ai_agent" and ownership: "this_app". Messages the agent handles keep firing whatsapp.message.* with passive: true.

whatsapp.meta_business_agent.handover is a legacy event. It still fires for webhooks already subscribed to it, but new webhooks can’t add it in the dashboard. Use whatsapp.thread.ownership_changed instead.

API

Kapso proxies Meta’s Business Agent API. Use Meta’s paths and payloads with Kapso’s base URL and your Kapso API key:

curl "https://api.kapso.ai/meta/whatsapp/$PHONE_NUMBER_ID/agent_config/settings" \
  -H "X-API-Key: $KAPSO_API_KEY"

Area	Paths
Agent	`agent_eligibility`, `agent_onboarding`, `delete_agent`, `agent_test`
Configuration	`agent_config/settings`, `agent_config/allowlist`, `agent_config/business_info`, `agent_config/faq`, `agent_config/websites`, `agent_config/files`, `agent_config/skills`, `agent-ui-skills`
Connectors	`agent_connectors`, `agent_connectors/{id}/tools`, `agent_connectors/{id}/tools/{tool_id}/run`, `agent_connectors/{id}/logs`, `agent_connectors/{id}/upsertApiKey`, `upsertOAuth`, `upsertCertificate`
Operate	`agent_event`, `insights/tool_calls`

X-API-Version defaults to 2.0.0. Other paths return 404. API changes go straight to Meta and skip your Kapso draft. Click Refresh from Meta to see them in the dashboard.

Agent events

Tell the agent something happened, like a payment or a shipment, so it can bring it up with the customer. The agent must be handling the conversation.

curl -X POST "https://api.kapso.ai/meta/whatsapp/$PHONE_NUMBER_ID/agent_event" \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "event": {
      "type": "payment_received",
      "description": "Payment received for order 123",
      "payload": "{\"order_id\":\"123\"}"
    }
  }'

Meta processes events asynchronously. Check the result with GET /{phone_number_id}/agent_event/{agent_event_id}.

Getting started

WhatsApp

For your team

Onboard customers

Automations

Migrate to Kapso

Before you start

Create an agent

Configure

Settings

Knowledge

Connectors and tools

Publish

Test

Monitor

Conversations

Take over

Hand back

Webhooks

API

Agent events

​Before you start

​Create an agent

​Configure

​Settings

​Knowledge

​Connectors and tools

​Publish

​Test

​Monitor

​Conversations

​Take over

​Hand back

​Webhooks

​API

​Agent events

Before you start

Create an agent

Configure

Settings

Knowledge

Connectors and tools

Publish

Test

Monitor

Conversations

Take over

Hand back

Webhooks

API

Agent events