Send a message

Send a stream or a private message.

POST https://oilshell.zulipchat.com/api/v1/messages

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)
print(result)

# Send a private message
user_id = 9
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 zulip = require('zulip-js');

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

// Send a stream message
zulip(config).then((client) => {
    // Send a message
    const params = {
        to: 'Denmark',
        type: 'stream',
        subject: 'Castle',
        content: 'I come not, friends, to steal away your hearts.'
    }

    client.messages.send(params).then(console.log);
});

// Send a private message
zulip(config).then((client) => {
    // Send a private message
    const user_id = 9;
    const params = {
        to: [user_id],
        type: 'private',
        content: 'With mirth and laughter let old wrinkles come.',
    }

    client.messages.send(params).then(console.log);
});

# For stream messages
curl -X POST https://oilshell.zulipchat.com/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "type=stream" \
    -d "to=Denmark" \
    -d "subject=Castle" \
    -d $"content=I come not, friends, to steal away your hearts."

# For private messages
curl -X POST https://oilshell.zulipchat.com/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "type=private" \
    -d "to=[9]" \
    -d $"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 private 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 arguments if you have a ~/.zuliprc file.

Arguments

type required

Example: "private"

The type of message to be sent. private for a private message and stream for a stream message. Must be one of: private, stream.


to required

Example: [9, 10]

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

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


topic optional

Example: "Castle"

The topic of the message. Only required if type is stream, ignored otherwise. Maximum length of 60 characters.


content required

Example: "Hello"

The content of the message. Maximum message size of 10000 bytes.


Response

Return values

  • id: The ID of the newly created message

Example response

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 private message is sent to a user that does not exist:

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