Attachment Handler Setup

Upload files and media to conversation threads through the GHL MCP server. This tool handles images, documents, and media files that you want to share within SMS, email, or chat conversations. Uploaded files become available for cross-channel delivery, so a single upload can be referenced in messages across different messaging channels.

Prerequisites

Before uploading attachments, confirm the following:

• A GoHighLevel sub-account with at least one active conversation
• A Private Integration Token (PIT) with the conversations scope enabled
• A conversation ID for the target thread (retrieve one using Conversation CRUD)
• A file ready to upload (images, PDFs, or media files)

Supported file types include JPEG, PNG, GIF, PDF, and common document formats. Check your location’s file size limits in GHL settings, as large files may be rejected.

Set Up Authentication

Generate a PIT from Settings > Integrations > Private Integrations in your sub-account. Click Create New, name it “MCP Attachment Uploader,” and enable the conversations scope. Copy the token and store it securely.

For upload requests, use the header Authorization: Bearer YOUR_PIT_TOKEN along with Version: 2021-07-28. Note that the Content-Type for file uploads should be multipart/form-data rather than the usual JSON content type. Your HTTP client or MCP framework should handle the multipart encoding automatically.

Make Your First Call

Upload a file using POST /conversations/{id}/upload where {id} is the conversation ID. The request body uses multipart form data with the file included as the upload field.

Structure your request with these components:

• URL path: Replace {id} with your target conversation’s ID
• File field: Include the file binary data in the multipart form body
• Content type: Let your HTTP client set the multipart boundary automatically

The upload endpoint accepts one file per request. If you need to attach multiple files, make separate upload calls for each file. Once uploaded, the file is stored in GHL’s media system and linked to the specified conversation.

The returned URL from a successful upload can then be used as an attachments value when sending messages through SMS Operations or Email Send.

Handle the Response

A successful upload returns a JSON object with the file URL and metadata. The URL is a publicly accessible link hosted by GHL that you can reference in subsequent message sends.

Key response fields include:

• url — the hosted file URL for use in message attachments
• name — the original filename
• type — the MIME type of the uploaded file

If the upload fails, common errors include unsupported file types (check the MIME type), files exceeding the size limit, and invalid conversation IDs. A 404 response means the conversation ID does not exist. A 413 response indicates the file is too large.

Test Your Setup

Run a quick validation of the upload flow:

• Prepare a small test image (JPEG or PNG, under 1 MB)
• Call POST /conversations/{id}/upload with a valid conversation ID and the test file
• Confirm the response includes a url field with an accessible link
• Open the URL in a browser to verify the file is accessible
• Use the returned URL in an SMS or email send to confirm end-to-end attachment delivery

Check the full Attachment Handler guide for file type restrictions and size limits. To manage the media files in your location’s library, see Media Library.