> ## Documentation Index
> Fetch the complete documentation index at: https://clapvo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a message

> Send a WhatsApp message from one of your connected numbers to a recipient.

This single endpoint sends every message type — text, image, document, video, and audio. The `message.type` field decides which one is sent. Text messages use `message.message` for the text; media messages add a `message.media` object instead. Use the **Examples** dropdown in the request panel to switch between message types.

On success the message is queued for delivery and the response returns `state: "PUBLISHED"`.

## Status codes

Each response returns a standard HTTP status code so you can tell what happened at a glance.

| Code  | Status               | Description                                           |
| ----- | -------------------- | ----------------------------------------------------- |
| `200` | Success              | Message queued for delivery                           |
| `400` | Bad Request          | Invalid or missing required parameters                |
| `401` | Unauthorized         | Invalid or expired API token                          |
| `403` | Access denied        | The token lacks permission for this action            |
| `404` | Connection not found | The `from` number is not a connection on your account |


## OpenAPI

````yaml api-reference/openapi.json POST /chat/api/v1/public/message/send
openapi: 3.1.0
info:
  title: Clapvo Public API
  description: >-
    Send WhatsApp messages programmatically through Clapvo. Authenticate every
    request with your API token in the `x-api-key` header.
  version: 1.0.0
servers:
  - url: https://api.clapvo.com
    description: Production
security:
  - apiKeyAuth: []
paths:
  /chat/api/v1/public/message/send:
    post:
      tags:
        - Messages
      summary: Send a message
      description: >-
        Send a WhatsApp message from one of your connected numbers to a
        recipient.


        This single endpoint sends every message type — text, image, document,
        video, and audio. The `message.type` field decides which one is sent.
        Text messages use `message.message` for the text; media messages add a
        `message.media` object instead. Use the **Examples** dropdown in the
        request panel to switch between message types.


        On success the message is queued for delivery and the response returns
        `state: "PUBLISHED"`.
      operationId: sendMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
            examples:
              text:
                summary: Text message
                value:
                  from: '918495632548'
                  message:
                    type: message
                    message: ok public
                  to: '918965742135'
              image:
                summary: Image
                value:
                  from: '918495632548'
                  message:
                    type: image
                    media:
                      name: 10202905 (1).jpg
                      url: >-
                        https://clapvo-space.nyc3.cdn.digitaloceanspaces.com/clapvo-v1/c3a8b4b2-7c4a-4fd1-a1fb-9f32ab6c9e21/1af03df7-2cc4-416f-9022-e9b22e7032e1/chat/image/10202905__1__1782191001290.jpg
                      caption: test caption
                  to: '918965742135'
              document:
                summary: Document / PDF
                value:
                  from: '918495632548'
                  message:
                    type: document
                    media:
                      name: pdf-test.pdf
                      url: >-
                        https://clapvo-space.nyc3.cdn.digitaloceanspaces.com/clapvo-v1/c3a8b4b2-7c4a-4fd1-a1fb-9f32ab6c9e21/1af03df7-2cc4-416f-9022-e9b22e7032e1/chat/document/pdf_test_1782191111069.pdf
                      caption: ''
                  to: '918965742135'
              video:
                summary: Video
                value:
                  from: '918495632548'
                  message:
                    type: video
                    media:
                      name: mov_bbb.mp4
                      url: >-
                        https://clapvo-space.nyc3.cdn.digitaloceanspaces.com/clapvo-v1/c3a8b4b2-7c4a-4fd1-a1fb-9f32ab6c9e21/1af03df7-2cc4-416f-9022-e9b22e7032e1/chat/video/mov_bbb_1782191190623.mp4
                      caption: testing video caption
                  to: '918965742135'
              audio:
                summary: Audio
                value:
                  from: '918495632548'
                  message:
                    type: audio
                    media:
                      name: sample-6s.mp3
                      url: >-
                        https://clapvo-space.nyc3.cdn.digitaloceanspaces.com/clapvo-v1/c3a8b4b2-7c4a-4fd1-a1fb-9f32ab6c9e21/1af03df7-2cc4-416f-9022-e9b22e7032e1/chat/audio/sample_6s_1782191259216.mp3
                      caption: ''
                  to: '918965742135'
      responses:
        '200':
          description: Success — message queued for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
              example:
                success: true
                code: HC-1
                name: success_200
                data:
                  state: QUEUED
                message: Request was successful.
        '400':
          description: Bad Request — invalid or missing required parameters.
        '401':
          description: Unauthorized — invalid or expired API token.
        '403':
          description: Access denied — the token does not have permission for this action.
        '404':
          description: >-
            Connection not found — the `from` number is not a connection on your
            account.
      security:
        - apiKeyAuth: []
