Business API · v1

Your system sends. Their phone buzzes.

One REST endpoint for every message type, one signed webhook for everything that comes back. The payloads are shaped like the WhatsApp Cloud API on purpose, so a flow you have already written ports across with a changed base URL and a changed key.

Last updated: 4 Nov 2026

Quick start

Everything lives under https://api.pitta.pro. Issue a key from the app (Channel → Developer → API keys) or from the portal at app.pitta.pro, and keep it in an environment variable on your server:

export PITTA_KEY="q_live_0123456789abcdef:sk_your_secret_here"

1. Message one customer: check, opt in, send

The person must have a Pitta account on that number, and must have agreed to hear from you (they follow your channel, wrote to you first, or you record the consent you collected).

# a. is this number on Pitta?
curl https://api.pitta.pro/v1/contacts/+919876543210 \
  -H "Authorization: Bearer $PITTA_KEY"
# 200 { "phone":"+919876543210", "registered":true, "reachable":true,
#       "opted_in":false, "opted_out":false, "can_opt_in":true }

# b. record the consent you collected (a form, a checkout, an import)
curl -X POST https://api.pitta.pro/v1/contacts/opt-in \
  -H "Authorization: Bearer $PITTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+919876543210", "source": "website_form" }'
# 201 { "phone":"+919876543210", "opted_in":true, "opted_in_at":"…" }

# c. send
curl -X POST https://api.pitta.pro/v1/messages \
  -H "Authorization: Bearer $PITTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "text",
    "text": { "body": "Your order is packed and leaves at 4pm." },
    "client_msg_id": "order-1042-packed"
  }'

# 201 Created
{ "id": "cmuy…", "status": "sent", "conversation_id": "cmus…", "type": "text" }

2. Post to every follower (broadcast)

No phone numbers needed: one call reaches everyone who follows your channel, exactly like the Broadcast button in the app. See Post to all followers.

curl -X POST https://api.pitta.pro/v1/broadcasts \
  -H "Authorization: Bearer $PITTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Diwali sale starts tomorrow at 10am. *20% off* everything.",
        "importance": "important" }'

# 200 { "total": 86, "sent": 86, "failed": 0, "broadcast_id": "5c0e…" }

Which one to use: broadcast to tell all your followers the same thing; POST /v1/messages for one customer (an order update, a reply); POST /v1/messages/batch for many different messages to a list of numbers you already have consent for.

Authentication

A key belongs to one channel and carries its permissions. Send it as a bearer token on every request: the key id, a colon, then the secret. A key id starts q_live_ and a secret starts sk_; the key string you get at creation is already in this form.

Authorization: Bearer <key_id>:<secret>
  • The secret is shown onceAt creation, together with the ready-to-use key string. Store it in your server's environment; it is never displayed again and we cannot recover it for you.
  • Revoke instantlyFrom the same screen. A revoked key answers 401 on the next call.
  • Server-side onlyNever ship a key in an app, a browser or a public repository. Anyone holding it can message your followers as you.
  • Reuse one keyThe first request with a key runs a deliberately slow secret check; later requests are fast. Keep one key per sending system and reuse it (see Speed & retries).

A key holds scopes. A new key gets all of them unless you narrow it; a call outside the key's scopes is refused with 403 "API key is missing scope: …".

ScopeAllows
messages:sendSend, batch, broadcast, typing, read receipts, opt-in
messages:readGET /v1/messages/{id}
contacts:readGET /v1/contacts/{phone}
media:write / media:readUpload media / fetch a download link for it
profile:write / profile:readPUT / GET /v1/profile
webhooks:writeCreate a webhook, rotate its secret
orders:readGET /v1/orders. A key that holds every other scope in this table has it too (keys made before orders existed); a key with a narrower set does not.

