Chat API: REST endpoints and WebSocket protocol

The Chat API lets companies open private conversations with individual candidates or broadcast group chats to all applicants for a vacancy. Messages are delivered in real time over a STOMP WebSocket connection; REST endpoints handle chat creation, history retrieval, and state management.

REST endpoints

All endpoints are under /api/chats and return JSON.

Create a private chat

Opens a one-to-one chat between a company and a specific candidate for a given vacancy. Only users with the EMPRESA role can call this endpoint; the company is derived from the vacancy owner.

POST /api/chats/crear
Content-Type: application/json

{
  "vacanteId": "42",
  "candidatoId": "17"
}

Request body

vacanteId

string

required

ID of the vacancy that this chat is associated with.

candidatoId

string

required

ID of the candidate to start the chat with. The candidate must be an active user.

Responses

Code	Meaning
`200`	Chat created. Returns the `ChatDTO` object.
`400`	Invalid data or the candidate’s account is banned.
`403`	Caller does not have the `EMPRESA` role.

Create a group chat for a vacancy

Creates a single group chat for all candidates who have applied to a vacancy.

POST /api/chats/vacantes/crear
Content-Type: application/json

{
  "vacanteId": "42"
}

vacanteId

string

required

ID of the vacancy whose applicants will be included in the group chat.

Responses

Code	Meaning
`200`	Group chat created. Returns the `ChatDTO` object.
`403`	Caller does not have the `EMPRESA` role.

Get chat info

Returns metadata about a chat together with the authenticated user’s ID and primary role. Requires the jwtToken cookie.

GET /api/chats/{chatId}/info
Cookie: jwtToken=<token>

chatId

string

required

The chat identifier.

Response body

chatInfo

ChatDTO

Full chat object (see ChatDTO fields below).

userId

string

The authenticated user’s ID extracted from the JWT.

rolPrincipal

string

The user’s primary role (EMPRESA or CANDIDATO).

List messages in a chat

Returns all messages for a chat. The server method accepts a Spring Pageable but returns a flat List<MensajeDTO> — results are not wrapped in a Spring Page envelope.

GET /api/chats/{chatId}/mensajes

chatId

string

required

The chat identifier.

Response — MensajeDTO[] array (see MensajeDTO fields below).

List all chats (paginated)

Returns all chats in the system, paginated. Intended for administrative use.

GET /api/chats/listar?page=0&size=10

page

integer

default:"0"

Zero-based page number.

size

integer

default:"10"

Page size.

Response — map with pagination metadata and a content array of ChatDTO objects.

List chats by user

Filters chats for a specific user (company or candidate) with optional status and search filters.

PATCH /api/chats/{tipoUsuario}/{userId}?estado=activos&search=developer&page=0&size=10

tipoUsuario

string

required

Either empresa or candidato.

userId

string

required

The user’s ID.

estado

string

Filter by chat status: activos or inactivos. Omit to return all.

string

Free-text search term applied to chat metadata.

page

integer

default:"0"

Zero-based page number.

size

integer

default:"10"

Page size.

Change chat status

Allows the company that created the chat to close or reopen it. Requires the jwtToken cookie; the caller must match the chat’s empresaId.

PATCH /api/chats/{chatId}/estado?isActive=false
Cookie: jwtToken=<token>

chatId

string

required

The chat identifier.

isActive

boolean

required

true to reopen the chat; false to close it.

Responses

Code	Meaning
`204`	Status updated successfully. No body.
`403`	Caller is not the company that created the chat.

Add a message (REST)

Persists a message to a chat. For real-time delivery, prefer the WebSocket interface described below.

POST /api/chats/{chatId}/mensajes
Content-Type: application/json

{
  "senderId": "5",
  "receiverId": "17",
  "senderRole": "EMPRESA",
  "content": "Hello, we'd like to schedule an interview."
}

chatId

string

required

The chat the message belongs to. This value overrides chatId in the request body.

senderId

string

required

Sender’s user ID.

receiverId

string

required

Recipient’s user ID.

senderRole

string

Role of the sender (EMPRESA or CANDIDATO).

content

string

required

Message text.

Response — the saved MensajeDTO with server-assigned time and state.

Data models

ChatDTO fields

string

Unique chat identifier.

empresaId

string

ID of the company that created the chat.

nombreEmpresa

string

Display name of the company.

candidatoId

string

ID of the candidate (private chats only).

nombreCandidato

string

Display name of the candidate.

vacanteId

string

ID of the associated vacancy.

tituloVacante

string

Title of the associated vacancy.

isActive

boolean

Whether the chat is currently open.

tipoChat

string

Privado for one-to-one chats; Grupo for group chats.

contentUltimoMensaje

string

Text of the most recent message.

horaUltimoMensaje

string (ISO 8601 datetime)

