Conversation Attachments

Conversation attachments provide a powerful way to enhance AI interactions by including files, images, documents, and other media directly in the conversation context. This feature allows users to share visual information, reference documents, and provide rich context that goes beyond text-based communication.

The attachment system supports multiple upload methods to accommodate different use cases and technical requirements, including direct file uploads, URL-based uploads, data URLs, and direct-to-storage uploads for large files. Each method is optimized for specific scenarios, ensuring efficient and reliable file handling regardless of file size or source.

Uploading Attachments

Uploading attachments to a conversation can be accomplished through several methods, each suited to different integration patterns and use cases. The system automatically handles file validation, storage, and tracking, creating activity entries in the conversation history to maintain a complete record of all uploaded files.

Method 1: Upload from HTTP URL

The simplest method is to provide an HTTP or HTTPS URL pointing to an existing file. The system will fetch the file from the URL and store it as a conversation attachment:

POST /api/v1/conversation/{conversationId}/attachment/upload
Content-Type: application/json

{
  "file": "https://example.com/document.pdf"
}

http

This method is ideal when files are already hosted elsewhere and you want to reference them in the conversation without re-uploading the data.

Method 2: Upload from Data URL

For smaller files, you can embed the file data directly in the request using a data URL. This is particularly useful for images and small documents that are generated client-side:

POST /api/v1/conversation/{conversationId}/attachment/upload
Content-Type: application/json

{
  "file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
}

http

Data URLs are limited by request size constraints but provide a convenient way to upload inline file data without additional requests.

Method 3: Multipart Form Upload

Traditional multipart form uploads are supported for direct file uploads from web forms or applications:

POST /api/v1/conversation/{conversationId}/attachment/upload
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

[binary file data]
------WebKitFormBoundary--

http

This standard approach works with HTML forms and most HTTP clients.

Method 4: Raw Binary Upload

You can upload files as raw binary data by sending the file content directly in the request body with the appropriate Content-Type header:

POST /api/v1/conversation/{conversationId}/attachment/upload
Content-Type: image/jpeg

[binary file data]

http

This method is efficient for programmatic uploads where the file type is known in advance.

Method 5: Direct-to-Storage Upload

For large files, the system supports a two-step upload process that bypasses the API servers entirely. First, request upload credentials:

POST /api/v1/conversation/{conversationId}/attachment/upload
Content-Type: application/json

{
  "file": {
    "type": "video/mp4",
    "size": 52428800,
    "name": "presentation.mp4"
  }
}

http

The API responds with pre-signed upload credentials:

{
  "id": "att_abc123",
  "name": "presentation.mp4",
  "uploadRequest": {
    "method": "PUT",
    "url": "https://storage.example.com/...",
    "headers": {
      "Content-Length": "52428800",
      "Content-Type": "video/mp4",
      "Content-Disposition": "attachment; filename=presentation.mp4"
    }
  }
}

json

Then upload the file directly to the storage service using the provided credentials. This method bypasses API size limits and enables efficient handling of large media files.

File Size Limits

File size limits vary by upload method and account tier:

  • Standard uploads (Methods 1-4): 4.5MB limit
  • Direct-to-storage uploads (Method 5): Account-specific limit (typically 50MB or higher)
  • File size limits are enforced based on the user's account settings
  • Exceeding limits returns a limitsReached error

Response Format

All upload methods return consistent response data:

{
  "id": "att_abc123",
  "name": "document.pdf",
  "downloadRequest": {
    "method": "GET",
    "url": "https://api.chatbotkit.com/...",
    "headers": {}
  }
}

json

For direct-to-storage uploads, an additional uploadRequest object is included with credentials for uploading the file.

Important Notes:

  • All uploaded files are scanned and validated before being made available
  • File names are normalized to handle special characters and encodings
  • Activity messages are automatically created to track upload events
  • Only the conversation owner can upload attachments
  • Attachments are automatically associated with the conversation and included in conversation exports
  • File types should be appropriate for processing by AI models (images, documents, text files are commonly supported)
Go to cbk.ai