Messages

Retrieve messages for a specific conversation. Messages are returned in chronological order.

Endpoint

GET /v1/messages

Authentication

Requires a valid API key via the X-API-Key header.

Parameters

Parameter	Type	Required	Default	Description
conversationId	string	Yes	--	The ID of the conversation to fetch messages for.
platform	string	No	Auto-detected	Filter by platform. Supported values: instagram, line, facebook, whatsapp.
from	string	No	--	ISO 8601 timestamp. Only return messages sent at or after this time.
to	string	No	--	ISO 8601 timestamp. Only return messages sent at or before this time.
limit	number	No	50	Maximum number of messages to return. Max value: 100.

Request Example

curl

curl -X GET "https://api.convotic.com/v1/messages?conversationId=conv_abc123&limit=20" \
  -H "X-API-Key: your-api-key-here"

With date range

curl -X GET "https://api.convotic.com/v1/messages?conversationId=conv_abc123&from=2026-03-01T00:00:00Z&to=2026-03-31T23:59:59Z&limit=50" \
  -H "X-API-Key: your-api-key-here"

Response Example

{
  "messages": [
    {
      "id": "msg_001",
      "conversationId": "conv_abc123",
      "platform": "instagram",
      "direction": "inbound",
      "sender": {
        "id": "ct_abc123",
        "name": "Somchai Prasert"
      },
      "content": {
        "type": "text",
        "text": "Hi, I'd like to ask about your product."
      },
      "timestamp": "2026-03-30T14:20:00Z"
    },
    {
      "id": "msg_002",
      "conversationId": "conv_abc123",
      "platform": "instagram",
      "direction": "outbound",
      "sender": {
        "id": "agent_01",
        "name": "Support Bot"
      },
      "content": {
        "type": "text",
        "text": "Hello! Thank you for reaching out. Which product are you interested in?"
      },
      "timestamp": "2026-03-30T14:20:05Z"
    },
    {
      "id": "msg_003",
      "conversationId": "conv_abc123",
      "platform": "instagram",
      "direction": "inbound",
      "sender": {
        "id": "ct_abc123",
        "name": "Somchai Prasert"
      },
      "content": {
        "type": "image",
        "url": "https://cdn.convotic.com/media/msg_003_img.jpg",
        "caption": "This one"
      },
      "timestamp": "2026-03-30T14:21:30Z"
    }
  ],
  "conversationId": "conv_abc123",
  "total": 3,
  "limit": 20
}

Response Fields

Field	Type	Description
messages	Message[]	Array of message objects in chronological order.
conversationId	string	The conversation these messages belong to.
total	number	Total number of messages returned.
limit	number	The limit value used for this request.

Message Object

Field	Type	Description
id	string	Unique message identifier.
conversationId	string	The conversation this message belongs to.
platform	string	The messaging platform.
direction	string	"inbound" (from contact) or "outbound" (from agent/bot).
sender	object	Object containing id and name of the sender.
content	object	Message content object. Contains type ("text", "image", "video", "file") and type-specific fields.
timestamp	string	ISO 8601 timestamp of when the message was sent.

TypeScript Example

interface MessageSender {
  id: string;
  name: string;
}

interface MessageContent {
  type: "text" | "image" | "video" | "file";
  text?: string;
  url?: string;
  caption?: string;
}

interface Message {
  id: string;
  conversationId: string;
  platform: string;
  direction: "inbound" | "outbound";
  sender: MessageSender;
  content: MessageContent;
  timestamp: string;
}

interface MessagesResponse {
  messages: Message[];
  conversationId: string;
  total: number;
  limit: number;
}

const params = new URLSearchParams({
  conversationId: "conv_abc123",
  limit: "20",
});

const response = await fetch(
  `https://api.convotic.com/v1/messages?${params}`,
  {
    headers: {
      "X-API-Key": "your-api-key-here",
    },
  }
);

const data: MessagesResponse = await response.json();
data.messages.forEach((msg) => {
  const arrow = msg.direction === "inbound" ? "<<" : ">>";
  console.log(`${arrow} [${msg.sender.name}] ${msg.content.text ?? msg.content.type}`);
});