Timestamp of the most recent message.

MensajeDTO fields

chatId

string

ID of the chat this message belongs to.

senderId

string

User ID of the sender.

receiverId

string

User ID of the recipient.

senderRole

string

Role of the sender.

receiverRole

string

Role of the recipient.

content

string

Message body text.

time

string (ISO 8601 datetime)

Server-assigned send timestamp (UTC).

state

string

Message delivery state.

WebSocket interface

Real-time messaging uses STOMP over SockJS. The server exposes a single SockJS endpoint at /chats. Once connected, clients send frames to application destinations prefixed with /app and subscribe to topics or user queues.

Broker configuration

Setting	Value
SockJS endpoint	`/chats`
Application destination prefix	`/app`
User destination prefix	`/user`
Simple broker prefixes	`/queue`, `/topic`

Connecting

import SockJS from 'sockjs-client';
import { Client } from '@stomp/stompjs';

const stompClient = new Client({
  webSocketFactory: () => new SockJS('http://your-host/chats'),
  reconnectDelay: 5000,

  onConnect: () => {
    console.log('Connected to STOMP');

    // Subscribe to private messages for the current user
    stompClient.subscribe('/user/queue/messages', (msg) => {
      const message = JSON.parse(msg.body);
      console.log('New message:', message);
    });

    // Subscribe to chat-status change events
    stompClient.subscribe('/user/queue/chat-change', (msg) => {
      console.log('Chat status changed:', msg.body);
    });
  },
});

stompClient.activate();

Send a private message

Publish to /app/chats.sendMessage. The server saves the message and delivers it to both the sender and recipient via their respective /user/queue/messages destinations.

stompClient.publish({
  destination: '/app/chats.sendMessage',
  body: JSON.stringify({
    chatId: '64f1a2b3c4d5e6f7a8b9c0d1',
    senderId: '5',
    receiverId: '17',
    senderRole: 'EMPRESA',
    content: 'Hello, are you available for an interview?',
  }),
});

Destination summary — private chat

Direction	Destination
Client sends to	`/app/chats.sendMessage`
Client receives from (sender)	`/user/{senderEmail}/queue/messages`
Client receives from (recipient)	`/user/{recipientEmail}/queue/messages`

Send a group message

Publish to /app/vacantes/{vacanteId}/chat. All subscribers of /topic/vacantes/{vacanteId}/chat receive the broadcast.

stompClient.publish({
  destination: '/app/vacantes/42/chat',
  body: JSON.stringify({
    chatId: '64f1a2b3c4d5e6f7a8b9c0d2',
    senderId: '5',
    senderRole: 'EMPRESA',
    content: 'Interview day is confirmed for next Monday.',
  }),
});

// Subscription for group chat
stompClient.subscribe('/topic/vacantes/42/chat', (msg) => {
  const message = JSON.parse(msg.body);
  console.log('Group message:', message);
});

Destination summary — group chat

Direction	Destination
Client sends to	`/app/vacantes/{vacanteId}/chat`
Client receives from	`/topic/vacantes/{vacanteId}/chat`

Re-subscribing after reconnect

The client singleton in Websocket.js maintains a subscriptions registry and re-subscribes all registered destinations automatically when STOMP reconnects:

import { connect, subscribe, sendMessage } from './services/Websocket';

// Register subscription before or after connecting
subscribe('/user/queue/messages', (msg) => {
  const message = JSON.parse(msg.body);
  // handle message
});

connect(); // activates the shared client; safe to call multiple times

Authentication

Core Resources

Features

Chat API: REST endpoints and WebSocket protocol

REST endpoints

Create a private chat

Create a group chat for a vacancy

Get chat info

List messages in a chat

List all chats (paginated)

List chats by user

Change chat status

Add a message (REST)

Data models

ChatDTO fields

MensajeDTO fields

WebSocket interface

Broker configuration

Connecting

Send a private message

Send a group message

Re-subscribing after reconnect

Build docs developers (and LLMs) love

Authentication

Core Resources

Features

Documentation Index

​REST endpoints

​Create a private chat

​Create a group chat for a vacancy

​Get chat info

​List messages in a chat

​List all chats (paginated)

​List chats by user

​Change chat status

​Add a message (REST)

​Data models

​ChatDTO fields

​MensajeDTO fields

​WebSocket interface

​Broker configuration

​Connecting

​Send a private message

​Send a group message

​Re-subscribing after reconnect

Build docs developers (and LLMs) love

REST endpoints

Create a private chat

Create a group chat for a vacancy

Get chat info

List messages in a chat

List all chats (paginated)

List chats by user

Change chat status

Add a message (REST)

Data models

ChatDTO fields

MensajeDTO fields

WebSocket interface

Broker configuration

Connecting

Send a private message

Send a group message

Re-subscribing after reconnect