Business AI agent

Meta offers its own AI agent for WhatsApp Business numbers. When it is on, it answers customers in the chat using the business information, FAQs, websites and files you give it, follows the tone and rules you write as skills, and can call your APIs to look things up. Pozy exposes the whole setup under /v1/accounts/{accountId}/business-agent, so you can configure the agent for a merchant without them opening Meta's tools, except for two steps Meta keeps for the merchant.

#What only the merchant can do

GET /v1/accounts/{accountId}/business-agent reports the first under manualSteps (with the URL to send the merchant to). Meta does not expose billing state, so the second is listed under unverifiedSteps once an agent exists and you decide when to stop showing it.

#Which numbers qualify

The number must be on the Cloud API, in a vertical and country Meta supports, in good standing, and not running another AI product. Meta allows one AI product per number, so a coexistence number that still has the WhatsApp Business app's own AI linked is not eligible until the merchant unlinks it in the app. eligible on the status read is Meta's answer, and creating an agent on an ineligible number returns 403 business_agent_not_eligible.

#Set it up

curl https://api.pozy.ai/v1/accounts/6712a9d4c0e3b58f1a7d2e64/business-agent \
  -H "Authorization: Bearer $POZY_API_KEY"

{
  "eligible": true,
  "termsAccepted": true,
  "onboarded": false,
  "enabled": false,
  "agentId": null,
  "settings": null,
  "manualSteps": [],
  "unverifiedSteps": []
}

curl -X POST https://api.pozy.ai/v1/accounts/6712a9d4c0e3b58f1a7d2e64/business-agent/faqs \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Can I order a cake for the same day?",
    "answer": "Same-day cakes are available until 11am for pickup after 4pm. For delivery, order a day ahead."
  }'

const accountId = "6712a9d4c0e3b58f1a7d2e64";

const res = await fetch(`https://api.pozy.ai/v1/accounts/${accountId}/business-agent/faqs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "Can I order a cake for the same day?",
    answer: "Same-day cakes are available until 11am for pickup after 4pm. For delivery, order a day ahead.",
  }),
});
if (!res.ok) throw new Error((await res.json()).error);

import os
import requests

H = {"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"}
base = "https://api.pozy.ai/v1/accounts/6712a9d4c0e3b58f1a7d2e64/business-agent"

requests.post(f"{base}/faqs", headers=H, timeout=30, json={
    "question": "Can I order a cake for the same day?",
    "answer": "Same-day cakes are available until 11am for pickup after 4pm. For delivery, order a day ahead.",
}).raise_for_status()

curl -X POST https://api.pozy.ai/v1/accounts/6712a9d4c0e3b58f1a7d2e64/business-agent/test-messages \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you deliver to Cascais on Sundays?" }'

# 1. Allow a test phone
curl -X POST https://api.pozy.ai/v1/accounts/6712a9d4c0e3b58f1a7d2e64/business-agent/allowlist \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "consumer_phone_number": "+351912345678" }'

# 2. Switch on for allowlisted people only
curl -X PATCH https://api.pozy.ai/v1/accounts/6712a9d4c0e3b58f1a7d2e64/business-agent/settings \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rollout": { "enabled": true },
    "ai_audience": "ALLOWLISTED_ONLY",
    "handoff": { "enabled": true, "message_selection": "CUSTOM", "message": "Let me get someone from the shop to help you." }
  }'

#Settings

Settings update partially: fields you leave out keep their value.

#Work alongside the agent

While the agent holds a conversation, Pozy still sees everything:

• Customer messages arrive as message.received with metadata.standby: true.
• The agent's replies arrive as message.sent with source: "meta_business_agent".

Sending any message from Pozy takes the conversation back from the agent. If you run your own bot on the same number, skip messages marked standby or you will interrupt the agent on every turn.

The agent also hands over by itself when it is unsure or the customer asks for a person. To give a conversation back to the agent without sending anything, call POST /v1/inbox/conversations/{conversationId}/thread-control with action: "release". Every change of control fires conversation.control_changed.

#Tell the agent about events

When something happens in your systems that the customer should hear about (an order shipped, a document approved), send it with POST .../business-agent/events: the customer's number in to, a type, a description and a payload. The agent writes the message. The customer must already have a conversation with the number. The call answers 202 with an event id; check the outcome with GET .../events/{eventId}.

#Costs

Meta bills agent replies by tokens on the merchant's Business Agent billable account, separately from Pozy. Meta's own figure is roughly 4 to 5 US cents per message. Cap the spend with PUT .../budget: each budget is a max_budget of token or ai_turn units over one_day, seven_days, fourteen_days or thirty_days. Sending the list replaces all budgets, and an empty list means no cap. When a cap is hit the agent finishes its turn, stops answering and hands the thread to a person until the window rolls over.

#Endpoints

#Webhook events