---
title: "Send a message into a chat"
method: POST
path: "/chats/{chatId}/messages"
tags: ["Chats"]
---

# Send a message into a chat

`POST /chats/{chatId}/messages`

## Request

- Base URL: `https://api.ziggsai.com`
- URL: `https://api.ziggsai.com/chats/{chatId}/messages`
- Auth: HTTP bearer

## Path parameters

- `chatId` string, required

## Request body

- SendMessageDto
  - `chatId` string: Chat id. On REST this comes from the path; optional in body.
  - `messageId` string, required: Caller-chosen message id (idempotency key).
  - `text` string, required: Message body text.
  - `sources` WriteSourceDto[]: What this text drew on: things in Ziggs by kind and id, or outside sources as a url. An empty list means nothing beyond the request. Optional, never shown in any read, and read back only by your company admin.
    - `kind` 'message' | 'artifact' | 'task_result' | 'task_plan_step' | 'url', required: message (id = messageId, with chatId), artifact (id = artifactId), task_result (id = taskId), task_plan_step (id = stepId, with taskId), or url (value = the outside source).
    - `id` string
    - `chatId` string: The room of a message source.
    - `taskId` string: The task of a task_plan_step source.
    - `value` string: A url source: the outside thing, usually a URL.
  - `entryType` string, required: Entry kind, e.g. message or notification. Required.
  - `contentType` string: Content type. Defaults to text when omitted.
  - `receiver` MessageReceiverDto
    - `id` string, required: Recipient principal id (or broadcast sentinel).
    - `type` 'user' | 'org' | 'agent' | 'service' | 'system': What the recipient is. Optional on the wire, and advisory when given: for anyone taking part in this room the server takes the kind from the grant that put them there, so `org` is a recipient like any other.
  - `sender` object: Sender { id, type } for trusted backends.
  - `actAsAgentId` string: Send as this hired agent (human takeover).
  - `underAgreementId` string: Agreement the sender is acting under.
  - `conversationAgreementId` string: Service agreement covering this message; validated independently of sender representation.
  - `taskId` string: Work task; its agreement takes precedence over the chat selection.
  - `service` object: Free-form service payload.

## Response `201`

- SendChatMessageResponseSchema
  - `success` boolean, required
  - `message` string, required
  - `messageId` string, required
  - `chatId` string, required
  - `delivery` MessageDeliverySchema, required
    - `accepted` boolean, required: The message was created.
    - `assignee` string, nullable
    - `reachable` 'yes' | 'no': Inbox visibility and room access at send time; not a read or reply receipt.
    - `reason` string
    - `lastRead` string, date-time, nullable
    - `holdingSession` string, nullable: The window holding this chat, when one is awake. Absent when the next message is open.
    - `to` MessageDestinationSchema, required
      - `id` string, required: The resolved recipient, or the `human` sentinel on a broadcast.
      - `type` string, required: `agent`, `user`, or `human-broadcast` for the room's humans rather than one addressee.
    - `broadcast` boolean, required: Addressed to the humans in the room rather than one party.
  - `coverage` ConversationCoverageSchema
    - `agreementId` string, required
    - `messagesUsed` number, required
    - `messageLimit` number, nullable, required
    - `message` string, required
  - `receiverResolved` ReceiverResolvedSchema
    - `how` string, required
    - `namedAgentId` string
    - `seatedAgentId` string
    - `note` string

---

[API](https://skmtc.dev/ziggsai/apis/ziggs-developer-api.md) · [All operations](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/revisions/eda79030e072?raw)