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

# Add Message

> Send a user message to a chat and receive the assistant's reply.

Add a user message to a chat. The assistant processes the message and returns a reply, which may include follow-up suggestions and product recommendations.

## Authentication

This request requires your API key in the `x-api-key` header.

## Request

<ParamField path="chatId" type="string" required>
  ID of the chat to add the message to.
</ParamField>

<ParamField query="store" type="string">
  Optional query parameter.
</ParamField>

<ParamField body="message" type="string" required>
  The user's message text.
</ParamField>

<ParamField body="currentUrl" type="string" required>
  The URL of the page the user is currently viewing. Used to give the assistant page context.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  ID of the created message.
</ResponseField>

<ResponseField name="chatId" type="string" required>
  ID of the chat the message belongs to.
</ResponseField>

<ResponseField name="type" type="string" required>
  The message type, for example whether it originated from the user or the assistant.
</ResponseField>

<ResponseField name="content" type="string" required>
  The message text content.
</ResponseField>

<ResponseField name="suggestions" type="string[]">
  Optional list of suggested follow-up questions.
</ResponseField>

<ResponseField name="products" type="object[]">
  Optional list of recommended products.

  <Expandable title="MessageProductDto">
    <ResponseField name="gtin" type="string" required>
      Global Trade Item Number of the product.
    </ResponseField>

    <ResponseField name="brand" type="string" required>
      Brand name.
    </ResponseField>

    <ResponseField name="designation" type="string" required>
      Product name or designation.
    </ResponseField>

    <ResponseField name="url" type="string" required>
      URL of the product detail page.
    </ResponseField>

    <ResponseField name="image" type="string" required>
      URL of the product image.
    </ResponseField>

    <ResponseField name="price" type="number" required>
      Product price.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Currency code of the price, for example `EUR`.
    </ResponseField>

    <ResponseField name="priceInfo" type="string">
      Additional price information.
    </ResponseField>

    <ResponseField name="location" type="object[]">
      Key/value pairs describing the product location.

      <Expandable title="MessageProductLocationDto">
        <ResponseField name="key" type="string" required>
          Location attribute name.
        </ResponseField>

        <ResponseField name="value" type="string" required>
          Location attribute value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="availability" type="object">
      Stock availability of the product.

      <Expandable title="MessageAvailabilityDto">
        <ResponseField name="status" type="string" required>
          Availability status.
        </ResponseField>

        <ResponseField name="quantity" type="number" required>
          Available quantity.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="category" type="string">
      Product category.
    </ResponseField>

    <ResponseField name="query" type="string">
      Search query that surfaced the product.
    </ResponseField>

    <ResponseField name="description" type="string">
      Product description.
    </ResponseField>

    <ResponseField name="recommendationText" type="string">
      Text explaining why the product is recommended.
    </ResponseField>

    <ResponseField name="flags" type="object[]">
      Highlight badges attached to the product.

      <Expandable title="ProductFlags">
        <ResponseField name="type" type="string" required>
          Flag type.
        </ResponseField>

        <ResponseField name="title" type="string" required>
          Flag title.
        </ResponseField>

        <ResponseField name="text" type="string" required>
          Flag text.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp of when the message was created.
</ResponseField>

<Note>
  To receive the assistant's streamed response and tool activity in real time, open the [Message Events](/en/api-reference/backend/messages/message-events) stream for the same `chatId`.
</Note>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.yourhomie.ai/v1/chats/ab12cd34-ef56-7890-ab12-cd34ef567890/messages \
    -H "x-api-key: homie_sk_live_8f3a..." \
    -H "Content-Type: application/json" \
    -d '{
      "message": "Do you have a waterproof jacket in blue?",
      "currentUrl": "https://shop.example.com/jackets"
    }'
  ```

  ```javascript JavaScript (fetch) theme={null}
  const chatId = "ab12cd34-ef56-7890-ab12-cd34ef567890";

  const res = await fetch(
    `https://api.yourhomie.ai/v1/chats/${chatId}/messages`,
    {
      method: "POST",
      headers: {
        "x-api-key": "homie_sk_live_8f3a...",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message: "Do you have a waterproof jacket in blue?",
        currentUrl: "https://shop.example.com/jackets",
      }),
    },
  );

  const message = await res.json();
  ```
</CodeGroup>

### Success response

```json theme={null}
{
  "id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f2a3b4c5d",
  "chatId": "ab12cd34-ef56-7890-ab12-cd34ef567890",
  "type": "assistant",
  "content": "Yes, here is a waterproof jacket available in blue.",
  "suggestions": [
    "What sizes are available?",
    "Is it machine washable?"
  ],
  "products": [
    {
      "gtin": "4006381333931",
      "brand": "Acme",
      "designation": "All-Weather Jacket",
      "url": "https://shop.example.com/p/all-weather-jacket",
      "image": "https://shop.example.com/img/all-weather-jacket.jpg",
      "price": 129.99,
      "currency": "EUR",
      "availability": {
        "status": "in_stock",
        "quantity": 12
      }
    }
  ],
  "createdAt": "2025-10-16T11:45:02.512Z"
}
```

### Error response

```json theme={null}
{
  "message": "Monthly message quota reached"
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/chats/{chatId}/messages
openapi: 3.0.0
info:
  title: homie AI API
  description: The homie AI API description
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.yourhomie.ai
    description: Production server
security: []
tags:
  - name: Chat
    description: ''
  - name: Knowledge
    description: Public, CORS-enabled endpoints for PDP question sets
paths:
  /v1/chats/{chatId}/messages:
    post:
      tags:
        - Chat
      summary: Add Message to Chat
      operationId: ChatController_addMessageToChat
      parameters:
        - name: chatId
          required: true
          in: path
          schema:
            type: string
        - name: store
          required: false
          in: query
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequestDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDto'
      security:
        - bearer: []
components:
  schemas:
    MessageRequestDto:
      type: object
      properties:
        message:
          type: string
        currentUrl:
          type: string
      required:
        - message
        - currentUrl
    MessageDto:
      type: object
      properties:
        id:
          type: string
        chatId:
          type: string
        type:
          type: string
        content:
          type: string
        suggestions:
          type: array
          items:
            type: string
        products:
          type: array
          items:
            $ref: '#/components/schemas/MessageProductDto'
        createdAt:
          type: string
      required:
        - id
        - chatId
        - type
        - content
        - createdAt
    MessageProductDto:
      type: object
      properties:
        gtin:
          type: string
        brand:
          type: string
        designation:
          type: string
        url:
          type: string
          format: uri
        image:
          type: string
          format: uri
        price:
          type: number
        priceInfo:
          type: string
        currency:
          type: string
        location:
          type: array
          items:
            $ref: '#/components/schemas/MessageProductLocationDto'
        availability:
          $ref: '#/components/schemas/MessageAvailabilityDto'
        category:
          type: string
        query:
          type: string
        description:
          type: string
        recommendationText:
          type: string
        flags:
          type: array
          items:
            $ref: '#/components/schemas/ProductFlags'
      required:
        - gtin
        - brand
        - designation
        - url
        - image
        - price
        - currency
    MessageProductLocationDto:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
    MessageAvailabilityDto:
      type: object
      properties:
        status:
          type: string
        quantity:
          type: number
      required:
        - status
        - quantity
    ProductFlags:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        text:
          type: string
      required:
        - type
        - title
        - text
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````