Shop API

Send a message

Send customer messages with the usual shop messaging limits.

Send a text message as your shop using a key with themessages:write permission. Create a new key with this permission if your existing key does not have it.

Endpoint and request

POST https://popbob.gg/api/v1/messages
Authorization: Bearer pb_live_your_key_here
Content-Type: application/json

{
  "userId": "customer-account-id",
  "content": "Your order is ready for delivery."
}

Use the customer's account ID (the order'saccountUsername field). They must have purchased from the shop connected to your key; cancelled orders also qualify. The endpoint creates or reuses that customer's shop conversation.

content must be a non-empty string of at most 2,000 characters. Optionally include replyToMessageId to reply to a message in the same conversation. Attachments are not supported by this endpoint.

Successful response

A successful send returns 200:

{
  "chatId": "67f15e3c3d6d55ab781ac123",
  "message": {
    "_id": "67f15e3c3d6d55ab781ac456",
    "senderType": "shop",
    "senderId": "shop-owner-account-id",
    "content": "Your order is ready for delivery.",
    "images": [],
    "createdAt": "2026-10-18T12:00:00.000Z"
  }
}

The message object also includes the usual chat metadata. Messages appear in the existing conversation immediately through WebSocket events and use the usual offline notifications.

Limits and errors

The API key's 60 requests per minute limit applies. Messages also share the shop's 60 messages per minute and 1,000 messages per UTC day limits across all keys and Superpanel users. A limited request returns 429 with a Retry-After header.

Contacting more than three distinct customers without an order in the last seven days during one UTC day suspends shop messaging. API messages use the same recipient checks. Failed sends can consume rate limits; do not retry repeatedly.

Invalid input returns 400. Invalid keys return401. Missing permissions, shop or owner bans, messaging suspension, and recipients without a purchase return403. Missing shops, customers, or reply messages return404. Replies cannot reference another conversation.

Sending is not idempotent. Retrying after an uncertain response can send the same message twice.