Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Send a message

Send a stream or a private message.

POST https://yourZulipDomain.zulip.iemn.fr/api/v1/messages

Usage examples

  • Python
  • JavaScript
  • curl
  • zulip-send

#!/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",
    "subject": "Castle",
    "content": "I come not, friends, to steal away your hearts."
}
result = client.send_message(request)
print(result)

# Send a private message
request = {
    "type": "private",
    "to": "iago@zulip.com",
    "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 params = {
        to: 'hamlet@example.com',
        type: 'private',
        content: 'With mirth and laughter let old wrinkles come.',
    }

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


# For stream messages
curl https://yourZulipDomain.zulip.iemn.fr/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 https://yourZulipDomain.zulip.iemn.fr/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "type=private" \
    -d "to=hamlet@example.com" \
    -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

Argument Example Required Description
type "private" Yes

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 "aaron@zulip.com, iago@zulip.com" Yes

The destination stream, or a CSV/JSON-encoded list containing the usernames (emails) of the recipients.
subject "Castle" No

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

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"
}