perform.chat
Conversations

Get Messages

Retrieve messages from a conversation

Endpoint

GET https://api.perform.chat/rest/v1/conversations/:id/messages

Request Body

{
  "keyId": "your-key-id",
  "keySecret": "your-key-secret"
}

Path Parameters

ParameterTypeDescription
idstringConversation ID

Query Parameters

ParameterTypeDefaultMaxDescription
pagenumber1-Page number
limitnumber50100Messages per page

Response

{
  "data": [
    {
      "id": "msg_1",
      "content": "Hello, I have a question about my billing",
      "role": "user",
      "conversation_id": "conv_123",
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "msg_2",
      "content": "Hi! I'd be happy to help you with your billing question. What would you like to know?",
      "role": "assistant",
      "conversation_id": "conv_123",
      "created_at": "2025-01-15T10:30:15Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 12,
    "total_pages": 1
  },
  "conversation": {
    "id": "conv_123",
    "title": "Help with billing question"
  }
}

Response Fields

Message Object

FieldTypeDescription
idstringUnique message identifier
contentstringMessage text
rolestring"user" or "assistant"
conversation_idstringParent conversation ID
created_atstringISO 8601 timestamp

Message Roles

RoleDescription
userMessage from the customer user
assistantMessage from the AI agent

Example Request

async function getConversationMessages(conversationId, page = 1) {
  const response = await axios.get(
    `https://api.performchat.com/rest/v1/v1/conversations/${conversationId}/messages`,
    {
      params: { page, limit: 50 },
      data: {
        keyId: process.env.API_KEY_ID,
        keySecret: process.env.API_KEY_SECRET
      }
    }
  )
  return response.data
}

// Usage
const messages = await getConversationMessages('conv_123')
console.log(`Total messages: ${messages.pagination.total}`)

Use Cases

Export Full Conversation

async function exportConversation(conversationId) {
  const allMessages = []
  let page = 1
  let hasMore = true

  while (hasMore) {
    const result = await getConversationMessages(conversationId, page)
    allMessages.push(...result.data)

    hasMore = page < result.pagination.total_pages
    page++
  }

  return {
    conversation: result.conversation,
    messages: allMessages
  }
}

Analyze Conversation

async function analyzeConversation(conversationId) {
  const { messages } = await exportConversation(conversationId)

  const userMessages = messages.filter(m => m.role === 'user')
  const assistantMessages = messages.filter(m => m.role === 'assistant')

  return {
    total: messages.length,
    userMessages: userMessages.length,
    assistantMessages: assistantMessages.length,
    avgMessageLength: messages.reduce((sum, m) => sum + m.content.length, 0) / messages.length,
    duration: new Date(messages[messages.length - 1].created_at) - new Date(messages[0].created_at)
  }
}

Search Messages

async function searchInConversation(conversationId, searchTerm) {
  const { messages } = await exportConversation(conversationId)

  return messages.filter(msg =>
    msg.content.toLowerCase().includes(searchTerm.toLowerCase())
  )
}

Format for Display

async function formatConversationForDisplay(conversationId) {
  const { conversation, messages } = await exportConversation(conversationId)

  return {
    title: conversation.title,
    messages: messages.map(msg => ({
      text: msg.content,
      isUser: msg.role === 'user',
      timestamp: new Date(msg.created_at).toLocaleTimeString()
    }))
  }
}

Best Practices

  1. Messages are ordered chronologically - Oldest first
  2. Use pagination for long conversations - Don't load all at once
  3. Handle both roles - Check role field for message source
  4. Cache message data - Messages rarely change once created

Error Responses

StatusDescription
404Conversation not found or doesn't belong to company
401Invalid API credentials
400Invalid parameters
500Internal server error