Phone numbers

  • E.164, with or without the +Any format is normalised to E.164 on our side: 919876543210, +919876543210 and +91 98765 43210 are the same number, so a WhatsApp Cloud API integration ports without rewriting its number handling. Responses always give the + form.
  • The country code is requiredA bare ten-digit number is refused with 400 rather than guessed at. If your data is in a local format, send "country": "IN" (any ISO country code) alongside it on POST /v1/messages or POST /v1/contacts/opt-in.
  • The recipient must be on Pitta: otherwise 404We deliver inside the app only (there is no SMS fallback), so a "sent" for a number that cannot receive it would be a lie. The answer is "+91… is not on Pitta. They need to install Pitta and sign up with this number before you can message them." Check first with GET /v1/contacts/{phone}.

Send a message

POST /v1/messages → 201 with { id, status, conversation_id, type }. One endpoint for every type, discriminated by type; shapes and limits follow the WhatsApp Cloud API.

FieldTypeNotes
tostringRecipient, E.164 with or without +. Required.
typestringtext, image, video, audio, document, location, interactive, poll or reaction. Anything else is 400.
text / image / video / audio / document / location / interactive / poll / reactionobjectThe content block matching type. See Message types.
countrystringOptional. ISO country for a number written without its country code.
importancestringOptional. regular or important. important puts the thread in the customer's Important tab. Omit it to keep the thread's current importance.
client_msg_idstringOptional, up to 120 characters. Your own id for this message, and an idempotency key, forever, per channel: a repeat returns the original message (same id) and sends nothing. Use it, and retries after a timeout are safe. Consent is checked first, so once the person has opted out a repeat is refused with 403 rather than answered with the original.
reply_tostringOptional. The id of the message you are quoting (WhatsApp context.message_id). Send it only when you want the quote shown.
allow_requestbooleanOptional. To someone with no relationship to your channel, send as a message request instead of being refused with 403.
ai_contentbooleanOptional. Marks the message as made or edited with AI; the customer sees a small AI content tag. Images and videos that carry AI provenance metadata (C2PA, IPTC, Stable Diffusion text) are tagged automatically, and leaving the flag out never clears that.

Messages do not expire: they stay in the chat and are kept on record. expires_at and expires_in_seconds are still accepted for older integrations, and ignored. Unknown fields are dropped, not rejected.

Message types

Text, with up to three footer buttons

{
  "to": "+919876543210",
  "type": "text",
  "importance": "important",
  "text": {
    "body": "*Your table is booked* for 8pm.",
    "preview_url": false,
    "buttons": [
      { "type": "url",   "title": "Directions", "url": "https://maps.example/…" },
      { "type": "call",  "title": "Call us",    "phone": "+919876543210" },
      { "type": "reply", "id": "cancel",      "title": "Cancel booking" }
    ]
  },
  "client_msg_id": "booking-77-confirm"
}

The body is capped at 4,096 characters and supports *bold*, _italic_ and line breaks. Buttons sit under the bubble like a WhatsApp template footer, so you never need to paste raw links into the body. Button types are url, call and reply; a reply tap comes back on your webhook as a button_reply with your id. A fourth button is refused with 400. Title limits: 25 characters for url, 20 for call and reply. preview_url: false suppresses the link-preview card.

Media: by link or by upload

{ "to": "+919876543210", "type": "image",
  "image": { "link": "https://cdn.example/new-arrival.jpg",
             "caption": "Just in. 12 pieces only." } }

// A picture with text and buttons (up to 3, any mix of url / call / reply)
{ "to": "+919876543210", "type": "image",
  "image": { "link": "https://cdn.example/banner.jpg",
             "caption": "Gold is down today. See the full analysis.",
             "buttons": [
               { "type": "url",  "title": "Visit website", "url": "https://example.com" },
               { "type": "call", "title": "Call us", "phone": "+919876543210" } ] } }

{ "to": "+919876543210", "type": "document",
  "document": { "media_id": "MEDIA_ID", "filename": "invoice-1042.pdf" } }

