Skip to main content
POST
/
api
/
messages
Send with Attachments
curl --request POST \
  --url https://app.tuco.ai/api/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "attachmentUrls": [
    "<string>"
  ],
  "attachmentNames": [
    "<string>"
  ],
  "message": "<string>"
}
'
Send attachments alongside or instead of text messages. Tuco handles downloading, caching, and delivering files through your device relay.

​
Request body

Use the same POST /api/messages endpoint. Add attachmentUrls to your request:
​
attachmentUrls
string[]
required
Array of public URLs to attach. Max 2 attachments per message, max 25 MB each.
​
attachmentNames
string[]
Optional display names for each attachment (same order as attachmentUrls). When omitted, the filename from the URL is used.
​
message
string
Optional text to send with the attachments. When omitted, only the attachment is sent (no “Attachment” placeholder text).
All other POST /api/messages body fields apply here too — including forceFallback (skip the iMessage availability check and route straight to your configured fallback). One caveat: the SMS/fallback channel is text-only, so a forceFallback send delivers the message text but not the attachments — those go over iMessage only.

​
Supported formats

CategoryFormatsNotes
ImagesPNG, JPG, JPEG, GIF, WebP, HEICRenders inline in iMessage
VideoMP4, MOVUp to 25 MB. Renders as playable video
Audio / Voice notesCAF.caf files render as native iMessage voice notes (the play button bubble). Record with Core Audio or convert from other formats
DocumentsPDFRenders as attachment preview
Voice notes must be .caf format. MP3, WAV, M4A, and other audio formats are sent as generic file attachments, not as the native iMessage voice note bubble. To get the recognizable play-button bubble, use .caf (Core Audio Format).

​
Examples

curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Check this out!",
    "leadId": "667f1f77bcf86cd799439012",
    "attachmentUrls": ["https://example.com/photo.jpg"]
  }'

​
Limits

LimitValue
Max attachments per message2
Max file size per attachment25 MB
Supported sourcesAny public URL, UploadThing URLs, Blob URLs belonging to your workspace
Attachment caching: When you send the same attachment URL multiple times (e.g. a promo video in a campaign), Tuco caches it per line. The second send skips download + upload, making delivery significantly faster.

​
Device gap

Each attachment counts as part of a single message — not a separate send. Sending text + video in one API call uses one device gap (30s), not two. This is significantly faster than sending them as separate messages.
For automations that send a video followed by a text CTA, combine them into a single API call with message + attachmentUrls instead of two separate calls. This halves your device gap overhead.

​
Error responses

StatusWhenBody
400attachmentUrls not an array{ "error": "attachmentUrls must be an array" }
400More than 2 attachments{ "error": "Maximum 2 attachments per message" }
403URL doesn’t belong to workspace{ "error": "Attachment URL does not belong to this organization" }