Skip to main content

​
Overview

The Messaging API enables direct communication between tourists and guides through threaded conversations. Messages are organized into chat threads for easy conversation management.

​
Send Message

curl -X POST "https://api.kinconecta.com/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": 123,
    "senderUserId": 456,
    "body": "Hello! I am interested in booking a tour to Sagrada Familia.",
    "messageType": "TEXT"
  }'

​
Endpoint

POST /messages

​
Request Body

​
threadId
Long
required
The ID of the chat thread where this message belongs
​
senderUserId
Long
required
The user ID of the message sender
​
body
String
required
The content of the message (supports TEXT content)
​
messageType
MessageType
required
Type of message being sentEnum values:
  • TEXT - Regular text message
  • SYSTEM - System-generated message (e.g., “Tour booked”)
  • IMAGE - Image attachment
  • FILE - File attachment

​
Response

​
messageId
Long
Unique identifier for the created message
​
threadId
Long
The chat thread ID this message belongs to
​
senderUserId
Long
User ID of the sender
​
body
String
The message content
​
messageType
MessageType
Type of the message (TEXT, SYSTEM, IMAGE, FILE)
​
sentAt
LocalDateTime
Timestamp when the message was sent (ISO 8601 format)
​
readAt
LocalDateTime
Timestamp when the message was read (null if unread)

​
Example Response

{
  "messageId": 7891,
  "threadId": 123,
  "senderUserId": 456,
  "body": "Hello! I am interested in booking a tour to Sagrada Familia.",
  "messageType": "TEXT",
  "sentAt": "2026-03-10T14:23:45",
  "readAt": null
}

​
Get Messages by Thread

curl -X GET "https://api.kinconecta.com/messages/thread/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Endpoint

GET /messages/thread/{threadId}

​
Path Parameters

​
threadId
Long
required
The unique identifier of the chat thread to retrieve messages from

​
Response

Returns an array of ChatMessage objects ordered chronologically.
​
messages
Array<ChatMessage>
List of all messages in the thread

​
Example Response

[
  {
    "messageId": 7891,
    "threadId": 123,
    "senderUserId": 456,
    "body": "Hello! I am interested in booking a tour to Sagrada Familia.",
    "messageType": "TEXT",
    "sentAt": "2026-03-10T14:23:45",
    "readAt": "2026-03-10T14:25:12"
  },
  {
    "messageId": 7892,
    "threadId": 123,
    "senderUserId": 789,
    "body": "Great! I have availability tomorrow at 10 AM. Would that work for you?",
    "messageType": "TEXT",
    "sentAt": "2026-03-10T14:25:30",
    "readAt": "2026-03-10T14:26:05"
  },
  {
    "messageId": 7893,
    "threadId": 123,
    "senderUserId": 456,
    "body": "Perfect! See you tomorrow.",
    "messageType": "TEXT",
    "sentAt": "2026-03-10T14:26:15",
    "readAt": null
  }
]

​
Message Types

The messaging system supports different message types:

​
TEXT

Standard text messages sent between users. This is the most common message type for regular conversation.

​
SYSTEM

Automated system messages that provide updates about bookings, payments, or other platform events. Example system messages:
  • “Tour booking confirmed for March 15, 2026”
  • “Payment of €150 received”
  • “Carlos has updated the tour details”

​
IMAGE

Messages containing image attachments. The body field contains the image URL or reference.

​
FILE

Messages with file attachments (PDFs, documents, etc.). The body field contains the file URL or reference.

​
Best Practices

​
Real-time Updates

Consider implementing WebSocket connections or polling for real-time message delivery and read receipts.

​
Message Pagination

For threads with many messages, implement pagination on the client side to load messages in batches.

​
Read Receipts

Update the readAt timestamp when a user views messages to provide accurate read receipt functionality.

​
Error Handling

Handle cases where:
  • Thread doesn’t exist
  • User doesn’t have permission to access the thread
  • Message body exceeds maximum length

Build docs developers (and LLMs) love

Get started for freeTalk to us