Send a message
Send a stream or a private message.
POST https://chat.outreachy.org/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",
"topic": "Castle",
"content": "I come not, friends, to steal away your hearts.",
}
result = client.send_message(request)
# Send a private 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 private message
const user_id = 9;
params = {
to: [user_id],
type: "private",
content: "With mirth and laughter let old wrinkles come.",
};
console.log(await client.messages.send(params));
})();
# For stream messages
curl -X POST https://chat.outreachy.org/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 private messages
curl -X POST https://chat.outreachy.org/api/v1/messages \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode type=private \
--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 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 parameters if you have a ~/.zuliprc
file.
Parameters
type string 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 (integer)[] 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 for using user/stream IDs was added in Zulip 2.0.0.
content string required
Example: "Hello"
The content of the message. Maximum message size of 10000 bytes.
topic string optional
Example: "Castle"
The topic of the message. Only required for stream messages
(type="stream"), ignored otherwise.
Maximum length of 60 characters.
Changes: New in Zulip 2.0. Previous Zulip releases encoded
this as subject, which is currently a deprecated alias.
queue_id string optional
Example: "1593114627:0"
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.
-
deliver_at: string
Present for scheduled messages, encodes the time when the message will
be sent. Note that scheduled messages ("Send later") is a beta API and
may change before it's a finished feature.
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"
}