Skip to content

Messages

Send a file

Uploads one file as multipart/form-data and sends it to the conversation through the workspace’s active connection (QR-linked number or Cloud API). Returns the stored message with status sent, in the same shape as Send a message; its media_url serves the file you sent. Live listeners receive message.created and conversation.updated events.

POST/api/conversations/{id}/attachments
  • Bearer API key
  • Scope: write
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Path parameters

  • iduuidrequired

    Conversation id.

    Example
    6a1f3c52-8e0b-4d7a-b1f2-93c4d5e6f708

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

multipart/form-data
  • filefilerequired

    The file, as a form part with a file name. Its type is detected from its content together with the file name’s extension; the part’s own Content-Type is ignored. A name without an extension takes the type the content shows.

    Constraints
    One file. Photos: JPEG, PNG, WebP, up to 5 MB. Videos: MP4, 3GP, up to 16 MB. Audio: MP3, OGG (Opus), AAC, AMR, M4A, up to 16 MB. Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, ZIP, up to 16 MB.
    Example
    @invoice-1042.pdf
  • captionstringoptional

    Text shown under the photo, video or document; it becomes the message’s content. Leading and trailing spaces are trimmed.

    Constraints
    At most 1024 characters. Audio files cannot have a caption.
    Example
    Your invoice for October

Response

201 Createdapplication/json

  • iduuid

    Message id in whatsappx.si.

  • whatsapp_message_idstring

    Message id assigned by WhatsApp.

  • conversation_iduuid

    Conversation the message belongs to.

  • sender_jidstring

    WhatsApp id (JID) of the sender. For your own messages, the connected number.

  • sender_namestring

    Sender display name, when WhatsApp provides one (may be empty).

  • contentstring

    Message text. On numbers linked by QR code, images and documents carry their caption here. On the Cloud API, non-text messages are stored as a placeholder such as [image message].

  • message_typestring

    text, image or document on numbers linked by QR code. Non-text messages received through the Cloud API keep the type name Meta sends (for example image or audio) and have no downloadable media.

  • media_urlstringmay be absent

    Path of the downloaded media file, for example /api/media/<workspace>/<file>. Prefix it with https://whatsappx.si and send your API key to download it.

  • mime_typestringmay be absent

    MIME type of the media file.

  • file_namestringmay be absent

    Original file name of a document.

  • file_sizeintegermay be absent

    Media size in bytes.

  • timestamptimestamp

    When the message was sent on WhatsApp (RFC 3339).

  • from_meboolean

    true for messages sent from the connected number (by your team, the API or an automation).

  • statusenum

    received for incoming messages, sent for outgoing ones. Delivered and read receipts are not tracked.

  • edited_attimestampnullable

    When the text was last edited: through the API or the app, or by its sender on WhatsApp. null if never edited.

  • deleted_attimestampnullable

    When the message was deleted for everyone. Its content and media fields are then empty. null if not deleted.

  • created_attimestamp

    When whatsappx.si stored the message (RFC 3339).

Status codes

  • 201Created. The file was sent and stored. message_type is image for a photo and document for everything else (videos and audio included).
  • 400Bad request. file is required, file is empty, send one file per request, send multipart/form-data with a file field, caption is too long (at most 1024 characters), audio files cannot have a caption, invalid conversation id, or the conversation cannot be used for sending (conversation belongs to an inactive channel, conversation has no whatsapp jid, invalid chat jid).
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The API key has the read scope, which only allows GET requests (API key is read-only). A key in another workspace gets API key belongs to a different workspace.
  • 404Not found. The conversation does not exist in this workspace, belongs to the inactive connection, or (for agents signed in to the app) is not assigned to you.
  • 409Conflict. The WhatsApp connection is not ready to send (whatsapp is not connected).
  • 413Too large. The file is over the limit of its type (file too large: images can be up to 5 MB, file too large: videos, audio and documents can be up to 16 MB), or the whole request is.
  • 415Unsupported type. The file type cannot be sent, or the content is not what the extension says (unsupported file type: the file is not a valid .png file). Cloud API numbers cannot send ZIP files.
  • 429Too many requests. More than 30 files in a minute from this workspace (too many attempts, please wait a minute and try again), with a Retry-After header. The API key rate limits apply as well.
  • 500Server error. WhatsApp or Meta rejected the file, or it could not be stored. The error carries the reason.

What does the customer receive?

Photos arrive as photos, videos as videos, audio files as audio messages (not voice notes) and everything else as a document under its file name. The file name is cleaned before it is sent: any folder path, control characters and the characters <>:"/\|?* are removed, and it always ends in an extension of the detected type (a photo named IMG_0001 is sent as IMG_0001.jpg).

How is the sent file stored?

Like a received one: the message's media_url (/api/media/<workspace>/<file>) serves the file you sent, with your API key, under the rules in List messages. The original name is the message's file_name.