Skip to main content
GHL MCP Guide
ATT

Attachment Handler

Conversations & Messaging · Intermediate · Updated March 2026

Upload files and media to conversation threads. Support for images, documents, and other file types across all communication channels.

Conversations aren’t just text. Contracts need signatures, photos document job completions, invoices get shared, and proposals get attached. The Attachment Handler lets you upload files directly into conversation threads, making them part of the communication record alongside SMS, email, and chat messages.

What This MCP Tool Does

Upload files and media attachments to specific conversation threads. Supports images, documents, PDFs, and other common file types. Uploaded files become part of the conversation record and are accessible to both the team and, depending on the channel, the contact.

Endpoint Reference

Upload an attachment: POST /conversations/{conversationId}/upload Upload a file to a specific conversation. The file becomes available within that conversation’s thread and can be shared in subsequent messages.

Authentication

Requires a Private Integration Token (PIT) with the conversations scope enabled.

Key Parameters

  • conversationId — the conversation to attach the file to
  • file — the file data (multipart form upload)

Important Notes

File uploads go to the specific conversation, not to the contact record broadly. If a contact has multiple conversations (SMS thread, email thread, chat thread), the file is only in the conversation you uploaded it to.

File size limits apply. Large files may be rejected depending on the channel. Keep uploads reasonable — under 10MB is a safe target for most channels.

Uploaded files are stored in GHL’s infrastructure and served through their CDN. You don’t need to host the files yourself after upload.

For MMS messages (images sent via text), you can either upload through this handler first and reference the URL in your SMS Operations call, or provide a publicly accessible URL directly in the SMS send request.

Common Questions

What file types are supported? Common formats including JPEG, PNG, GIF, PDF, DOC, DOCX, and XLS. The exact supported types depend on the communication channel.

Can the contact see uploaded attachments? Depends on the channel. Files uploaded to an email conversation can be attached to outbound emails. Files uploaded to an SMS conversation can be sent as MMS. Files uploaded to a chat conversation appear in the chat widget.

Is there a storage limit? GHL manages storage for uploaded files. There’s no per-file limit documented, but total storage across a location may have limits depending on your plan.

Can I upload files to a contact record (not a conversation)? Not through this tool. This is conversation-level file management. For contact-level file storage, custom field file uploads or the Media Library are better options.

Back to GHL MCP Guide