image, video, audio and document take the same shape: either a public link or a media_id from an upload, plus an optional caption (up to 1,024 characters) and filename. All four also take buttons, exactly as on a text message: up to 3, any mix of url, call and reply, shown under the media. We fetch a link once and keep our own copy, so a link that expires later does not empty the customer's thread. Caps for linked media: image 5 MB (jpeg, png, webp, gif), video 16 MB (mp4, 3gpp), audio 16 MB (mp3, aac, m4a, amr, ogg, opus, 3gpp, webm, wav), document 25 MB. Uploaded media may be up to 100 MB.

Interactive: reply buttons, lists, a link or a call

{ "to": "+919876543210", "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { "type": "text", "text": "Order #1042" },
    "body":   { "text": "Ready for pickup?" },
    "footer": { "text": "Reply within 2h" },
    "action": { "buttons": [
      { "type": "reply", "reply": { "id": "pick_now", "title": "Pick up now" } } ] } } }

{ "to": "+919876543210", "type": "interactive",
  "interactive": {
    "type": "list",
    "body": { "text": "Pick a slot for Thursday" },
    "action": { "button": "Choose", "sections": [
      { "title": "Morning", "rows": [
        { "id": "s9",  "title": "9:00", "description": "30 min" },
        { "id": "s10", "title": "10:00" } ] } ] } } }

{ "to": "+919876543210", "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": { "text": "See today's menu" },
    "action": { "name": "cta_url",
                "parameters": { "display_text": "Open menu", "url": "https://example.com/menu" } } } }

// An image with a link button: put the image in the header
{ "to": "+919876543210", "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": { "type": "image", "image": { "link": "https://example.com/banner.jpg" } },
    "body": { "text": "Gold is down today. See the full analysis." },
    "footer": { "text": "Daily market update" },
    "action": { "name": "cta_url",
                "parameters": { "display_text": "View analysis", "url": "https://example.com/analysis" } } } }

A tap comes back on your webhook as a message.received of type interactive, carrying button_reply or list_reply with the id you set, so you match on ids, not on the words the customer saw. call works like cta_url with a phone number. The header may also be an image, video or document (by media_id or link) on every interactive type, including cta_url and call: the customer sees the picture, the text and the button in one message.

Picture plus a button? Either send type: "image" with buttons (see Media), or type: "interactive" with an image header, as above.

Interactive limitValue
Reply buttons3; title 20 characters, id 256
Body / header / footer1,024 / 60 / 60 characters
cta_url / call button text (display_text)20 characters
ListUp to 10 sections and 10 rows in total; opener button 20, section title 24, row title 24, row description 72, row id 200 characters

Location, poll and reaction

{ "to": "+919876543210", "type": "location",
  "location": { "latitude": 17.385, "longitude": 78.4867,
                "name": "Shop 12, Main Road", "address": "Vizianagaram" } }

{ "to": "+919876543210", "type": "poll",
  "poll": { "question": "Which slot suits you?",
            "options": ["9am", "10am"], "allow_multiple": false } }

{ "to": "+919876543210", "type": "reaction",
  "reaction": { "message_id": "cmuy…", "emoji": "👍" } }

Location name up to 200 characters, address up to 500. A poll has a question of up to 300 characters and 1 to 12 options of up to 200 (a broadcast poll needs at least 2); each vote comes back as a poll.vote webhook.

Post to all followers (broadcast)

The same as the Broadcast button in the app: every follower of your channel (or only the followers carrying one tag) gets the message in your channel's chat, with a push notification.

POST /v1/broadcasts → 200. Scope messages:send. You do not send phone numbers: the audience is your followers, and following is their consent.

curl -X POST https://api.pitta.pro/v1/broadcasts \
  -H "Authorization: Bearer $PITTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi {name}, our new menu is live. Tap below to see it.",
    "importance": "important",
    "buttons": [ { "type": "url", "title": "See menu", "url": "https://example.com/menu" } ]
  }'

# up to 100 followers: sent now, counts are final
{ "total": 86, "sent": 85, "failed": 1, "broadcast_id": "5c0e…" }

