Skip to content

Messages

Send a message

Sends a text message to the conversation through the workspace’s active connection (QR-linked number or Cloud API) and returns the stored message with status sent. Live listeners receive message.created and conversation.updated events.

POST/api/conversations/{id}/messages
  • 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

application/json
  • bodystringrequired

    Message text. Leading and trailing spaces are trimmed.

    Constraints
    Not empty. On numbers linked by QR code, at most 4096 bytes.
    Example
    Yes, it is ready. We are open until 6 pm.

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.

  • created_attimestamp

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

Status codes

  • 201Created. The message was sent and stored.
  • 400Bad request. message body is required, message body too long, invalid request body, 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).
  • 500Server error. WhatsApp or Meta rejected the message, or it could not be stored. The error carries the reason.