Send a message

POST https://zulip.cs.ut.ee/api/v1/messages

Send a stream message or a direct message.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Send a stream message
request = {
    "type": "stream",
    "to": "Denmark",
    "topic": "Castle",
    "content": "I come not, friends, to steal away your hearts.",
}
result = client.send_message(request)

# Send a direct message
user_id = 10
request = {
    "type": "private",
    "to": [user_id],
    "content": "With mirth and laughter let old wrinkles come.",
}
result = client.send_message(request)

print(result)

More examples and documentation can be found here.

const zulipInit = require("zulip-js");

// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };

(async () => {
    const client = await zulipInit(config);

    // Send a stream message
    let params = {
        to: "social",
        type: "stream",
        topic: "Castle",
        content: "I come not, friends, to steal away your hearts.",
    };
    console.log(await client.messages.send(params));

    // Send a direct message
    const user_id = 9;
    params = {
        to: [user_id],
        type: "direct",
        content: "With mirth and laughter let old wrinkles come.",
    };
    console.log(await client.messages.send(params));
})();

# For stream messages
curl -X POST https://zulip.cs.ut.ee/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode type=stream \
    --data-urlencode 'to="Denmark"' \
    --data-urlencode topic=Castle \
    --data-urlencode 'content=I come not, friends, to steal away your hearts.'

# For direct messages
curl -X POST https://zulip.cs.ut.ee/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode type=direct \
    --data-urlencode 'to=[9]' \
    --data-urlencode 'content=With mirth and laughter let old wrinkles come.'

You can use zulip-send (available after you pip install zulip) to easily send Zulips from the command-line, providing the message content via STDIN.

# For stream messages
zulip-send --stream Denmark --subject Castle \
    --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5

# For direct messages
zulip-send hamlet@example.com \
    --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5

Passing in the message on the command-line

If you'd like, you can also provide the message on the command-line with the -m or --message flag, as follows:

zulip-send --stream Denmark --subject Castle \
    --message 'I come not, friends, to steal away your hearts.' \
    --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5

You can omit the user and api-key parameters if you have a ~/.zuliprc file.

Parameters

type string required

Example: "direct"

The type of message to be sent.

"direct" for a direct message and "stream" for a stream message.

Changes: In Zulip 7.0 (feature level 174), "direct" was added as the preferred way to request a direct message, deprecating the original "private". While "private" is still supported for requesting direct messages, clients are encouraged to use to the modern convention with servers that support it, because support for "private" will eventually be removed.

Must be one of: "direct", "stream", "private".


to string | integer | (string)[] | (integer)[] required

Example: [9, 10]

For stream messages, either the name or integer ID of the stream. For direct messages, either a list containing integer user IDs or a list containing string Zulip API email addresses.

Changes: Support for using user/stream IDs was added in Zulip 2.0.0.


content string required

Example: "Hello"

The content of the message.

Clients should use the max_message_length returned by the POST /register endpoint to determine the maximum message size.


topic string optional

Example: "Castle"

The topic of the message. Only required for stream messages ("type": "stream"), ignored otherwise.

Clients should use the max_topic_length returned by the POST /register endpoint to determine the maximum topic length.

Changes: New in Zulip 2.0.0. Previous Zulip releases encoded this as subject, which is currently a deprecated alias.


queue_id string optional

Example: "fb67bf8a-c031-47cc-84cf-ed80accacda8"

For clients supporting local echo, the event queue ID for the client. If passed, local_id is required. If the message is successfully sent, the server will include local_id in the message event that the client with this queue_id will receive notifying it of the new message via GET /events. This lets the client know unambiguously that it should replace the locally echoed message, rather than adding this new message (which would be correct if the user had sent the new message from another device).


local_id string optional

Example: "100.01"

For clients supporting local echo, a unique string-format identifier chosen freely by the client; the server will pass it back to the client without inspecting it, as described in the queue_id description.


Response

Return values

  • id: integer

    The unique ID assigned to the sent message.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "id": 42,
    "msg": "",
    "result": "success"
}

A typical failed JSON response for when a stream message is sent to a stream that does not exist:

{
    "code": "STREAM_DOES_NOT_EXIST",
    "msg": "Stream 'nonexistent_stream' does not exist",
    "result": "error",
    "stream": "nonexistent_stream"
}

A typical failed JSON response for when a direct message is sent to a user that does not exist:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid email 'eeshan@zulip.com'",
    "result": "error"
}