WhatsApp

WhatsApp in Pozy runs on Meta's WhatsApp Business Platform. You connect a WhatsApp Business number to a profile, then message customers from the Inbox API, send broadcasts, and use templates, flows, groups and calling. The platform id is whatsapp.

This page is the summary. The WhatsApp section has a page for each feature.

#What you can do

#Two rules that shape every send

The 24-hour window. For 24 hours after a customer's last message you can send them anything. Outside that window, the first message must be an approved template. A free-form message outside the window fails with Meta's error 131047.

The messaging tier. A new number starts on Meta's lowest tier: 250 unique contacts in 24 hours for business-initiated conversations. Meta raises the tier as you build history and keep quality up. Quality and tier changes arrive as the whatsapp.account.quality_updated webhook.

#Connect

You need a WhatsApp Business Account inside a Meta Business account. A personal WhatsApp account cannot be connected. If the business has no WhatsApp Business Account yet, Meta creates one during signup. There are three ways in:

curl "https://api.pozy.ai/v1/connect/whatsapp?profileId=66a1f0c2a4b9d3e8f1a2b3c4&redirect_url=https://app.example.com/connected&onboarding=api" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/whatsapp?profileId=66a1f0c2a4b9d3e8f1a2b3c4&redirect_url=https:%2F%2Fapp.example.com%2Fconnected&onboarding=api", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
// Send the user's browser to data.authUrl

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/connect/whatsapp",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "66a1f0c2a4b9d3e8f1a2b3c4", "redirect_url": "https://app.example.com/connected", "onboarding": "api"},
)
print(resp.json()["authUrl"])

The user lands back on redirect_url with the new accountId, which every WhatsApp call takes from then on.

#Cloud API only or coexistence

onboarding decides whether the number keeps working in the WhatsApp Business app on the phone:

A profile can hold several WhatsApp numbers, each its own account. One number can be live on one profile only. If the user picks a number that conflicts, they come back to your redirect_url with an error such as one_whatsapp_per_profile, whatsapp_number_pinned_to_profile or whatsapp_number_already_connected. See Connect WhatsApp for each fix and for the full signup walkthrough.

#Sending messages

A new conversation starts with a template through Create conversation. Replies inside the 24-hour window use Send message.

curl -X POST https://api.pozy.ai/v1/inbox/conversations \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "participantId": "+13105551234",
    "templateName": "order_shipped",
    "templateLanguage": "en_US",
    "templateParams": ["Maria", "A-10423"]
  }'

const res = await fetch("https://api.pozy.ai/v1/inbox/conversations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "66b2e19d8c3f5a7e9d0b1c2d",
    participantId: "+13105551234",
    templateName: "order_shipped",
    templateLanguage: "en_US",
    templateParams: ["Maria", "A-10423"],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.data.conversationId);

resp = requests.post(
    "https://api.pozy.ai/v1/inbox/conversations",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
        "participantId": "+13105551234",
        "templateName": "order_shipped",
        "templateLanguage": "en_US",
        "templateParams": ["Maria", "A-10423"],
    },
)
print(resp.json()["data"]["conversationId"])

Once the customer replies, send free-form messages to that conversationId:

{
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "message": "Your parcel is with the courier. Tracking link below.",
  "attachmentUrl": "https://pozy.ai/media/label.pdf",
  "attachmentType": "file"
}

What a message can carry:

Send an Idempotency-Key header so a retry never sends twice. See Idempotency.

#Media requirements

Every URL must be public with no login and return the file, not a web page. Use Media to host files.

#Limits

#Analytics

WhatsApp has no post analytics. Delivery is tracked per message and per broadcast recipient through the message.delivered, message.read and message.failed webhooks. Conversation volume and response times are in Inbox analytics.

#Inbox

WhatsApp conversations live in the same Inbox as every other channel. Contacts, custom fields and automations such as workflows and sequences work on WhatsApp. There are no comments.

#Pricing

WhatsApp has two billers:

• Pozy bills the connected account, outbound messages past the monthly free allowance, numbers you buy through Pozy, and the carrier leg of outbound calls.
• Meta bills template delivery and its per-minute calling fee straight to the WhatsApp Business Account. Meta needs a payment method on that account, or it stops delivering templates once the free tier runs out.

See WhatsApp pricing and Pricing.

#Errors you may see

A message that was accepted and later fails arrives as message.failed with the same Meta code. Errors covers Pozy's error format.

#Endpoints

The full list is in the API reference.

#Webhook events