Private message

Send a private message to a user or multiple users.

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

Usage examples

curl https://yourZulipDomain.zulipchat.com/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "type=private" \
    -d "to=hamlet@example.com" \
    -d "content=I come not, friends, to steal away your hearts."
#!/usr/bin/env python3

import zulip

# Download ~/zuliprc-dev from your dev server
client = zulip.Client(config_file="~/zuliprc-dev")

# Send a private message
request = {
    "type": "private",
    "to": "iago@zulip.com",
    "content": "I come not, friends, to steal away your hearts."
}
result = client.send_message(request)
print(result)

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.

zulip-send hamlet@example.com \
    --user othello-bot@example.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5

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

See also the full API endpoint documentation.

More examples and documentation can be found here.

const zulip = require('zulip-js');

// Download zuliprc-dev from your dev server
const config = {
    zuliprc: 'zuliprc-dev',
};

zulip(config).then((client) => {
    // Send a private message
    const params = {
        to: 'hamlet@example.com',
        type: 'private',
        content: 'I come not, friends, to steal away your hearts.',
    }

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

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.

to wdaher@example.com Yes

A JSON-encoded list containing the usernames of the recipients.

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": 134,
    "msg": "",
    "result": "success"
}

A typical failed JSON response for when the recipient's email address is invalid:

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