Chat Endpoints

Chat endpoints require the chat scope. Conversations are between game owners and playtesters who have interacted through accepted playtests.

List Contacts

GET /api/v1/chat/contacts

Scope: chat

Returns your chat contacts. The response shape varies by role.

Response (Game Owner)

{
  "data": {
    "contacts": [
      {
        "id": "playtester-uuid",
        "displayName": "TestGamer42",
        "chatMode": "free",
        "isUnlocked": true,
        "unreadCount": 2,
        "lastMessageAt": "2026-03-01T16:00:00.000Z",
        "lastMessagePreview": "Thanks for the great playtest!",
        "conversationId": "conv-uuid"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}

Response (Playtester)

{
  "data": {
    "contacts": [
      {
        "id": "game-owner-uuid",
        "displayName": "Indie Dev Studio",
        "companyName": "Indie Dev Studio",
        "isUnlocked": true,
        "unreadCount": 0,
        "lastMessageAt": "2026-03-01T16:00:00.000Z",
        "lastMessagePreview": "Thanks for the great playtest!",
        "conversationId": "conv-uuid"
      }
    ],
    "chatDisabled": false
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}

Contacts are sorted by most recent message first. conversationId is null if no conversation exists yet. For playtesters, chatDisabled indicates whether their chat is disabled.

---

Get Conversation

GET /api/v1/chat/conversations/:id

Scope: chat

Returns messages in a conversation. The :id parameter is the conversation UUID (not a user ID).

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Max 100
cursor	string	—	Pagination cursor

Response

{
  "data": {
    "messages": [
      {
        "id": "msg-uuid",
        "senderType": "game_owner",
        "senderId": "go-uuid",
        "content": "Thanks for the great playtest!",
        "readAt": null,
        "createdAt": "2026-03-01T16:00:00.000Z"
      },
      {
        "id": "msg-uuid-2",
        "senderType": "playtester",
        "senderId": "pt-uuid",
        "content": "Happy to help! Let me know if you need more testing.",
        "readAt": "2026-03-01T16:10:00.000Z",
        "createdAt": "2026-03-01T16:05:00.000Z"
      }
    ],
    "isBlocked": false
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z",
    "cursor": "eyJpZCI6ImFiYzEyMyJ9",
    "hasMore": false
  }
}

Messages are returned in chronological order (oldest first). isBlocked is true if you have blocked this contact.

---

Send Message

POST /api/v1/chat/conversations/:id/messages

Scope: chat

The :id parameter is the conversation UUID.

Request Body

Field	Type	Required	Description
content	string	Yes	Message text (max 5000 chars)

cURL

curl -X POST https://app.weplaytestgames.com/api/v1/chat/conversations/conv-uuid/messages \
  -H "Authorization: Bearer wpg_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Thanks for the feedback!"}'

TypeScript

const response = await fetch(
  `https://app.weplaytestgames.com/api/v1/chat/conversations/${conversationId}/messages`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ content: 'Thanks for the feedback!' }),
  },
);

Response

{
  "data": {
    "message": {
      "id": "msg-uuid",
      "conversationId": "conv-uuid",
      "senderType": "game_owner",
      "senderId": "go-uuid",
      "content": "Thanks for the feedback!",
      "readAt": null,
      "createdAt": "2026-03-02T12:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}

---

Get Unread Count

GET /api/v1/chat/unread-count

Scope: chat

Response

{
  "data": {
    "unreadCount": 3
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}