Using the Signed URL File Upload API

About Signed URL File Upload

The Signed URL File Upload API enables you to upload files directly from a client application to secure cloud storage, bypassing the CRM's application servers. This is done using a secure, time-limited URL. This method significantly improves upload performance and reliability, reduces load on the server, and allows for the transfer of larger files.

Key Benefits

Using this upload flow offers several advantages:

• Enhanced Stability: Files are streamed directly to cloud storage, eliminating the risk of server memory issues.
• Larger File Support: Upload media files up to 100MB for WhatsApp and up to 5MB for all other communication channels.
• Improved Performance: The direct upload path from client to storage reduces latency and speeds up the transfer.
• Increased Reliability: Signed URLs expire after 15 minutes, providing a clear timeframe for uploads with defined error handling.
• Robust Security: The process includes multiple validation steps for file paths, user access, and content types.

The Three-Step Upload Process

The upload is broken down into three distinct phases to ensure security and validation at each step.

Step 1: Initiate the Upload

Send a POST request to the /conversations/messages/upload/initiate endpoint with the file's metadata. The CRM will validate the request and provide a time-limited signed URL and a specific storage path for the file.

Step 2: Upload the File

Using the signed URL provided in the first step, perform a PUT request to upload the file data directly to the cloud storage. This must be completed before the URL expires.

Step 3: Complete the Upload

Send a POST request to the /conversations/messages/upload/complete endpoint. The CRM will verify that the file was successfully stored and will then return a public URL that you can use to reference the file in messages.

File Size Limits by Channel

Different messaging channels have different maximum file size allowances.

• WhatsApp: Supports files up to 100MB.
• All Other Channels: Support files up to 5MB.

The system performs checks during the initiation phase to reject files that exceed these limits, preventing unnecessary data transfer.

Content-Type Validation

To ensure file safety and compatibility, the file's MIME type is validated at two points.

• On Initiate: The declared Content-Type is checked against the file's extension.
• On Complete: The stored Content-Type in the cloud storage is verified against the filename.

This two-step process helps prevent content-type spoofing and ensures the file type is correct.

Security and Access Control

Multiple safeguards are in place to protect the upload process.

• The system confirms that the specified conversation exists and is associated with the correct location.
• It verifies that the user has the necessary permissions to access that location.
• The file path is validated to ensure it conforms to the expected format for the location and conversation.
• Signed URLs are only valid for 15 minutes to minimize potential misuse.

Error Handling

Understanding potential errors will help you build a robust integration.

• URL Expired: If the signed URL expires, you must restart the process by calling the Initiate endpoint again.
• Oversized File: The file will be rejected if it exceeds the channel's size limit.
• Content-Type Mismatch: Ensure the file's extension and the Content-Type header accurately represent the file.
• Permission Errors: Verify the user's access rights and that the conversation identifiers are correct.

Implementation Tips

Follow these best practices for a smooth integration.

• Initiate the upload close to the time you are ready to transfer the file to make the most of the 15-minute URL validity window.
• Always set the Content-Type header in your PUT request to match the actual file type.
• Keep a record of the object path returned by the Initiate call for troubleshooting purposes.
• For large files, if an upload stalls near the expiration time, it is better to re-initiate the process rather than retrying with the same URL.
• Perform client-side checks on file size and MIME type before initiating the upload to provide faster feedback to users.

Frequently Asked Questions

Is the "Complete" step required?

Yes. The Complete step is necessary to verify the file was stored correctly and to receive the public URL needed for sending messages.

What happens if the URL expires during an upload?

You must restart the entire flow: call Initiate to get a new signed URL, then perform the upload and completion steps again.

Are the uploaded files publicly accessible?

After completion, a public URL is provided for use within messages. You should handle this URL according to your organization's data security policies.

Can I upload any file type as long as it's under the size limit?

No. The content-type validation will block files where the declared type does not match the file extension.

Do channels other than WhatsApp support 100MB files?

No. The 100MB limit is specific to WhatsApp; all other channels have a 5MB maximum.

How does this improve system stability?

Because files are sent directly to cloud storage, the CRM's application servers do not need to buffer the file data, which eliminates the risk of memory-related crashes.

How long is the signed URL valid?

The signed URL expires 15 minutes after it is issued.

Can I use the same signed URL for multiple files?

No. Each Initiate call generates a unique URL intended for a single file and a specific storage path.