# more than 100 followers: queued and fanned out in the background
{ "total": 12480, "sent": 0, "failed": 0, "queued": true, "broadcast_id": "9a41…" }
FieldTypeNotes
textstringUp to 4,096 characters (*bold*, _italic_, line breaks). {name} is replaced by each follower's name ("there" when we do not know it). With media, it becomes the caption.
importancestringregular (default) or important (the follower's Important tab).
segmentstringOptional. Only followers carrying this tag. A tag nobody carries reaches nobody (total: 0).
buttonsarrayUp to 3 footer buttons, exactly as in a text message. They go with a text or a media broadcast; they are ignored when location or interactive is set, and a poll is sent without them.
mediaId, mediaKind, filenamestringOptional. Send a file instead of plain text: a media_id from an upload and its kind (image, video, audio, document).
pollobjectOptional. { question, options, allow_multiple }, as in a poll message, with at least 2 options (fewer is refused with 403). A poll replaces the other content; any text goes out first as its own message. Votes from every recipient share the broadcast_id.
location, interactiveobjectOptional. The same blocks as in POST /v1/messages.
aiContentbooleanOptional. The AI content label. Note the camelCase spelling on this endpoint (and on mediaId / mediaKind); unknown fields are dropped silently.
  • Sync or queuedWith 100 followers or fewer in the audience, the answer comes after the send and its counts are final. Above that, the answer is immediate with queued: true and sent: 0; the messages go out over the next moments and arrive as normal message.status webhooks.
  • One request, one thread eachA broadcast counts as one request against your rate limit. Each follower gets their own copy in their own chat with you, and their replies come back as ordinary message.received events.
  • Followers onlyPeople you opted in through the API but who do not follow you are not part of a broadcast. To reach a list of numbers, use POST /v1/messages/batch.

Send many messages at once

POST /v1/messages/batch → 200. Up to 1,000 messages per request, body up to 8 MB. Each entry is exactly a POST /v1/messages body and must carry its own client_msg_id, unique within the batch (a missing or repeated one is 400 for the whole request). Each entry is validated up front: a malformed entry makes the whole request 400. Once validated, messages are independent: one failing to send does not fail the others (a number in the wrong format, for example, fails only its own entry with invalid_phone).

curl -X POST https://api.pitta.pro/v1/messages/batch \
  -H "Authorization: Bearer $PITTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [
    { "to": "+919876543210", "type": "text", "text": { "body": "Your EMI is due on the 15th." }, "client_msg_id": "q27812" },
    { "to": "+919876543211", "type": "text", "text": { "body": "Your EMI is due on the 18th." }, "client_msg_id": "q27813" }
  ] }'

The answer has one result per message, in request order, with the status that message would have got on its own:

{ "results": [
    { "client_msg_id": "q27812", "status": 201, "id": "cmuy…", "message_status": "sent", "conversation_id": "cmuy…", "type": "text" },
    { "client_msg_id": "q27813", "status": 404, "error": { "code": "not_on_pitta", "message": "+91… is not on Pitta. …" } },
    { "client_msg_id": "q27814", "status": 200, "id": "cmux…", "duplicate": true },
    { "client_msg_id": "q27815", "status": 429, "retry_after": 60, "error": { "code": "recipient_rate_limited", "message": "…" } } ],
  "summary": { "total": 4, "accepted": 2, "failed": 2 } }
StatusCodeMeans
201Sent.
200duplicate: trueThat client_msg_id was already sent; the original id is returned and nothing is sent twice.
400invalid_phone, invalid_requestBad number, or content that could not be sent (a link we could not fetch, a bad media_id).
403not_opted_in, opted_outNot allowed to message this person.
404not_on_pittaNo Pitta account on that number.
409duplicate_recipientSame number twice in one batch; send the second in another request.
409duplicate_messageThe same text to this person within 20 seconds (and they have not written since). The earlier copy was delivered: do not retry.
429recipient_rate_limitedMore than 30 messages a minute to this person; retry after retry_after seconds.

