# Upload file attachments
POST https://services.leadconnectorhq.com/conversations/messages/upload
Post the necessary fields for the API to upload files. The files need to be a buffer with the key "fileAttachment".
Note: One of conversationId or contactId must be provided.
File Size Limits: - Maximum file size: 5 MB
- Maximum files per upload: 5
Allowed file types:
Images: JPG, JPEG, PNG, GIF, SVG, HEIC, AI
Videos: MP4, MPEG, 3GP
Audio: MP3, WAV, WAVE, AIFF, AIF, AIFC, GSM, ULAW, OGG, AAC, M4A, AMR
Documents: PDF, DOC, DOCX, TXT, CSV, XLS, XLSX, PPT, PPTX, ODT
Archives: ZIP, RAR
Other: VCF, VCARD (contact files), ICS (calendar files)
The API will return an object with the URLs
Secure attachments: Set isSecureAttachment to true to upload the file as a secure attachment. This is currently supported for the email channel only; support for the remaining conversation channels is coming.
A secure attachment is returned with a /files/d/{slug} URL that is publicly accessible for one hour after upload. After that window the attachment becomes private — to render, download, or retry access, extract the {slug} from the returned URL and call GET /files/d/{slug} with a bearer token carrying the files.readonly OAuth scope, which returns a short-lived signed download URL. A file uploaded without this flag keeps its existing permanently accessible URL.
Note: From 30 November 2026 every file uploaded through this endpoint is stored as a secure attachment, and the isSecureAttachment field is ignored.
## Authentication
Send `Authorization: Bearer ` using:
- **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `conversations/message.write`
## Parameters
### Header Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Version` | string | Yes | API Version |
## OpenAPI Specification
```json
{
"openapi": "3.0.0",
"info": {
"title": "LeadConnector API",
"version": "v3"
},
"servers": [
{
"url": "https://services.leadconnectorhq.com"
}
],
"paths": {
"/conversations/messages/upload": {
"post": {
"summary": "Upload file attachments",
"operationId": "uploadFileAttachments",
"description": "Post the necessary fields for the API to upload files. The files need to be a buffer with the key \"fileAttachment\".
Note: One of conversationId or contactId must be provided.
File Size Limits: - Maximum file size: 5 MB
- Maximum files per upload: 5
Allowed file types:
Images: JPG, JPEG, PNG, GIF, SVG, HEIC, AI
Videos: MP4, MPEG, 3GP
Audio: MP3, WAV, WAVE, AIFF, AIF, AIFC, GSM, ULAW, OGG, AAC, M4A, AMR
Documents: PDF, DOC, DOCX, TXT, CSV, XLS, XLSX, PPT, PPTX, ODT
Archives: ZIP, RAR
Other: VCF, VCARD (contact files), ICS (calendar files)
The API will return an object with the URLs
Secure attachments: Set isSecureAttachment to true to upload the file as a secure attachment. This is currently supported for the email channel only; support for the remaining conversation channels is coming.
A secure attachment is returned with a /files/d/{slug} URL that is publicly accessible for one hour after upload. After that window the attachment becomes private — to render, download, or retry access, extract the {slug} from the returned URL and call GET /files/d/{slug} with a bearer token carrying the files.readonly OAuth scope, which returns a short-lived signed download URL. A file uploaded without this flag keeps its existing permanently accessible URL.
Note: From 30 November 2026 every file uploaded through this endpoint is stored as a secure attachment, and the isSecureAttachment field is ignored.",
"parameters": [
{
"name": "Version",
"in": "header",
"description": "API Version",
"required": true,
"schema": {
"type": "string",
"enum": [
"v3"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/UploadFilesDto"
}
}
}
},
"responses": {
"200": {
"description": "Uploaded the file successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadFilesResponseDto"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestDTO"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedDTO"
}
}
}
},
"404": {
"description": "Not Found - Conversation id, contact id, workflow id or campaign id not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundDTO"
}
}
}
},
"413": {
"description": "Payload Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadFilesErrorResponseDto"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadFilesErrorResponseDto"
}
}
}
}
},
"security": [
{
"bearer": [
"conversations/message.write"
]
}
]
}
}
},
"components": {
"securitySchemes": {
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"name": "Authorization",
"in": "header",
"description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
"type": "http"
},
"Location-Access": {
"scheme": "bearer",
"bearerFormat": "JWT",
"name": "Authorization",
"in": "header",
"description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
"type": "http"
},
"Location-Access-Only": {
"scheme": "bearer",
"bearerFormat": "JWT",
"name": "Authorization",
"in": "header",
"description": "Use the Access Token generated with user type as Sub-Account.",
"type": "http"
},
"Agency-Access": {
"scheme": "bearer",
"bearerFormat": "JWT",
"name": "Authorization",
"in": "header",
"description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.",
"type": "http"
}
},
"schemas": {
"UploadFilesDto": {
"type": "object",
"description": "One of conversationId, contactId, workflowId, or campaignId must be provided",
"properties": {
"conversationId": {
"type": "string",
"description": "Conversation Id",
"example": "ve9EPM428h8vShlRW1KT"
},
"contactId": {
"type": "string",
"description": "Contact Id",
"example": "ve9EPM428h8vShlRW1KT"
},
"workflowId": {
"type": "string",
"description": "Workflow Id",
"example": "ve9EPM428h8vShlRW1KT"
},
"campaignId": {
"type": "string",
"description": "Campaign Id",
"example": "ve9EPM428h8vShlRW1KT"
},
"locationId": {
"type": "string"
},
"attachmentUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"isSecureAttachment": {
"type": "string",
"default": "false",
"description": "Set to true to upload the file as a secure attachment. Defaults to false. Currently supported for the email channel only; support for the remaining conversation channels is coming. A secure attachment URL is publicly accessible for one hour after upload, after which the file must be fetched with GET /files/d/{slug} using the files.readonly OAuth scope. Considered only until 30 November 2026; from that date every upload is stored as a secure attachment and this field is ignored.",
"example": "false"
}
},
"required": [
"locationId",
"attachmentUrls"
],
"title": "UploadFilesDto"
},
"UploadFilesResponseDto": {
"type": "object",
"properties": {
"uploadedFiles": {
"type": "object"
}
},
"required": [
"uploadedFiles"
],
"title": "UploadFilesResponseDto"
},
"BadRequestDTO": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 400
},
"message": {
"type": "string",
"example": "Bad Request"
}
},
"title": "BadRequestDTO"
},
"UnauthorizedDTO": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid token: access token is invalid"
},
"error": {
"type": "string",
"example": "Unauthorized"
}
},
"title": "UnauthorizedDTO"
},
"NotFoundDTO": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"example": 404
},
"message": {
"type": "string",
"example": "Conversation id, contact id, workflow id, or campaign id not given"
}
},
"title": "NotFoundDTO"
},
"UploadFilesErrorResponseDto": {
"type": "object",
"properties": {
"status": {
"type": "number",
"description": "HTTP Status code of the request",
"example": 413,
"enum": [
400,
404,
413,
415
]
},
"message": {
"type": "string",
"description": "Error message of the request",
"example": "Failed to upload the files"
}
},
"required": [
"status",
"message"
],
"title": "UploadFilesErrorResponseDto"
}
}
}
}
```
## Code Examples
**cURL**
```bash
curl -L -X POST 'https://services.leadconnectorhq.com/conversations/messages/upload' \
-H 'Authorization: Bearer ' \
-H 'Version: v3' \
-H 'Content-Type: multipart/form-data' \
--data-raw '{
"conversationId": "ve9EPM428h8vShlRW1KT",
"contactId": "ve9EPM428h8vShlRW1KT",
"workflowId": "ve9EPM428h8vShlRW1KT",
"campaignId": "ve9EPM428h8vShlRW1KT",
"attachmentUrls": [],
"isSecureAttachment": "false"
}'
```
**Node.js**
```javascript
const options = {
method: 'POST',
headers: {
Authorization: 'Bearer ',
Version: 'v3',
'Content-Type': 'multipart/form-data'
},
body: JSON.stringify({
"conversationId": "ve9EPM428h8vShlRW1KT",
"contactId": "ve9EPM428h8vShlRW1KT",
"workflowId": "ve9EPM428h8vShlRW1KT",
"campaignId": "ve9EPM428h8vShlRW1KT",
"attachmentUrls": [],
"isSecureAttachment": "false"
})
};
try {
const response = await fetch('https://services.leadconnectorhq.com/conversations/messages/upload', options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
**Python**
```python
import requests
url = "https://services.leadconnectorhq.com/conversations/messages/upload"
headers = {
"Authorization": "Bearer ",
"Version": "v3"
}
payload = {
"conversationId": "ve9EPM428h8vShlRW1KT",
"contactId": "ve9EPM428h8vShlRW1KT",
"workflowId": "ve9EPM428h8vShlRW1KT",
"campaignId": "ve9EPM428h8vShlRW1KT",
"attachmentUrls": [],
"isSecureAttachment": "false"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
**PHP**
```php
'https://services.leadconnectorhq.com/conversations/messages/upload',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ',
'Version: v3',
'Content-Type: multipart/form-data',
],
CURLOPT_POSTFIELDS => '{
"conversationId": "ve9EPM428h8vShlRW1KT",
"contactId": "ve9EPM428h8vShlRW1KT",
"workflowId": "ve9EPM428h8vShlRW1KT",
"campaignId": "ve9EPM428h8vShlRW1KT",
"attachmentUrls": [],
"isSecureAttachment": "false"
}',
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
```
**Java**
```java
HttpResponse response = Unirest
.post("https://services.leadconnectorhq.com/conversations/messages/upload")
.header("Authorization", "Bearer ")
.header("Version", "v3")
.header("Content-Type", "multipart/form-data")
.body("{\"conversationId\":\"ve9EPM428h8vShlRW1KT\",\"contactId\":\"ve9EPM428h8vShlRW1KT\",\"workflowId\":\"ve9EPM428h8vShlRW1KT\",\"campaignId\":\"ve9EPM428h8vShlRW1KT\",\"attachmentUrls\":[],\"isSecureAttachment\":\"false\"}")
.asString();
```
**Go**
```go
package main
import (
"fmt"
"net/http"
"io"
"strings"
)
func main() {
url := "https://services.leadconnectorhq.com/conversations/messages/upload"
payload := strings.NewReader(`{
"conversationId": "ve9EPM428h8vShlRW1KT",
"contactId": "ve9EPM428h8vShlRW1KT",
"workflowId": "ve9EPM428h8vShlRW1KT",
"campaignId": "ve9EPM428h8vShlRW1KT",
"attachmentUrls": [],
"isSecureAttachment": "false"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Version", "v3")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
```
**Ruby**
```ruby
require 'uri'
require 'net/http'
url = URI("https://services.leadconnectorhq.com/conversations/messages/upload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer "
request["Version"] = "v3"
request["Content-Type"] = "application/json"
request.body = '{
"conversationId": "ve9EPM428h8vShlRW1KT",
"contactId": "ve9EPM428h8vShlRW1KT",
"workflowId": "ve9EPM428h8vShlRW1KT",
"campaignId": "ve9EPM428h8vShlRW1KT",
"attachmentUrls": [],
"isSecureAttachment": "false"
}'
response = http.request(request)
puts response.read_body
```
**PowerShell**
```powershell
$headers = @{
"Authorization" = "Bearer "
"Version" = "v3"
}
$body = '{
"conversationId": "ve9EPM428h8vShlRW1KT",
"contactId": "ve9EPM428h8vShlRW1KT",
"workflowId": "ve9EPM428h8vShlRW1KT",
"campaignId": "ve9EPM428h8vShlRW1KT",
"attachmentUrls": [],
"isSecureAttachment": "false"
}'
$response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/conversations/messages/upload' -Method 'POST' -Headers $headers -Body $body -ContentType 'multipart/form-data'
$response | ConvertTo-Json
```