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

# Create New Message

> Create a new message in the conversation.

Use `application/json` for text messages and `multipart/form-data` when the
message includes file attachments.

### Multipart attachment request

Send files with the `attachments[]` form field. `curl -F` sets the
`multipart/form-data` content type and boundary automatically.

```bash
curl -X POST "https://chat.chatclean.com.br/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages" \
  -H "Authorization: Bearer <your-api-token>" \
  -F "content=Here is the screenshot" \
  -F "message_type=outgoing" \
  -F "private=false" \
  -F "attachments[]=@/path/to/screenshot.png"
```

## WhatsApp Template Messages

For WhatsApp channels, you can send structured template messages using the `template_params` field. 
Templates must be pre-approved in WhatsApp Business Manager.

By default, `content` is treated as the already-rendered transcript text for
compatibility with existing API and mobile clients. To submit the original
template body instead, set `template_params.content_mode` to `raw_template`;
ChatClean will substitute `processed_params.body` before saving the transcript.

### Example Templates

**Text with Image Header:**
```json
{
  "content": "Hi your order 121212 is confirmed. Please wait for further updates",
  "template_params": {
    "name": "order_confirmation",
    "category": "MARKETING",
    "language": "en",
    "processed_params": {
      "body": {
        "1": "121212"
      },
      "header": {
        "media_url": "https://picsum.photos/200/300",
        "media_type": "image"
      }
    }
  }
}
```

**Text with Copy Code Button:**
```json
{
  "content": "Special offer! Get 30% off your next purchase. Use the code below",
  "template_params": {
    "name": "discount_coupon",
    "category": "MARKETING",
    "language": "en",
    "processed_params": {
      "body": {
        "discount_percentage": "30"
      },
      "buttons": [{
        "type": "copy_code",
        "parameter": "SAVE20"
      }]
    }
  }
}
```




## OpenAPI

````yaml /openapi.json post /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages
openapi: 3.1.0
info:
  title: ChatClean API
  description: API REST do ChatClean.
  version: 1.1.0
  contact:
    email: contato@chatclean.com.br
servers:
  - url: https://chat.chatclean.com.br
security: []
tags:
  - name: Account AgentBots
    description: Account-specific Agent Bots
  - name: Agents
    description: Agent management APIs
  - name: Campaigns
    description: >-
      Create, schedule, and manage campaigns. Requires an account administrator
      and API access enabled for the account.
  - name: Canned Responses
    description: Pre-defined responses for common queries
  - name: Contacts
    description: Contact management APIs
  - name: Contact Labels
    description: Manage contact labels
  - name: Conversation Assignments
    description: Manage conversation assignments
  - name: Conversation Labels
    description: Manage conversation labels
  - name: Conversations
    description: Conversation management APIs
  - name: Custom Attributes
    description: Custom fields for contacts and conversations
  - name: Custom Filters
    description: Saved filters for conversations
  - name: Inboxes
    description: Communication channels setup
  - name: Integrations
    description: Third-party integrations
  - name: Labels
    description: Account label management APIs
  - name: Messages
    description: Message management APIs
  - name: Profile
    description: User profile APIs
  - name: Reports
    description: Analytics and reporting APIs
  - name: Teams
    description: Team management APIs
  - name: Webhooks
    description: Event notification webhooks
  - name: Automation Rule
    description: Workflow automation rules
  - name: Help Center
    description: Knowledge base management
  - name: Contacts API
    description: Public contact APIs
  - name: Conversations API
    description: Public conversation APIs
  - name: Messages API
    description: Public message APIs