A suspended channel never reaches the entries: the whole request is refused with 403 business_suspended. The codes above come from the normal batch path. A batch that contains a reaction, a reply_to or an allow_request entry is sent one message at a time, and its failed entries carry broader codes instead: not_found, forbidden, conflict, rate_limited (without retry_after), invalid_request, send_failed, duplicate_message; a repeated client_msg_id there comes back as 201 without duplicate. Branch on status first and treat code as detail.

Your channel's rate limits count messages, not requests: a batch of 1,000 uses 1,000. For volume, one batch beats many parallel single sends.

Upload media

For files that are not at a public URL, upload them first, then send with media_id. Three steps: ask for an upload URL, PUT the bytes straight to storage, commit.

# 1. init (kind: image | video | audio | document)
curl -X POST https://api.pitta.pro/v1/media \
  -H "Authorization: Bearer $PITTA_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "image", "mime": "image/jpeg", "filename": "promo.jpg" }'
# 201 { "media_id": "cmv…", "upload_url": "https://…", "storage_key": "…" }

# 2. PUT the file to upload_url
curl -X PUT "$UPLOAD_URL" --data-binary @promo.jpg -H "Content-Type: image/jpeg"

# 3. commit: checks the file arrived (and scans it for AI provenance)
curl -X POST https://api.pitta.pro/v1/media/$MEDIA_ID/commit -H "Authorization: Bearer $PITTA_KEY"
# 201 { "media_id": "cmv…", "committed": true, "size_bytes": 184233, "ai_content": false }

Uploads may be up to 100 MB. GET /v1/media/{id} returns a short-lived download link, { "url": "…" }.

Typing and receipts

CallDoes
POST /v1/messages/{id}/readMarks the customer's messages in that message's thread read: their ticks turn blue.
POST /v1/conversations/{id}/readThe same, addressed by conversation.
POST /v1/messages/{id}/typing
{"typing":true,"ttl_seconds":25}
Shows "typing…" on that thread while your system composes an answer. It clears itself after ttl_seconds (at most 25); send again to extend, or "typing": false to stop.
POST /v1/conversations/{id}/typingThe same, addressed by conversation.
POST /v1/messages
{"status":"read","message_id":"…",
"typing_indicator":{"type":"text"}}
The WhatsApp-shaped alias: marks the message read and, optionally, shows typing.

Receipts run in both directions. When your webhook answers 2xx to a message.received event, that inbound message is marked delivered for the customer; replying through the API marks it read. Customers see the same ticks whether you answer from the app or from your own software.

Message status

curl https://api.pitta.pro/v1/messages/cmuy… -H "Authorization: Bearer $PITTA_KEY"

{ "id": "cmuy…", "status": "read", "type": "text", "conversation_id": "cmus…",
  "sent_at": "2026-10-11T09:41:01.994Z",
  "receipts": [ { "state": "delivered", "at": "…" }, { "state": "read", "at": "…" } ] }

status is one of queued, sent, delivered, read, failed. Rather than poll, subscribe to message.status. Scope messages:read; an id that is not your channel's is 404.

Webhooks

Add an endpoint in Channel → Developer → Webhooks, or with the API, and subscribe to the events you want. Every delivery is a POST with this envelope:

{
  "id": "evt_3b1f…",
  "type": "message.received",
  "created_at": "2026-10-11T09:41:02.118Z",
  "business_id": "cmtd…",
  "data": {
    "conversation_id": "cmus…",
    "message": {
      "id": "cmuz…",
      "from": "+919876543210",
      "timestamp": "2026-10-11T09:41:01.994Z",
      "type": "text",
      "text": { "body": "Is the blue one still there?" }
    }
  }
}
EventFires when
message.receivedA customer sends you anything: text, media (with a short-lived download url), a location, a tap on a button or list row (interactive.button_reply / list_reply), an order or booking summary.
message.statusOne of your messages becomes sent, delivered, read or failed (a declined message request, with error.code).
reaction.addedSomeone reacts to a message.
poll.voteSomeone votes in your poll, or takes a vote back (selected: false).
user.opted_inSomeone starts following you, accepts your message request, or you opt them in with POST /v1/contacts/opt-in.
user.opted_outSomeone unfollows (or you remove them): stop sending.
order.createdA customer placed an order. data: { order }, the same object as GET /v1/orders/{id}.
order.updatedAn order changed. data: { order, change }, where change is status, payment or items.

