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

# Send Message

> Sends a message to a conversation

Send a message to an existing conversation on behalf of your agent.

## Message Types

You can send two main types of messages:

* **Unified messages** — Sent rich text messages with images, videos, audio, documents, buttons, and more
* **Template messages** — Pre-approved messages that can initiate or re-engage conversations

You can additionally send cta and text speicic messages, though these are deprecated and will be removed in the future.
We will be adding support for other specific message types, such as contacts, location and call requests in the future.

> [!WARNING]
>
> **Check conversation status first!** You can only send regular (non-template) messages to **active** conversations. Use the [Get Conversation](https://docs.wassist.app/api-reference/conversations/get.md) endpoint to verify the conversation is active before sending.

> [!NOTE]
>
> **Billing**: Template messages are billed by Meta according to their [pricing tiers](https://developers.facebook.com/docs/whatsapp/pricing). Regular messages within the 24-hour customer service window are free.

## Service window closed

Sending anything other than a template after the 24-hour window has closed returns:

```json theme={null}
HTTP 400
{
  "error": "Message failed to send, the conversation is not active. The user has not responded in the last 24 hours. You can only send a template message.",
  "code": "service_window_closed"
}
```

Match on `code`, not the text. To act before this happens, check `active` and `chatWindowRemainingTime` on the conversation, or subscribe to the `subscription.service_window.expiring` and `.closed` [webhook events](https://docs.wassist.app/guides/webhooks/routing.md#service-window-lifecycle).

## Media URLs

`unified.media.url` must be reachable when you call this endpoint. We download the file straight away and host our own copy, so short-lived pre-signed URLs are fine. We check the file type with a `HEAD` request, falling back to a one-byte `GET` for URLs that only allow `GET`, such as S3 and GCS pre-signed URLs. The `Content-Type` must be one WhatsApp supports.

## Template variables

```json theme={null}
{
  "type": "template",
  "template": {
    "name": "order_update",
    "variables": {
      "body": ["Eddy", "#1234"],
      "header": ["Your order"],
      "buttons": ["track/1234"]
    }
  }
}
```

* `body` and `header` take a list for positional (`{{1}}`) templates, or an object keyed by variable name for named templates. An image header takes `{ "link": "https://..." }`.
* `buttons` is only needed when the template has a dynamic button (a URL with a variable, or a flow). Then pass one value per button, in order. Values for static buttons, such as quick replies, are ignored. Templates with only static buttons can leave `buttons` out.
* The template is looked up by name. Keep one language per template name.

## Reactions

React to a message in the conversation, or remove your reaction, using the message's Wassist ID:

```json theme={null}
{ "type": "reaction", "reaction": { "messageId": "7f2c...91", "emoji": "👍" } }
```

Send `"emoji": null` or leave it out to remove the reaction. Reactions follow the same 24-hour rule as other non-template messages. Customer reactions arrive as the [`message.reaction.updated`](https://docs.wassist.app/concepts/webhooks#message-reaction-updated) webhook event.

## Quoted replies

To reply to a specific message, so it shows quoted above your reply in WhatsApp, add `replyTo` with the message's Wassist ID. This is the same `message.id` you get on [`message.received`](https://docs.wassist.app/concepts/webhooks#message-received) webhook events. It works on `text` and `unified` messages:

```json theme={null}
{ "type": "text", "text": { "body": "Yes, that one ships tomorrow" }, "replyTo": "7f2c...91" }
```

The sent message comes back with `replyTo` set. Errors:

| Situation | Response |
| - | - |
| `replyTo` on a `template`, `cta` or `reaction` message | `400` validation error on `replyTo`. |
| The message isn't in this conversation | `404` with `code: "message_not_found"`. |
| The message never reached WhatsApp, or is a reaction | `400` with `code: "message_not_quotable"`. |

## Idempotency

Send an `Idempotency-Key` header (any unique string up to 255 characters, such as a UUID) to make retries safe. Keys are scoped to your API key and kept for 24 hours.

| Situation | Response |
| - | - |
| First request | Sent as normal (`201`). |
| Repeat with the same body after it succeeded | The original response, with `200` and `Idempotent-Replayed: true`. Nothing is sent again. |
| Repeat while the first is still running | `409` with `code: "idempotency_in_progress"`. |
| Same key with a different body | `422` with `code: "idempotency_key_reused"`. |
| The first request failed | Nothing is stored, so you can retry with the same key. |

`POST /api/v1/conversations/` supports the same header.


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/conversations/{id}/messages/
openapi: 3.0.3
info:
  title: Wassist API
  version: 1.0.0
  description: API for building WhatsApp AI agents
servers:
  - url: https://alpha-plagiocephalic-darrell.ngrok-free.dev
    description: Development
security: []
tags:
  - name: Agents
    description: Create and manage AI agents
  - name: Conversations
    description: Chat conversations and messages
  - name: WhatsApp
    description: WhatsApp Business account management
  - name: Contacts
    description: Contact management
  - name: Integrations
    description: Third-party integrations
paths:
  /api/v1/conversations/{id}/messages/:
    post:
      tags:
        - api
      description: |-
        Get or send messages in a conversation.

        POST supports unified input for text or template messages:
        - type: 'text' with 'message' field
        - type: 'template' with 'templateName' and optional 'variables' fields
      operationId: api_v1_conversations_messages_create
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SendMessageInput:
      type: object
      description: Unified input for sending text, template, or CTA URL messages.
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/SendMessageInputTypeEnum'
          description: >-
            The type of message to send: 'text', 'template', 'cta', or
            'unified'.


            * `text` - text

            * `template` - template

            * `cta` - cta

            * `unified` - unified
        text:
          $ref: '#/components/schemas/SendMessageTextInput'
        template:
          $ref: '#/components/schemas/SendMessageTemplateInput'
        cta:
          $ref: '#/components/schemas/SendMessageCtaInput'
        unified:
          $ref: '#/components/schemas/UnifiedWhatsappMessageInput'
        replyTo:
          type: string
          format: uuid
          nullable: true
          description: >-
            The Wassist ID of the message to quote, as sent on webhooks. Only
            for 'text' and 'unified' messages.
      required:
        - type
    Message:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        role:
          type: string
          readOnly: true
        type:
          type: string
          readOnly: true
        status:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        replyTo:
          type: string
          readOnly: true
        source:
          type: string
        supportHandoff:
          type: string
          readOnly: true
        text:
          type: string
          readOnly: true
        image:
          type: string
          readOnly: true
        cta:
          type: string
          readOnly: true
        listSelection:
          type: string
          readOnly: true
        template:
          type: string
          readOnly: true
        unified:
          type: string
          readOnly: true
        quickReply:
          type: string
          readOnly: true
        toolExecutions:
          type: string
          readOnly: true
        referral:
          allOf:
            - $ref: '#/components/schemas/MessageReferral'
          nullable: true
          readOnly: true
      required:
        - createdAt
        - cta
        - id
        - image
        - listSelection
        - quickReply
        - referral
        - replyTo
        - role
        - source
        - status
        - supportHandoff
        - template
        - text
        - toolExecutions
        - type
        - unified
    SendMessageInputTypeEnum:
      enum:
        - text
        - template
        - cta
        - unified
      type: string
      description: |-
        * `text` - text
        * `template` - template
        * `cta` - cta
        * `unified` - unified
    SendMessageTextInput:
      type: object
      properties:
        body:
          type: string
      required:
        - body
    SendMessageTemplateInput:
      type: object
      properties:
        name:
          type: string
        variables:
          $ref: '#/components/schemas/TemplateVariables'
      required:
        - name
    SendMessageCtaInput:
      type: object
      properties:
        body:
          type: string
          description: Message body text.
          maxLength: 1024
        buttonText:
          type: string
          description: Button label (max 20 chars).
          maxLength: 20
        url:
          type: string
          format: uri
          description: URL to open when button is tapped.
        image:
          $ref: '#/components/schemas/SendMessageCtaImageInput'
      required:
        - body
        - buttonText
        - url
    UnifiedWhatsappMessageInput:
      type: object
      properties:
        text:
          type: string
          maxLength: 1024
        footer:
          type: string
          maxLength: 60
        media:
          $ref: '#/components/schemas/UnifiedWhatsappMediaInput'
        buttons:
          type: array
          items:
            $ref: '#/components/schemas/UnifiedWhatsappButtonInput'
    MessageReferral:
      type: object
      description: |-
        Click-to-WhatsApp ad referral attached to an inbound message.

        Shared by the REST API and outbound webhooks.
      properties:
        messageId:
          type: string
          format: uuid
        sourceType:
          type: string
          nullable: true
        sourceId:
          type: string
          nullable: true
        sourceUrl:
          type: string
          nullable: true
        headline:
          type: string
          nullable: true
        body:
          type: string
          nullable: true
        mediaType:
          type: string
          nullable: true
        imageUrl:
          type: string
          nullable: true
        videoUrl:
          type: string
          nullable: true
        thumbnailUrl:
          type: string
          nullable: true
        ctwaClid:
          type: string
          nullable: true
        welcomeMessage:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - body
        - createdAt
        - ctwaClid
        - headline
        - imageUrl
        - mediaType
        - messageId
        - sourceId
        - sourceType
        - sourceUrl
        - thumbnailUrl
        - videoUrl
        - welcomeMessage
    TemplateVariables:
      type: object
      properties:
        body:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
              additionalProperties:
                type: string
        header:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
              additionalProperties:
                type: string
            - type: object
              properties:
                link:
                  type: string
                id:
                  type: string
        buttons:
          type: array
          items:
            type: string
        cards:
          type: array
          items:
            $ref: '#/components/schemas/Card'
    SendMessageCtaImageInput:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Image URL.
      required:
        - url
    UnifiedWhatsappMediaInput:
      type: object
      properties:
        url:
          type: string
          format: uri
      required:
        - url
    UnifiedWhatsappButtonInput:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/UnifiedWhatsappButtonInputTypeEnum'
        text:
          type: string
          maxLength: 20
        url:
          type: string
          format: uri
        quickReplyId:
          type: string
          maxLength: 200
      required:
        - text
        - type
    Card:
      type: object
      properties:
        body:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
              additionalProperties:
                type: string
        header:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
              additionalProperties:
                type: string
            - type: object
              properties:
                link:
                  type: string
                id:
                  type: string
        buttons:
          type: array
          items:
            type: string
    UnifiedWhatsappButtonInputTypeEnum:
      enum:
        - url
        - quick_reply
      type: string
      description: |-
        * `url` - url
        * `quick_reply` - quick_reply
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication. Pass your API key in the X-API-Key header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.