Send Message

POST /api/v1/messages — 🔑 Bearer · Rate limit: 10 req / minute · Kill-switched

The most complex endpoint in the message module. Validates a long chain of preconditions (sender email verification, receiver active, block list, DM enabled, no vacation, dmType matches creator's config, no duplicate-window collision, no pending paid-DM concurrency violation, sufficient wallet balance for paid DMs), then atomically creates the Message, escrow record (paid DMs), and MessageRuleSnapshot. Content moderation runs after persistence; flagged messages get quarantined (silent to the fan — they see "sent").

Request

Body — SendMessageDto

Response

201 Created — ApiResponseOf<SendMessageResponseDto>

{
  "success": true,
  "data": {
    "messageId": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "status": "ESCROWED"
  }
}

Errors

Side effects

1. Self-message guard + content non-empty.
2. Sender email verification gate (404/403 if missing or unverified).
3. Receiver gate — must exist AND User.status = ACTIVE.
4. Block check — BlockList { ownerId: receiverId, blockedId: senderId }.
5. Creator DM config — CreatorProfile.dmActive AND not vacationMode AND dmType matches.
6. Duplicate window — searchContent projection match within messaging.duplicate_window_seconds.
7. Free DM rate limits (when dmType = FREE) — Redis INCR with TTL on free_dm:<senderId>:<utcDate> AND free_dm:<senderId>:<receiverId>:<utcDate>. Rollback DECR on over-limit. Reject if Redis offline.
8. Get-or-create ChatSession for the (fan, creator) pair (bidirectional match).
9. Resolve timeoutHours — body or dm.timeout_hours default.
10. Paid DM extra checks (when dmType !== 'FREE' && price > 0):
    • price >= activeDMPackage.price (Decimal comparison).
    • Pending paid concurrency cap — count of PENDING/ESCROWED paid DMs from sender to receiver must be 0.
    • Pre-escrow balance check — wallet exists, not frozen, balance >= price.
    • Resolve commissionRate from creator.commission_<level> config (per creator level).
11. Atomic create: insert Message (encrypted content, plaintext searchContent, priceSnapshot, commissionRate, expiresAt).
12. Create escrow for paid DMs via escrowService.createEscrow — on failure, delete the orphan message + new chat session for recovery.
13. Snapshot — MessageRuleSnapshot.create (fire-and-forget — failure logs but doesn't block).
14. Moderation — moderateContent(content) against active ModerationRule rows (Redis-cached, DB fallback, hardcoded fallback). On flag:
    • Transition message to QUARANTINED.
    • Emit DSA Art. 17 sorService.emit (fire-and-forget audit).
    • Return { messageId, status: 'PENDING' } to the fan (silent quarantine).
15. Status transition (no flag) — paid → ESCROWED, free → DELIVERED.
16. Notify creator via notificationService.send({ eventKey: 'new_message_creator', deepLink: '/messages/<sessionId>' }) (fire-and-forget; failure logged).
17. Update ChatSession.lastMessageAt for conversation ordering.
18. Increment messageSentTotal Prometheus counter.
19. Return { messageId, status }.

Code samples

# Free DM
curl -X POST https://api.bio.re/api/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "receiverId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "content": "Loved your latest post!",
    "dmType": "FREE"
  }'

# Paid DM
curl -X POST https://api.bio.re/api/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "receiverId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "content": "Quick question about your service.",
    "dmType": "SINGLE_PAY",
    "price": "5.00",
    "timeoutHours": 48
  }'

type DmType = 'FREE' | 'SINGLE_PAY' | 'PER_MESSAGE';

type SendMessageInput = {
  receiverId: string;
  content: string; // 1-2000 chars
  dmType: DmType;
  price?: string;        // required when dmType !== 'FREE'
  timeoutHours?: number; // 1-720, default from dm.timeout_hours admin config
};

type SendMessageResult = {
  messageId: string;
  status: 'PENDING' | 'ESCROWED' | 'DELIVERED';
};

async function sendMessage(accessToken: string, input: SendMessageInput): Promise<SendMessageResult> {
  const res = await fetch('https://api.bio.re/api/v1/messages', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    throw Object.assign(new Error(json?.error?.message ?? 'Send failed'), {
      code: json?.error?.code,
    });
  }
  return json.data;
}

import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useSendMessage() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async (input: SendMessageInput) => {
      const res = await fetch('/api/v1/messages', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(input),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Send failed'), {
          code: json?.error?.code,
          i18nKey: json?.error?.i18nKey,
        });
      }
      return json.data as SendMessageResult;
    },
    onSuccess: () => {
      // Multi-resource invalidation — message lists, conversations, unread, balance (paid DMs)
      qc.invalidateQueries({ queryKey: ['messages'] });
      qc.invalidateQueries({ queryKey: ['wallet', 'balance'] });
      qc.invalidateQueries({ queryKey: ['wallet', 'activity'] });
    },
  });
}

Try it

curl -X POST "https://loading/api/v1/messages" \  -H "Content-Type: application/json" \  -d '{    "receiverId": "cuid_creator_123",    "content": "Hey, loved your latest post!",    "dmType": "FREE"  }'

{
  "success": true,
  "data": {
    "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
    "status": "PENDING"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Source