Export conversations API

Prerequisites

To use the APIs, you need to have a token. Tokens can be generated by an admin at the setting section in Filum CX platform. Ensure you have the necessary permissions to access the admin settings for token generation.

APIs

Access the APIs via the endpoint: https://contact-center.filum.ai/

GET /external/conversations

Summary

Get Conversations

Query Parameters

Name	Description	Required	Schema
start_date	The start date for filtering conversations (YYYY-MM-DD)	Yes	string (date)
end_date	The end date for filtering conversations (YYYY-MM-DD)	Yes	string (date)
page	The page number of the conversation results you want to retrieve	No	integer (>= 1, default: 1)
per_page	The number of conversation results you want to display per page	No	integer (1 .. 100, default: 10)
statuses	Filter by conversation statuses (comma-separated). Options: closed, human_in_progress, ai_in_progress, pending, classifying, rating	No	string
installed_source_ids	Filter by installed source IDs (comma-separated)	No	string
assignee_account_ids	Filter by assignee account IDs (comma-separated)	No	string
team_ids	Filter by team IDs (comma-separated)	No	string
has_ticket	Filter by whether conversation has a ticket. Options: true, false	No	boolean
chatbot_enabled	Filter by whether chatbot is enabled. Options: true, false	No	boolean
read	Filter by read status. Options: true, false	No	boolean
search	Search term to filter conversations by user name, phone, email, or ticket ID	No	string

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value should be in the format Bearer <your_api_token>	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	The type of authorization used for the request. Options: token (for API tokens), account (for user sessions)	Yes	string

Responses

Code	Description	Content type
200	Successful Response	application/json
422	Validation Error	application/json

200 Successful Response

Field	Type/Format	Required	Description
items	array of objects	Yes	A list of conversations
items.id	string	Yes	The unique identifier of the conversation
items.organization_id	string	Yes	The unique identifier of the organization
items.installed_source_id	integer	No	The ID of the installed source (channel)
items.source_id	integer	No	The ID of the source
items.user	object	Yes	Information about the user in the conversation
items.user.id	string	No	The unique identifier of the user
items.user.name	string	No	The name of the user
items.user.email	string	No	The email of the user
items.user.phone	string	No	The phone number of the user
items.user.anonymous_id	string	No	The anonymous identifier of the user
items.status	string	Yes	The status of the conversation
items.assignee	object	No	Information about the assignee
items.assignee.id	integer	Yes	The ID of the assignee
items.assignee.name	string	Yes	The name of the assignee
items.assignee.email	string	Yes	The email of the assignee
items.team	object	No	Information about the team
items.team.id	integer	Yes	The ID of the team
items.team.name	string	Yes	The name of the team
items.ticket	object	No	Information about the linked ticket
items.ticket.id	integer	Yes	The ID of the ticket
items.ticket.status	string	No	The status of the ticket
items.ticket.assignee	object	No	The assignee of the ticket
items.ticket.team	object	No	The team of the ticket
items.last_message	object	No	Information about the last message
items.last_message.text	string	No	The text content of the last message
items.last_message.created_at	string (date-time)	No	The timestamp when the last message was created
items.last_message.sender_type	string	No	The sender type of the last message (user, assistant, agent)
items.read	boolean	Yes	Whether the conversation has been read
items.chatbot_enabled	boolean	Yes	Whether chatbot is enabled for the conversation
items.ai_package_enabled	boolean	Yes	Whether AI package is enabled for the conversation
items.created_at	string (date-time)	Yes	The timestamp when the conversation was created
items.updated_at	string (date-time)	Yes	The timestamp when the conversation was last updated
items.type	string	No	The type of conversation (chat, call, etc.)
items.name	string	No	The name of the conversation
total	integer	Yes	Total number of conversations matching the filter
page	integer	Yes	Current page number
per_page	integer	Yes	Number of items per page
pages	integer	Yes	Total number of pages

Response samples

