Upload files

note

This documentation describes the file upload process. To understand how to use uploaded files in messages, refer to the attachment section of Send and receive messages.

The Moveo WebSocket API provides a secure and efficient way to upload files during chat sessions. This feature allows users to share documents, images, and other file types with agents or AI agents. The process involves a two-step approach:

1. First, requesting a secure, time-limited URL for uploading the file
2. Then, using that URL to upload the file directly to the Moveo storage system

This approach ensures secure file handling while maintaining optimal performance.

warning

You can upload files only within an active WebSocket session.

Sending an attachment to the session

File uploads are a part of sending an attachment in a message to the server. Once a file is successfully uploaded, it can be included in messages using the attachments field in the message:send event. Here's how the two processes work together:

1. Upload the file Follow the File Upload Process to obtain the file_name of the uploaded file. This process involves:

   • Requesting a presigned URL using the file:upload_url:create event
   • Uploading the file to the provided upload_url
   • Keeping the file_id and file_name from the file:upload_url:created event

2. Include in message Once the upload is complete, you can include the file in your message using the attachments field. The attachment should follow the format described in the Send and receive messages documentation.

warning

Set the attachment id to the file_id and filename to the file_name. Do not send the upload_url. Moveo generates the download URL for the attachment.

Example of sending a message with an uploaded file:

{
  "event": "message:send",
  "data": {
    "input": {
      "text": "Please find the attached document",
      "attachments": [
        {
          "type": "file",
          "mime_type": "application/pdf",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "filename": "document_123.pdf",
          "title": "Important Document"
        }
      ]
    },
    "session_id": "session_123",
    "timestamp": 1744036886028
  }
}

Prerequisites

Before attempting to upload files, ensure that:

• You have an active WebSocket session
• You have the correct session_id from your active session

File upload process

1. Request upload URL

The file:upload_url:create event is used to request a presigned URL for file upload. This is the first step in the file upload process, where you provide the necessary metadata about the file you want to upload.

Field	Type	Required	Description
file_id	string	Yes	Unique identifier for the file
session_id	string	Yes	Unique identifier for the conversation session
original_name	string	Yes	Original filename of the file
file_type	string	Yes	Type of the file (for example, pdf, jpg)

{
  "event": "file:upload_url:create",
  "data": {
    "file_id": "123e4567-e89b-12d3-a456-426614174000",
    "session_id": "session_123",
    "original_name": "document.pdf",
    "file_type": "pdf"
  }
}

Server responses

Success response (file:upload_url:created)

The server responds with a success event containing the URL needed for file upload.

Field	Type	Required	Description
upload_url	string	Yes	URL for uploading the file
session_id	string	Yes	Session identifier
file_id	string	Yes	Unique identifier for the file
file_name	string	Yes	Processed filename of the file

{
  "event": "file:upload_url:created",
  "data": {
    "upload_url": "https://storage.example.com/presigned-url",
    "session_id": "session_123",
    "file_id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "document_123.pdf"
  }
}

Error response (file:upload_url:create:error)

If the request fails, the server responds with an error event containing details about the failure.

Field	Type	Required	Description
code	string	Yes	Error code for programmatic handling
message	string	Yes	Human-readable error message

The payload is the error of the Moveo API, with code, message, and status_code. A file_type that is not in the allowed list fails validation. The allowed file_type values are csv, doc, docx, pdf, ppt, pptx, txt, xls, xlsx, zip, gif, jfif, jpeg, jpg, png, webp, mp3, mpeg, ogg, wav, mov, mp4, and webm. See Limits and error handling.

2. Upload file to presigned URL

Once you receive the presigned URL, upload the file using a PUT request. The file should be sent as-is, without any additional processing or parsing.

HTTP PUT request

curl -X PUT \
  -H "Content-Type: <file-mime-type>" \
  --data-binary @<path-to-file> \
  https://storage.example.com/presigned-url

Headers:

• Content-Type: Must match the file's MIME type
• No additional headers are required as the presigned URL includes all necessary authentication

Body:

• Send the raw file bytes as the request body
• Do not encode or transform the file
• Do not wrap the file in any additional data structure

Example request

curl -X PUT \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf \
  https://storage.example.com/presigned-url

3. Response handling

The upload endpoint responds with:

Success (200 OK):

HTTP/1.1 200 OK

Error responses: the storage server returns an HTTP error status. A file larger than 50 MB fails. A presigned URL that expired fails too. Request a new URL with file:upload_url:create.

Important notes

1. File format

   • Send the file in its original format
   • Do not encode the file (no base64, no form-data)
   • Do not compress the file
   • Do not modify the file content

2. Content-Type

   • Must match the actual file type
   • Common MIME types:

     {
       "application/pdf": ".pdf",
       "image/jpeg": ".jpg, .jpeg",
       "image/png": ".png",
       "image/gif": ".gif",
       "application/msword": ".doc",
       "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
       "application/vnd.ms-powerpoint": ".ppt",
       "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
       "application/zip": ".zip"
     }

3. File size

   • Maximum size: 50 MB for each file
   • The upload is one PUT request. Moveo does not support chunked uploads.

4. Retry logic

   • The Moveo web client tries an upload up to 3 times, and does not retry a 4xx response
   • If the upload still fails, request a new presigned URL

Common issues and solutions

1. Invalid Content-Type

   • Ensure the Content-Type header matches the actual file type
   • Do not use generic types like application/octet-stream
   • Solution: Verify file type before upload and set correct Content-Type

2. File corruption

   • Send the file in its original format
   • Do not modify or transform the file content
   • Ensure proper binary transfer
   • Solution: Validate file integrity before and after upload

3. Timeout issues

   • Implement proper timeout handling
   • Consider implementing progress tracking
   • Handle network interruptions gracefully
   • Solution: Use appropriate timeout values and implement retry logic

4. Authentication errors

   • Ensure the presigned URL is used within its validity period
   • Do not modify the presigned URL
   • Request a new URL if the current one expires
   • Solution: Implement URL expiration checks and refresh logic

Example upload flow

1. Get presigned URL

{
  "event": "file:upload_url:create",
  "data": {
    "file_id": "123e4567-e89b-12d3-a456-426614174000",
    "session_id": "session_123",
    "original_name": "document.pdf",
    "file_type": "pdf"
  }
}

2. Receive presigned URL

{
  "event": "file:upload_url:created",
  "data": {
    "upload_url": "https://storage.example.com/presigned-url",
    "session_id": "session_123",
    "file_id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "document_123.pdf"
  }
}

3. Upload file

curl -X PUT \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf \
  https://storage.example.com/presigned-url

4. Handle response

• Success: Proceed with sending the file_id and file_name in the message attachment
• Failure: Implement retry logic or request new presigned URL

This documentation provides detailed information about the file upload process, including proper handling of file data and common issues to avoid.