components:
  schemas:
    SendMessageRequest:
      type: object
      required:
        - from
        - message
        - to
      properties:
        from:
          type: string
          description: >-
            Sender's WhatsApp number — the number the message is sent **from**.
            Must be a WhatsApp number connected to your Clapvo account. Use
            international format with the country code and **no** leading `+`,
            spaces, or dashes (e.g. `918495632548` for +91 84956 32548).
          example: '918495632548'
        to:
          type: string
          description: >-
            Recipient's WhatsApp number — the number the message is sent **to**.
            Use the same international format as `from`: country code, no
            leading `+`, spaces, or dashes.
          example: '918965742135'
        message:
          allOf:
            - $ref: '#/components/schemas/MessageObject'
          description: >-
            The message content. Its fields change with `message.type`: text
            messages use `type` + `message`, while media messages use `type` + a
            `media` object.
    SendMessageResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
          example: true
        code:
          type: string
          description: Clapvo status code.
          example: HC-1
        name:
          type: string
          description: Machine-readable status name.
          example: success_200
        data:
          type: object
          properties:
            state:
              type: string
              description: >-
                The delivery state of the message. `QUEUED` means Clapvo has
                accepted your request and added the message to the sending queue
                — messages are dispatched one by one, so this confirms receipt,
                not final delivery. To verify whether a message was actually
                sent, check your API logs in Clapvo.
              example: QUEUED
        message:
          type: string
          description: Human-readable status message.
          example: Request was successful.
    MessageObject:
      type: object
      required:
        - type
      description: The message payload. The fields you supply depend on `type`.
      properties:
        type:
          type: string
          description: >-
            What kind of message to send. This controls the rest of the payload:


            - `message` — plain text. Put the text in `message.message`; no
            `media`.

            - `image` — a photo. Include a `media` object.

            - `document` — a file such as a PDF. Include a `media` object.

            - `video` — a video clip. Include a `media` object.

            - `audio` — an audio clip or voice note. Include a `media` object.
          enum:
            - message
            - image
            - document
            - video
            - audio
        message:
          type: string
          description: >-
            The text body of the message. **Required** for the `message` (text)
            type — this is the text the recipient receives. Not used for media
            types; put any visible text in the media object's `caption` instead.
          example: ok public
        media:
          allOf:
            - $ref: '#/components/schemas/MediaItem'
          description: >-
            The file to attach. **Required** for `image`, `document`, `video`,
            and `audio` types; omit it for text messages.
    MediaItem:
      type: object
      required:
        - name
        - url
      properties:
        name:
          type: string
          description: >-
            The file name shown to the recipient, including its extension (e.g.
            `.jpg`, `.pdf`, `.mp4`, `.mp3`). **Required.**
          example: pdf-test.pdf
        url:
          type: string
          format: uri
          description: >-
            A publicly accessible URL Clapvo downloads the file from before
            sending. Must be reachable without authentication. **Required.**
          example: >-
            https://clapvo-space.nyc3.cdn.digitaloceanspaces.com/.../pdf_test_1782191111069.pdf
        caption:
          type: string
          description: >-
            Optional text shown beneath the media (ignored for `audio`). Send an
            empty string `""` for no caption.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Clapvo API token. Pass it in the `x-api-key` request header.

````