---
title: "Create Message"
method: POST
path: "/messages"
tags: ["Messages"]
---

# Create Message

`POST /messages`

## Request

- Base URL: `https://developers.chatway.app/api/v1`
- URL: `https://developers.chatway.app/api/v1/messages`
- Auth: API key in header `X-API-KEY`

Create a message in an existing conversation with POST /messages. Use a conversation ID from List Conversations or `data.conversation.id` in an incoming message webhook. For a visitor-authored message without a conversation ID, use Create Visitor Message instead.

For a basic text message, supply conversation_id and content. Replace the example conversation ID with the conversation you intend to reply to. Add agent_id to send the message as a team member; without it, the message is saved as written by the conversation's contact. Use optional fields only when your workflow needs them; you do not need an attachment for a text-only message.

Returns `201 Created` with the created message.

## Request body

- object
  - `conversation_id` string, required: Conversation ID
  - `content` string, nullable
  - `widget_id` string, nullable: Widget identifier (optional)
  - `type` string, nullable: Optional. `message` (default) or `note`. A note is an internal note for your team: it is not shown in the visitor's chat widget and is not sent to connected social channels. agent_id works the same way for both types. With agent_id, the note is written by that team member, is delivered in real time to agents only, and does not trigger the message.sent webhook. Without agent_id, the note is saved as written by the conversation's contact and triggers the message.received webhook like a visitor message, so send agent_id with every note.
  - `agent_id` string, nullable: Optional. ID of the team member (from List Agents) to send the message as. If omitted, the message is saved as written by the conversation's contact, not by an agent.
  - `attachments` object[], nullable: Each attachment is an object containing its URL and, optionally, a name. Use the URL of the intended file and a descriptive filename. Do not copy an API endpoint URL into attachments merely because it appears elsewhere in these docs.
    - `url` string, uri
    - `name` string, nullable

## Response `201`

Message created

- object
  - `data` object, required
    - `type` string, required
    - `id` string, required
    - `attributes` object, required
      - `conversation_id` string, required
      - `chat_contact_id` string, nullable, required
      - `agent` object, nullable, required
        - `id` string, nullable, required
        - `name` string, nullable, required
      - `contact` object, nullable, required
        - `id` string, nullable, required
        - `name` string, nullable, required
        - `email` string, nullable, required
        - `phone` string, nullable, required
      - `origin` string, required
      - `content` string, required
      - `type` string, required
      - `created_at` string, nullable, required

## Other responses

- `404`: Conversation not found
- `422`: Validation error
- `500`: An error

---

[API](https://skmtc.dev/chatway/apis/chatway-developer-docs.md) · [All operations](https://skmtc.dev/chatway/apis/chatway-developer-docs/llms.txt) · [OpenAPI document](https://skmtc.dev/chatway/apis/chatway-developer-docs/revisions/ca1a1da291cc?raw)