---
title: "Send a message"
method: POST
path: "/v1/{appId}/conversations/{conversationId}/messages"
tags: ["Messages"]
---

# Send a message

`POST /v1/{appId}/conversations/{conversationId}/messages`

## Request

- Base URL: `https://api.talkjs.com`
- URL: `https://api.talkjs.com/v1/{appId}/conversations/{conversationId}/messages`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
- TypeScript: <https://skmtc.dev/talkjs/apis/talkjs-api/docs/v1/:appId/conversations/:conversationId/messages/post.ts> (a function with typed inputs; its response is checked against the schema)

Sends one or more messages to a specific conversation.

### Message types

You can send two types of messages to a conversation: 
  - a user [message](https://talkjs.com/docs/Reference/Concepts/Messages/) sent on behalf of a user;
  - a [system message](https://talkjs.com/docs/Reference/Concepts/System_Messages/) sent on behalf of the application.

You can send a batch of consecutive messages in a single request, and combine user messages and system messages in one request.

### Deliver a message exactly once

If an initial request to send a message fails, you can retry your request. To avoid message duplication on retries, use the `idempotencyKey` field when sending the messages. You can retry sending a message with the same `idempotencyKey` any number of times, and it gets sent exactly once.

Make sure that your `idempotencyKey` is unique for a message within a conversation. 

An `idempotencyKey` is associated with a specific message in a conversation for 24 hours. After 24 hours, you can associate the key with another message.

### Attach a file to a message

To send a message with a file attachment, such as an image, video, or a document, take the following two steps: 

1. Upload the file you would like to attach to the TalkJS servers, using the 'Upload a file' resource. You'll receive an `attachmentToken` in response to the request.
2. Send a message that includes the `attachmentToken` you received when uploading the file.

## Path parameters

- `appId` string, required
- `conversationId` string, required

## Request body

- union
  - object[]: An array of one or more user [messages](https://talkjs.com/docs/Reference/Concepts/Messages/). To send a message on behalf of a user, make sure that the user has been created, and is a participant in the conversation that you send the message to. You can send a batch of consecutive user messages in a single request, attach a file to the message, or share a user's location. If notifications are enabled, then sending a user message triggers a notification.
    - `text` string: The body text of the message.
    - `sender` string, required: Unique identifier of the sender of the message. A sender of a user message must be a participant in the conversation that the message is sent to.
    - `type` 'UserMessage': The type of message. User messages are sent on behalf of a user, and must be of the type `"UserMessage"`.
    - `referencedMessageId` string: Use if this message is a reply to another message. An optional unique identifier of the message that this message is replying to.
    - `custom` object, nullable: A custom property of a user message. Both keys and values must be strings.
    - `idempotencyKey` string: Optional key to ensure that a message gets delivered exactly once, also if you need to retry your request. A message with the same `idempotencyKey` can be retried any number of times, and is sent exactly once. Make sure that your `idempotencyKey` is unique for a message within a conversation. An `idempotencyKey` is associated with a specific message in a conversation for 24 hours. After 24 hours, you can associate the key with another message.
  - object[]: An array of one or more [system messages](https://talkjs.com/docs/Reference/Concepts/System_Messages/) sent on behalf of the application. System messages can be useful for anything from order confirmations to notifications when a user joins a channel. A system message is displayed neutrally in the chat UI. System messages have no sender, and aren't associated with any participant in the conversation.. You can [format](https://talkjs.com/docs/Features/Customizations/Formatting/) your system messages, and send a batch of consecutive system messages in a single request. System messages support file attachments, but can't reply to other messages or share a location. A system message doesn't trigger notifications.
    - `text` string: The body text of the message.
    - `type` 'SystemMessage', required: The type of message. System messages, which are sent on behalf of the application, must be of the type `"SystemMessage"`.
    - `custom` object, nullable: A custom property of a system message. Both keys and values must be strings.
    - `idempotencyKey` string: Optional key to ensure that a message gets delivered exactly once, also if you need to retry your request. A message with the same `idempotencyKey` can be retried any number of times, and is sent exactly once. Make sure that your `idempotencyKey` is unique for a message within a conversation. An `idempotencyKey` is associated with a specific message in a conversation for 24 hours. After 24 hours, you can associate the key with another message.

## Response `200`

Message or messages sent successfully.

- object[]: An array of message IDs.
  - `id` string: An automatically generated unique identifier of this message.

## Other responses

- `400`: Bad request
- `401`: Authorization information is missing or invalid.
- `404`: Resource not found
- `415`: Unsupported media type
- `429`: Too many requests
- `500`: Internal server error

---

[API](https://skmtc.dev/talkjs/apis/talkjs-api.md) - [All operations](https://skmtc.dev/talkjs/apis/talkjs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talkjs/apis/talkjs-api/revisions/9d4acc9cfa43?raw)