Send messages

POST /api/v1/messages/send — enqueue encrypted messages for delivery, with per-message validation and a success/failure split response.

POST /api/v1/messages/send queues encrypted messages for delivery. Send up to 50 messages per call; the API validates each one independently and returns a partial-success envelope. A 202 Accepted means “accepted into the queue” — delivery to the recipient is asynchronous and not confirmed by this endpoint.

Request

POST /api/v1/messages/send HTTP/1.1
Host: privacyflow.app
Authorization: Bearer pf_live_your_key_here
Content-Type: application/json

{
  "messages": [
    {
      "appId": "app_123",
      "contactId": "+12025550104",
      "messenger": "signal",
      "message": "Your order #4421 has shipped."
    }
  ]
}

Auth required. The body must be a JSON object with a messages array — top-level arrays and bare objects are rejected with 400.

curl

curl -s -X POST https://privacyflow.app/api/v1/messages/send \
  -H "Authorization: Bearer $PRIVACYFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "appId": "'"$PRIVACYFLOW_APP_ID"'",
        "contactId": "+12025550104",
        "messenger": "signal",
        "message": "Your order #4421 has shipped."
      }
    ]
  }'

Request body: SendMessageInput

Each item in messages:

Batch constraints

• The messages array must contain at least one item (400 "At least one message is required").
• The array must contain at most 50 items (400 "Batch size exceeds maximum of 50 messages").
• Each item is validated independently. Invalid items are returned in failedMessages with an error string; valid ones enqueue normally. The HTTP status reflects the batch-level outcome, not per-message.

Validation errors per message

Contact ID formats per messenger

The API validates only that contactId is non-empty. The actual format is enforced downstream by each messenger. Mismatched formats produce per-message failures in the response rather than a 400 at the API layer.

Character limits per messenger

The API caps message at 10,000 characters. Each messenger has a smaller display limit and will reject (or truncate) over-length payloads downstream. The Agent Zero channel splits long replies before sending — your client should do the same when you expect long output.

Group replies

For a reply to land in the same thread as a group inbound, pass the groupId from the polled message:

{
  "messages": [
    {
      "appId": "app_123",
      "contactId": "05abcd…",
      "messenger": "session",
      "message": "Got it — assigning an agent.",
      "groupId": "group_abc123"
    }
  ]
}

For DMs, omit groupId entirely. Sending a groupId against a direct message is undefined.

Response

202 Accepted:

{
  "successfulMessages": [
    {
      "messageId": "8a5b3c0e1d2f4a6b8c0d1e2f3a4b5c6d",
      "appId": "app_123",
      "contactId": "+12025550104",
      "messenger": "signal"
    }
  ],
  "failedMessages": [
    {
      "appId": "app_123",
      "contactId": "invalid-format",
      "messenger": "signal",
      "error": "Missing required field: contactId"
    }
  ],
  "totalAccepted": 1,
  "totalFailed": 1
}

Response schema

Status codes

Rate-limit accounting

The send limit counts messages in the batch, not requests. A 50-message POST consumes 50 units. If the batch alone would exceed the remaining budget the entire request is rejected before any enqueue — see rate limiting.

What 202 doesn’t tell you

A 202 response means the API accepted the batch and handed it to BullMQ. It does not mean the message was delivered to the recipient. Downstream delivery happens asynchronously with up to 3 attempts and exponential backoff. The public API surfaces no delivery-status endpoint — if you need confirmation of delivery, build it on your side (e.g., an inbound /delivered command from the recipient).