{
  "items": [
    {
      "id": "507f1f77bcf86cd799439011",
      "organization_id": "org_12345",
      "installed_source_id": 1,
      "source_id": 10,
      "user": {
        "id": "user_123",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+84901234567",
        "anonymous_id": null
      },
      "status": "closed",
      "assignee": {
        "id": 42,
        "name": "Agent Smith",
        "email": "agent.smith@company.com"
      },
      "team": {
        "id": 5,
        "name": "Support Team"
      },
      "ticket": {
        "id": 1001,
        "status": "closed",
        "assignee": {
          "id": 42,
          "name": "Agent Smith",
          "email": "agent.smith@company.com"
        },
        "team": {
          "id": 5,
          "name": "Support Team"
        }
      },
      "last_message": {
        "text": "Thank you for your help!",
        "created_at": "2024-01-15T10:30:00Z",
        "sender_type": "user"
      },
      "read": true,
      "chatbot_enabled": false,
      "ai_package_enabled": true,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:35:00Z",
      "type": "chat",
      "name": "Support Inquiry"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 10,
  "pages": 15
}

GET /external/conversations/{conversation_id}/messages

Summary

Get Messages for a Conversation

Path Parameters

Name	Description	Required	Schema
conversation_id	The unique identifier of the conversation	Yes	string

Query Parameters

Name	Description	Required	Schema
page	The page number of the message results you want to retrieve	No	integer (>= 1, default: 1)
per_page	The number of message results you want to display per page	No	integer (1 .. 100, default: 20)
scope	Filter by message scope. Options: external, internal, social	No	string
sender_type	Filter by sender type. Options: user, assistant, agent	No	string

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value should be in the format Bearer <your_api_token>	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	token	Yes	string

Responses

Code	Description	Content type
200	Successful Response	application/json
404	Conversation Not Found	application/json
422	Validation Error	application/json

200 Successful Response

Field	Type/Format	Required	Description
items	array of objects	Yes	A list of messages
items.id	string	Yes	The unique identifier of the message
items.conversation_id	string	Yes	The unique identifier of the conversation
items.organization_id	string	Yes	The unique identifier of the organization
items.text	string	No	The text content of the message
items.sender_type	string	Yes	The type of sender (user, assistant, agent)
items.scope	string	Yes	The scope of the message (external, internal, social)
items.status	string	No	The status of the message (sent, sending, failed, etc.)
items.attachments	array of objects	No	List of attachments in the message
items.attachments.url	string	Yes	The URL of the attachment
items.attachments.type	string	Yes	The type of attachment (image, file, etc.)
items.attachments.name	string	No	The name of the attachment
items.attachments.mime_type	string	No	The MIME type of the attachment
items.created_at	string (date-time)	Yes	The timestamp when the message was created
items.updated_at	string (date-time)	Yes	The timestamp when the message was last updated
items.agent_type	string	No	The type of agent (qna, survey, greeting, etc.)
items.assistant_id	string	No	The ID of the assistant that sent the message
items.metadata	object	No	Additional metadata about the message
total	integer	Yes	Total number of messages in the conversation
page	integer	Yes	Current page number
per_page	integer	Yes	Number of items per page
pages	integer	Yes	Total number of pages

Response samples

{
  "items": [
    {
      "id": "msg_507f1f77bcf86cd799439011",
      "conversation_id": "507f1f77bcf86cd799439011",
      "organization_id": "org_12345",
      "text": "Hello, I need help with my order",
      "sender_type": "user",
      "scope": "external",
      "status": "sent",
      "attachments": [
        {
          "url": "https://example.com/image.jpg",
          "type": "image",
          "name": "order-screenshot.jpg",
          "mime_type": "image/jpeg"
        }
      ],
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z",
      "agent_type": null,
      "assistant_id": null,
      "metadata": {}
    },
    {
      "id": "msg_507f1f77bcf86cd799439012",
      "conversation_id": "507f1f77bcf86cd799439011",
      "organization_id": "org_12345",
      "text": "Sure, I'd be happy to help you with your order. Could you please provide your order number?",
      "sender_type": "assistant",
      "scope": "external",
      "status": "sent",
      "attachments": null,
      "created_at": "2024-01-15T10:00:30Z",
      "updated_at": "2024-01-15T10:00:30Z",
      "agent_type": "qna",
      "assistant_id": "assistant_abc123",
      "metadata": {
        "sources": [
          {
            "title": "Order Support Documentation",
            "url": "https://docs.example.com/orders"
          }
        ]
      }
    }
  ],
  "total": 25,
  "page": 1,
  "per_page": 20,
  "pages": 2
}

Usage Examples

Example 1: Get all conversations from the last 30 days

curl -X GET "https://contact-center.filum.ai/external/conversations?start_date=2024-01-01&end_date=2024-01-31&page=1&per_page=50" \
  -H "authorization: Bearer your_api_token_here" \
  -H "organization-id: your_organization_id_here" \
  -H "auth-type: token"

Example 2: Get messages for a specific conversation

curl -X GET "https://contact-center.filum.ai/external/conversations/507f1f77bcf86cd799439011/messages?page=1&per_page=50" \
  -H "authorization: Bearer your_api_token_here" \
  -H "organization-id: your_organization_id_here" \
  -H "auth-type: token"

Rate Limiting

The API endpoints are rate-limited to ensure fair usage and system stability. The default rate limits are:

• Per second: 5 requests
• Per minute: 50 requests

If you exceed these limits, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic with exponential backoff in your integration.

Error Responses

401 Unauthorized

{
  "detail": {
    "message": "Unauthorized"
  }
}

404 Not Found

{
  "detail": {
    "message": "Conversation not found"
  }
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["query", "start_date"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

429 Too Many Requests

{
  "detail": "Rate limit exceeded"
}