[ { "method": "POST", "endpoint": "messages", "example_response": "{'msg': '', 'result': 'success', 'id': 12345678}", "returns": [ [ "id", "The ID of the newly created message." ] ], "call": "Send a message", "arguments": [ [ "type", "One of {private, stream}" ], [ "content", "The content of the message. Maximum message size of 10000 bytes." ], [ "to", "In the case of a stream message, a string identifying the stream. In the case of a private message, a JSON-encoded list containing the usernames of the recipients." ], [ "subject", "The topic for the message (Only required if type is \u201cstream\u201d). Maximum length of 60 characters." ] ], "example_request": { "python": "
\nclient.send_message({\n    \"type\": \"private\",\n    \"to\": \"wdaher@example.com\",\n    \"content\": \"I come not, friends, to steal away your hearts.\"\n})\nclient.send_message({\n    \"type\": \"stream\",\n    \"to\": \"Denmark\",\n    \"subject\": \"Castle\",\n    \"content\": \"Something is rotten in the state of Denmark.\"\n})\n
\n", "curl": "
Stream message
\n
curl https://api.zulip.com/v1/messages \\\n    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \\\n    -d \"type=stream\" \\\n    -d \"to=Denmark\" \\\n    -d \"subject=Castle\" \\\n    -d \"content=Something is rotten in the state of Denmark.\"\n
\n
Private message
\n
curl https://api.zulip.com/v1/messages \\\n    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \\\n    -d \"type=private\" \\\n    -d \"to=othello@example.com\" \\\n    -d \"content=I come not, friends, to steal away your hearts.\"\n
" } }, { "method": "POST", "endpoint": "register", "example_response": "{'msg': '', 'last_event_id': -1, 'result': 'success', 'queue_id': '1375801870:2942'}", "returns": [ [ "queue_id", "The ID of the queue that has been allocated for your client" ], [ "last_event_id", "The initial value of the `last_event_id` value for to pass to `GET /api/v1/events`." ] ], "call": "Register a queue to receive new messages", "arguments": [ [ "event_types", "(optional) A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: \n If you do not specify this argument, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: event_types=[\"message\"]" ], [ "apply_markdown", "(optional) set to \u201ctrue\u201d if you would like the content to be rendered in HTML format (by default, the API returns the raw text that the user entered)" ] ], "example_request": { "python": "
client.register()\n
", "curl": "
curl https://api.zulip.com/v1/register \\\n -u othello-bot@example.com:a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \\\n -d 'event_types=[\"message\"]'\n
" } }, { "method": "GET", "endpoint": "events", "example_response": "{'result': 'success', 'msg': '', 'events': [ {'type': 'message', 'id': 0, 'message': { 'content_type': 'text/x-markdown', 'avatar_url': 'https://url/for/othello-bots/avatar', 'timestamp': 1375978403, 'display_recipient': 'Denmark', 'sender_id': 13215, 'sender_full_name': 'Othello Bot', 'sender_email': 'othello-bot@example.com', 'sender_short_name': 'othello-bot', 'sender_domain': 'example.com', 'content': 'Something is rotten in the state of Denmark.', 'gravatar_hash': '17d93357cca1e793739836ecbc7a9bf7', 'recipient_id': 12314, 'client': 'website', 'subject_links': [], 'subject': 'Castle', 'type': 'stream', 'id': 12345678, } }, {'type': 'message', 'id': 1, 'message': { 'content_type': 'text/x-markdown', 'avatar_url': 'https://url/for/othello-bots/avatar', 'timestamp': 1375978404, 'display_recipient': [{'full_name': 'Hamlet of Denmark', 'domain': 'example.com', 'email': 'hamlet@example.com', 'short_name': 'hamlet', 'id': 31572}], 'sender_id': 13215, 'sender_full_name': 'Othello Bot', 'sender_email': 'othello-bot@example.com', 'sender_short_name': 'othello-bot', 'sender_domain': 'example.com', 'content': 'I come not, friends, to steal away your hearts.', 'gravatar_hash': '17d93357cca1e793739836ecbc7a9bf7', 'recipient_id': 18391, 'client': 'website', 'subject_links': [], 'subject': '', 'type': 'private', 'id': 12345679, } } ] }", "returns": [ [ "events", "an array (possibly zero-length if dont_block is set) of events with IDs newer than `last_event_id`. Event IDs are guaranted to be increasing, but they are not guaranteed to be consecutive." ] ], "call": "Get new events from an events queue", "arguments": [ [ "queue_id", "The ID of a queue that you registered via POST /api/v1/register" ], [ "last_event_id", "The highest event ID in this queue that you've received and wish to acknowledge. See the code for call_on_each_event in the zulip Python module for an example implementation of correctly processing each event exactly once." ], [ "dont_block", "(optional) set to \u201ctrue\u201d if the client is requesting a nonblocking reply. If not specified, the request will block until either a new event is available or a few minutes have passed, in which case the server will send the client a heartbeat event." ] ], "example_request": { "python": "
client.get_events()\n
or if you want the event queues managed for you, 
client.call_on_each_event()\n
", "curl": "
curl -G https://api.zulip.com/v1/events \\\n -u othello-bot@example.com:a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \\\n -d \"queue_id=1375801870:2942\" \\\n -d \"last_event_id=-1\"\n
" } } ]