Messages to clients

Your app can send an in-app message from the business that connected it to one of the business’s own clients. The message lands in the client’s United Pet Club inbox, in a conversation with the business; the client’s own notification settings decide whether they also get a push notice. Nothing goes out by e-mail or SMS, and your app cannot message anyone who is not the business’s client.

Access

• A token from the authorization-code grant. A client-credentials token answers 403 0010010000406.
• The business must keep a valid payment card on file; without one, 403 0010010000407.
• Scope communication:send, declared by your app and granted by the business on the consent page — see Business resources.

Send a message

POST /api/communication/v1/messages
Content-Type: application/json
Idempotency-Key: 4d6c0a52-reminder-2026-10-18

{
  "clientId": "8e2b7d14-3c5a-4f90-b1e6-7a0d9c4f2e58",
  "subject": "Your next appointment",
  "body": "Hi Jane, Biscuit is due for a groom. Reply here to pick a time."
}

Field	Required	Meaning
clientId	yes	The client, as the business’s client list names it. Never a profile or an address.
body	yes	The text, at most 20,000 characters.
subject	no	At most 400 characters. Names a new conversation; ignored while the conversation with the client is open.
channel	no	Only IN_APP (the default). Anything else is 400.
idempotencyKey	no	At most 100 characters; the Idempotency-Key header works too, and the body value wins. A retry with the same key sends nothing new and answers the first send.

The sender is always the business the token acts for; the request cannot name another.

HTTP/1.1 201 Created

{
  "id": "c41e7a09-5b2d-4f6e-8a13-9d0b2c7e4f61",
  "conversationId": "2a9f6c3e-1d84-4b70-a5e2-6c0d8b1f3e97",
  "clientId": "8e2b7d14-3c5a-4f90-b1e6-7a0d9c4f2e58",
  "channel": "IN_APP",
  "status": "SENT",
  "postedAt": "2026-10-18T15:04:22Z",
  "conversationStarted": true,
  "replayed": false
}

status is SENT: the message is stored and queued to the client’s inbox. conversationStarted is true when this message opened a new conversation. A replay of an earlier key answers 200 with replayed: true and the first send’s ids and time. That holds for two sends with the same key that arrive at the same moment too: one is stored, the other answers it as a replay.

What the client controls

• If the client blocked the business (or the business blocked the client), opted out of the business’s messages or of all broadcasts, or left the conversation, the send answers 403. The answer is the same in every case, on purpose.
• A business that was paused for complaints about its broadcasts cannot send through an app either (403 Conversation_Messaging_VL_BroadcastPaused_RJ).

Daily caps

Across all of the business’s apps:

• at most 50 different clients per business in 24 hours (a client already messaged in that time does not count again);
• at most 5 messages to one client in 24 hours.

Both count the last 24 hours. Past either, the send answers 429 without Retry-After: do not retry it in a loop. This is not the per-minute rate limit.

Errors

Status	platformResponseCode	Cause	What to do
400	0010010000400	No clientId or body, a channel other than IN_APP, a key longer than 100 characters.	Fix the request.
400	the platform’s validation code	body or subject too long.	Fix the request.
403	Conversation_Messaging_VL_Authorization_RJ	The client blocked or opted out, left the conversation, or the business has no card on file.	Do not retry.
403	Conversation_Messaging_VL_BroadcastPaused_RJ	The business is paused for complaints.	Do not retry; the business must resolve it.
404	Conversation_Messaging_GT_Resource_FL	Not one of this business’s clients.	Check the client id.
409	Conversation_Messaging_UP_State_RJ	The client is a guest record with no United Pet Club account, so there is no inbox to deliver to; or the idempotency key was already used for another client.	Contact the client another way; use a new key per message.
429	the platform’s rate-limit code	A daily cap. (The per-minute rate limit is 0010010000429 with Retry-After.)	Send later.
503	Conversation_Messaging_GT_Dependency_FL	The client could not be checked right now. Nothing was sent.	Retry with backoff and the same key.

Everything else follows Errors.