Use an Attachment in a Message

Once you have an attachment UUID (from either /upload or /from-url), you reference it by UUID in the attachments array on POST /api/v1/messages.

Send an image

curl -X POST "https://api.sendseven.com/api/v1/messages" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_8f3a2b1c",
    "text": "Here is the photo you asked about.",
    "message_type": "image",
    "attachments": ["9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7"]
  }'

The attachments array takes one or more UUIDs. The server resolves each UUID to a stored file (scoped to your tenant), then delivers it on the channel. A bare string is accepted too — "attachments": "9b3f...e7" means the same as a one-element array.

Several attachments in one request

Channel	Result
Email	One email, all files attached.
Live Chat	One widget message carrying all files.
WhatsApp, Telegram, Messenger, Instagram, RCS, SMS, Browser Push	One message per attachment, in the order you listed them.

On the channels that split the send, text becomes the caption of the first message only, each message is typed from its own file, and each message has its own status, its own webhooks, and is billed as a message.

The response is still a single message object — the first one — plus a related_message_ids array holding the IDs of the others (empty whenever the send was not split):

{
  "id": "msg_a1b2c3",
  "status": "pending",
  "attachments": [{ "id": "9b3f1a8e-7c2d-4e5b-9f01-12a3b4c5d6e7", "filename": "photo-1.jpg" }],
  "related_message_ids": ["msg_d4e5f6", "msg_g7h8i9"]
}

Poll each ID with GET /api/v1/messages/{id} to follow every part. See Send Media Messages for the full behaviour.

Important: only UUIDs are accepted

attachments is a list of attachment UUIDs, not URLs. A request that puts a URL there is rejected with 422 Unprocessable Entity:

// REJECTED -- "attachments" must be UUIDs, not URLs
{
  "conversation_id": "conv_8f3a2b1c",
  "message_type": "image",
  "attachments": ["https://cdn.example.com/photo.jpg"]
}

If you have a URL and want to send it as a media message, the right flow is:

1. Call POST /api/v1/attachments/from-url with that URL.
2. Take the returned id (a UUID).
3. Pass that UUID in attachments[].

Re-using the same UUID

You can reference the same attachment UUID in as many messages as you want, on as many channels as you want. The file is stored once and not re-uploaded.

# Same product image, two different conversations, two different channels.
curl ... -d '{"conversation_id":"conv_wa_001","attachments":["9b3f...e7"], ...}'
curl ... -d '{"conversation_id":"conv_email_99","attachments":["9b3f...e7"], ...}'

Channel adapters take care of the channel-specific delivery (Meta media upload for WhatsApp, MIME-attached file for Email, etc.) -- you only need the UUID.

Errors

Status	Cause
422	attachments contained something that wasn't a UUID. Use from-url if you have a URL.
404 Attachment {id} not found	UUID is well-formed but no such attachment exists for your tenant.
403	Your token lacks messages:create.

See Errors for the full list.