The two user.* events carry only the number, "data": { "phone": "+919876543210" }, and fire the same way whether the change came from the person or from your own API call, so key your logic on the number, not on who triggered it. A webhook created without events gets message.received, message.status and reaction.added. A webhook subscribed to all six non-order events also receives the order events.

Managing webhooks with the API

curl -X POST https://api.pitta.pro/v1/webhooks \
  -H "Authorization: Bearer $PITTA_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://you.example.com/pitta/webhook",
        "events": ["message.received", "message.status", "user.opted_out", "order.created"] }'
# 201 { "id": "…", "url": "…", "events": [ … ], "signing_secret": "whsec_…" }   shown once
CallDoes
GET /v1/webhooksLists your webhooks: id, url, events, is_active.
POST /v1/webhooks/{id}/rotate-secretIssues a new signing secret (returned once).
POST /v1/webhooks/{id}/testSends a test message.status event (data.test: true) to every active webhook of the channel subscribed to message.status, not only this one. An inactive webhook, or one not subscribed to message.status, gets nothing.
GET /v1/webhooks/deliveries?limit=50Recent delivery attempts (up to 200): event, status, attempt, response status.
POST /v1/webhooks/deliveries/{id}/replaySends one delivery again.

The URL must be public http(s). Answer 2xx within 10 seconds; anything else (a redirect included) is retried with backoff: about 30 s, 2 min, 10 min, 1 h, 6 h, 12 h and 24 h after successive failures, plus up to 40% jitter, for 8 attempts in all; then the delivery is marked dead. After 20 dead deliveries in a row the webhook is switched off (any successful delivery resets the count). Delivery is at-least-once, so de-duplicate on the event id; ordering is best-effort.

A webhook and the channel's auto-reply are mutually exclusive: only one can own inbound. Turn auto-reply off before you add a webhook; adding one from the app or portal while auto-reply is on is refused (the API endpoint does not check this yet). Once a webhook is active, in-app customer chats are hidden by default so your system owns the conversation (you can switch them back on, read-only, from the Webhook or Profile screen), and the in-app composer is locked with a banner so a customer never gets two answers to one question. To reply, call POST /v1/messages with to set to message.from and, if you want the quote, reply_to set to message.id.

Verifying a delivery

Every delivery carries a Stripe-style signature over the raw body. Verify it before you trust the payload, and compare in constant time.

X-Q-Signature: t=<unix seconds>,v1=<hex HMAC_SHA256(secret, "<t>.<raw body>")>
X-Q-Event-Type: message.received
X-Q-Delivery-Id: <delivery id>
// Node: verify, with a five-minute tolerance against replay
const { createHmac, timingSafeEqual } = require('crypto');