paths:
  /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages:
    parameters:
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/conversation_id'
    post:
      tags:
        - Messages
      summary: Create New Message
      description: >
        Create a new message in the conversation.


        Use `application/json` for text messages and `multipart/form-data` when
        the

        message includes file attachments.


        ### Multipart attachment request


        Send files with the `attachments[]` form field. `curl -F` sets the

        `multipart/form-data` content type and boundary automatically.


        ```bash

        curl -X POST
        "https://chat.chatclean.com.br/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages"
        \
          -H "Authorization: Bearer <your-api-token>" \
          -F "content=Here is the screenshot" \
          -F "message_type=outgoing" \
          -F "private=false" \
          -F "attachments[]=@/path/to/screenshot.png"
        ```


        ## WhatsApp Template Messages


        For WhatsApp channels, you can send structured template messages using
        the `template_params` field. 

        Templates must be pre-approved in WhatsApp Business Manager.


        By default, `content` is treated as the already-rendered transcript text
        for

        compatibility with existing API and mobile clients. To submit the
        original

        template body instead, set `template_params.content_mode` to
        `raw_template`;

        ChatClean will substitute `processed_params.body` before saving the
        transcript.


        ### Example Templates


        **Text with Image Header:**

        ```json

        {
          "content": "Hi your order 121212 is confirmed. Please wait for further updates",
          "template_params": {
            "name": "order_confirmation",
            "category": "MARKETING",
            "language": "en",
            "processed_params": {
              "body": {
                "1": "121212"
              },
              "header": {
                "media_url": "https://picsum.photos/200/300",
                "media_type": "image"
              }
            }
          }
        }

        ```


        **Text with Copy Code Button:**

        ```json

        {
          "content": "Special offer! Get 30% off your next purchase. Use the code below",
          "template_params": {
            "name": "discount_coupon",
            "category": "MARKETING",
            "language": "en",
            "processed_params": {
              "body": {
                "discount_percentage": "30"
              },
              "buttons": [{
                "type": "copy_code",
                "parameter": "SAVE20"
              }]
            }
          }
        }

        ```
      operationId: create-a-new-message-in-a-conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/conversation_message_create_payload'
          multipart/form-data:
            schema:
              type: object
              description: Form data payload for creating a message with file attachments.
              example:
                content: Here is the screenshot
                message_type: outgoing
                private: false
                attachments[]:
                  - screenshot.png
              properties:
                content:
                  type: string
                  description: The content of the message
                  example: Here is the screenshot
                message_type:
                  type: string
                  enum:
                    - outgoing
                    - incoming
                  description: The type of the message
                  example: outgoing
                private:
                  type: boolean
                  description: Flag to identify if it is a private note
                  example: false
                content_type:
                  type: string
                  enum:
                    - text
                    - input_email
                    - cards
                    - input_select
                    - form
                    - article
                  description: Content type of the message
                  example: text
                content_attributes:
                  type: object
                  description: Attributes based on the content type
                  example: {}
                attachments[]:
                  type: array
                  description: Files to attach to the message
                  items:
                    type: string
                    format: binary
            encoding:
              attachments[]:
                style: form
                explode: true
            examples:
              attachment_message:
                summary: Message with an attachment
                value:
                  content: Here is the screenshot
                  message_type: outgoing
                  private: false
                  attachments[]:
                    - screenshot.png
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/generic_id'
                  - $ref: '#/components/schemas/message'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_error'
      security:
        - userBearerAuth: []
        - agentBotBearerAuth: []
        - userApiKey: []
        - agentBotApiKey: []