function verify(secret, rawBody, header, tolerance = 300) {
  const p = Object.fromEntries(header.split(',').map(kv => kv.split('=')));
  const t = parseInt(p.t, 10);
  if (!t || !p.v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > tolerance) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(p.v1), b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Sign against the raw request body, before any JSON parsing: a re-serialised body will not match. Answer 2xx quickly and do your work afterwards; a non-2xx is retried, and a 2xx on message.received is what marks the customer's message delivered.

Contacts

CallDoes
GET /v1/contacts/{phone}{ phone, registered, reachable, opted_in, opted_out, can_opt_in }. registered: has a Pitta account (a send without one is 404). reachable: has a signed-in phone that can get a push; false means the message waits in the app. can_opt_in: false: the person opted out in the app themselves; stop asking. Scope contacts:read.
POST /v1/contacts/opt-inRecords consent you collected yourself: { "phone", "source", "country"? } → { phone, opted_in: true, opted_in_at }, and fires user.opted_in. Refused with 403 when the person opted out in the Pitta app (unfollowed, or declined your request): only they can opt back in, by following you again.

Check registered before a bulk run: sending to numbers that never joined is the one mistake that looks like success and isn't. Lookups are capped at 500 distinct numbers per key per day (repeats are free); past that the answer is 429 with Retry-After until midnight UTC.

Orders

Orders customers place in the app, with the customer's name and number. Read-only; scope orders:read. To hear about orders as they happen, subscribe a webhook to order.created and order.updated.

curl "https://api.pitta.pro/v1/orders?status=placed&limit=25" -H "Authorization: Bearer $PITTA_KEY"
# 200 { "data": [ order, … ], "next_before": "2026-10-07T06:35:09.754Z" }   newest first
# last page: "next_before": null

curl https://api.pitta.pro/v1/orders/cmux… -H "Authorization: Bearer $PITTA_KEY"
# 200 order

{ "id": "cmux…", "status": "placed", "total": "₹648", "tax": "₹27", "fulfilment": "pickup",
  "address": null, "payment_status": "unpaid", "payment_method": "cash", "note": null,
  "conversation_id": "cmus…", "created_at": "2026-10-07T06:35:09.754Z",
  "items": [ { "id": "li_…", "product_id": "p_…", "title": "Basmati Rice, 5 kg", "price": "₹549", "qty": 1, "options": null } ],
  "customer": { "user_id": "cmus…", "name": "Sahin", "phone": "+919876543210" } }

Query: status (placed, accepted, packed, out_for_delivery, completed, rejected, cancelled), limit (1 to 100, default 25), before (pass the previous page's next_before). next_before is null once a page comes back with fewer than limit orders; if the last page is exactly full, the next call returns "data": [] with null. Pitta holds no money on an order: payment_status and payment_method record what the customer and the shop agreed.

Profile

GET /v1/profile reads your channel's public profile (scope profile:read); PUT /v1/profile updates it (scope profile:write) and returns the updated profile. Every field is optional; send only what you change.

curl -X PUT https://api.pitta.pro/v1/profile \
  -H "Authorization: Bearer $PITTA_KEY" -H "Content-Type: application/json" \
  -d '{ "about": "Fresh bakes every morning since 1998.",
        "hours": { "mon": "8:00 to 21:00", "sun": "Closed" },
        "website": "https://example.com" }'
FieldNotes
name, category, aboutChannel name (up to 80; letters, digits, spaces, dots, hyphens), category (80), about (500).
phone, email, website, address, cityPublic contact details.
lat, lngMap pin for "Near me"; null clears it.
hoursmon … sun → short text.
productsYour catalogue. Sending it replaces the whole catalogue: title, description, price, mrp, image_url, images, category, in_stock, stock_count, kind (product or service), duration_mins, variants and more.
discoverable, showFollowers, chatEnabled, autoReplyEnabled, autoReplyTextChannel switches. discoverable: true needs a verified channel; autoReplyEnabled: true is refused while a webhook is active.

The same endpoint also takes the website settings the app edits (template, colours, SEO, pages, languages). Field names follow the app's spelling, so a few are camelCase as shown.

All endpoints

Every Business API call, authenticated with Authorization: Bearer <key_id>:<secret> against https://api.pitta.pro.

CallScopeSection
POST /v1/messagesmessages:sendSend a message
POST /v1/messages/batchmessages:sendSend many at once
POST /v1/broadcastsmessages:sendPost to all followers
GET /v1/messages/{id}messages:readMessage status
POST /v1/messages/{id}/read
POST /v1/conversations/{id}/read
messages:sendTyping & receipts
POST /v1/messages/{id}/typing
POST /v1/conversations/{id}/typing
messages:sendTyping & receipts
POST /v1/contacts/opt-inmessages:sendContacts
GET /v1/contacts/{phone}contacts:readContacts
POST /v1/media
POST /v1/media/{id}/commit
media:writeUpload media
GET /v1/media/{id}media:readUpload media
GET /v1/orders
GET /v1/orders/{id}
orders:readOrders
GET /v1/profile
PUT /v1/profile
profile:read
profile:write
Profile
POST /v1/webhooks
POST /v1/webhooks/{id}/rotate-secret
webhooks:writeWebhooks
GET /v1/webhooks
POST /v1/webhooks/{id}/test
GET /v1/webhooks/deliveries
POST /v1/webhooks/deliveries/{id}/replay
any keyWebhooks

There is no stats or insights endpoint in the Business API today: follower and message analytics are in the app and the portal. To count delivery yourself, use message.status webhooks.

Errors

CodeMeans
400The request is wrong: unknown type, a number without its country code, a fourth button, a body over 4,096 characters, a batch entry without client_msg_id.
401Missing, malformed, revoked or wrong key.
403Not allowed. "Recipient has not opted in" (record consent, or send with allow_request); the person opted out or declined your request; a second message request while the first is unanswered; the person does not accept messages from new businesses; the key is missing a scope; or the channel is suspended (code: "business_suspended", for the whole request, a batch included).
404That number has no Pitta account ("… is not on Pitta"), or the message, conversation, media, order or webhook id is not yours.
409code: "duplicate_message": the same text to the same person within 20 seconds (unless they wrote back in between). The first copy was delivered, so this is not a failure: treat it as sent and do not retry. (In a batch, also duplicate_recipient.)
429Too many requests. Your channel's per-minute or per-day limit, and too many requests in progress at once: a Retry-After header and the same retry_after in the body. The daily contact-lookup cap: the Retry-After header only. More than 30 a minute to one customer: retry_after (60) in the body only, with no header (in a batch, on that entry). Wait that many seconds, then retry.

Every error carries a human sentence in its body (message). Log it: each one is written to be read by the person debugging, not by a parser. In a batch, each failed entry also has an error.code (see Send many at once for which ones); a single send carries code where one exists (duplicate_message, business_suspended).

Limits

LimitValue
API requests120 a minute and 20,000 a day per channel, shared by all of its API keys. The minute resets on the minute, the day at 00:00 UTC. A batch counts each message; a broadcast counts once.
Rate-limit headersX-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (seconds to the next minute), X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day
Requests in progress64 at once per channel per API server; past that, an immediate 429 with Retry-After: 1
Messages to one customer30 a minute
Batch1,000 messages, 8 MB per request (other requests 2 MB)
Contact lookups500 distinct numbers per key per day
Text body4,096 characters
Footer buttons3 per message
Message requestsOne unanswered request per person
Message retentionMessages are kept on record and stay visible in the chat; they do not expire.
PriceFree. No per-message fee, no packages.

Speed and retries

  • Keep one API key and reuse itThe first request with a key runs a slow, deliberately expensive secret check (about 0.1 to 0.5 s); later requests with the same key are checked quickly for 24 hours. Minting a fresh key per job makes every job slow. Revoking a key takes effect immediately.
  • Server-TimingEvery response carries Server-Timing: app;dur=<ms>, the time Pitta spent on it, so you can tell our time from the network's.
  • Retry safely with client_msg_idIt is idempotent forever, per channel: a repeat returns the original message and sends nothing (unless the person has since opted out: then it is 403). Retry a timed-out send with the same id. Never retry a 409 duplicate_message: the person already has it.
  • Back off on 429Honour Retry-After. For volume, use batch rather than many parallel single requests; HTTP/2 is supported.

Building something?

Tell us what you are wiring up and we will help you get the first message through — including the parts of the consent model that are easier to ask about than to read.

Chat with us