components:
  parameters:
    account_id:
      in: path
      name: account_id
      schema:
        type: integer
      required: true
      description: The numeric ID of the account
    conversation_id:
      in: path
      name: conversation_id
      schema:
        type: integer
      required: true
      description: The numeric ID of the conversation
  schemas:
    conversation_message_create_payload:
      type: object
      required:
        - content
      properties:
        content:
          type: string
          description: The content of the message
          example: Hello, how can I help you?
        message_type:
          type: string
          enum:
            - outgoing
            - incoming
          description: The type of the message
          example: outgoing
        private:
          type: boolean
          description: Flag to identify if it is a private note
          example: false
        content_type:
          type: string
          enum:
            - text
            - input_email
            - cards
            - input_select
            - form
            - article
          description: Content type of the message
          example: text
        content_attributes:
          type: object
          description: >
            Attributes based on the content type. For `input_select`, provide an
            `items` array with

            `title`, `value`, and optional `description`. WhatsApp list messages
            use `description`

            as the row subtitle when present.
          example:
            items:
              - title: Option 1
                value: option_1
                description: Optional WhatsApp list row subtitle
        campaign_id:
          type: integer
          description: The campaign id to which the message belongs
          example: 1
        template_params:
          type: object
          description: WhatsApp template parameters for sending structured messages
          required:
            - name
            - category
            - language
            - processed_params
          properties:
            name:
              type: string
              description: >-
                Name of the WhatsApp template (must be approved in WhatsApp
                Business Manager)
              example: purchase_receipt
            category:
              type: string
              enum:
                - UTILITY
                - MARKETING
                - SHIPPING_UPDATE
                - TICKET_UPDATE
                - ISSUE_RESOLUTION
              description: Category of the template
              example: UTILITY
            language:
              type: string
              description: Language code of the template (BCP 47 format)
              example: en_US
            content_mode:
              type: string
              enum:
                - raw_template
                - rendered
              default: rendered
              description: >
                Format of the top-level `content` field. Existing clients may
                send rendered

                content or omit this field. Set this to `raw_template` only when
                `content`

                contains the original template body placeholders.
            processed_params:
              type: object
              description: Processed template parameters organized by component type
              properties:
                body:
                  type: object
                  description: Body component parameters with variable placeholders
                  additionalProperties:
                    type: string
                  example:
                    '1': Visa
                    '2': Nike
                    '3': Bill
                header:
                  type: object
                  description: Header component parameters for media templates
                  properties:
                    media_url:
                      type: string
                      format: uri
                      description: >-
                        Publicly accessible URL for IMAGE, VIDEO, or DOCUMENT
                        headers
                      example: >-
                        https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
                    media_type:
                      type: string
                      enum:
                        - image
                        - video
                        - document
                      description: Type of media for the header
                      example: document
                buttons:
                  type: array
                  description: Button component parameters for interactive templates
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - url
                          - copy_code
                        description: Type of button parameter
                      parameter:
                        type: string
                        description: Dynamic parameter value for the button
                        example: SSFSDFSD
    generic_id:
      type: object
      properties:
        id:
          type: number
    message:
      type: object
      properties:
        id:
          type: number
          description: The ID of the message
        content:
          type: string
          description: The text content of the message
        account_id:
          type: number
          description: The ID of the account
        inbox_id:
          type: number
          description: The ID of the inbox
        conversation_id:
          type: number
          description: The ID of the conversation
        message_type:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
          description: The type of the message
        created_at:
          type: integer
          description: The time at which message was created
        updated_at:
          type:
            - integer
            - string
          description: The time at which message was updated
        private:
          type: boolean
          description: The flags which shows whether the message is private or not
        status:
          type:
            - string
            - 'null'
          enum:
            - sent
            - delivered
            - read
            - failed
            - null
          description: The status of the message
        source_id:
          type:
            - string
            - 'null'
          description: The source ID of the message
        content_type:
          type:
            - string
            - 'null'
          enum:
            - text
            - input_text
            - input_textarea
            - input_email
            - input_select
            - cards
            - form
            - article
            - incoming_email
            - input_csat
            - integrations
            - sticker
            - voice_call
            - null
          description: The type of the template message
        content_attributes:
          type: object
          description: The content attributes for each content_type
        sender_type:
          type:
            - string
            - 'null'
          enum:
            - Contact
            - User
            - AgentBot
            - Captain::Assistant
            - null
          description: The type of the sender
        sender_id:
          type:
            - number
            - 'null'
          description: The ID of the sender
        external_source_ids:
          type: object
          description: The external source IDs of the message
        additional_attributes:
          type: object
          description: The additional attributes of the message
        processed_message_content:
          type:
            - string
            - 'null'
          description: The processed message content
        sentiment:
          type:
            - object
            - 'null'
          description: The sentiment of the message
        conversation:
          type:
            - object
            - 'null'
          description: The conversation object
        attachment:
          type:
            - object
            - 'null'
          description: The file object attached to the image
        sender:
          type: object
          description: User/Agent/AgentBot object
    bad_request_error:
      title: data
      type: object
      properties:
        description:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/request_error'
    request_error:
      type: object
      properties:
        field:
          type: string
        message:
          type: string
        code:
          type: string
  securitySchemes:
    userBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate with `Authorization: Bearer <token>` using a user API token
        from **Profile Settings**.
    agentBotBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate with `Authorization: Bearer <token>` using an agent bot
        token from **Settings → Agent Bots**.
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: >-
        Find your API token in **Profile Settings**. The `api_access_token`
        header remains supported, but will be deprecated in a future release.
        For new integrations, use Bearer authentication.
    agentBotApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: >-
        Find your agent bot token in **Settings → Agent Bots**. For new
        integrations, use Bearer authentication. Agent bot tokens can access
        only bot-permitted APIs.

````

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