diff --git a/templates/zerver/api/arguments.json b/templates/zerver/api/arguments.json index 74378fd102..7fce264bdb 100644 --- a/templates/zerver/api/arguments.json +++ b/templates/zerver/api/arguments.json @@ -1,28 +1,8 @@ { - "private-message.md": [ + "send-message.md": [ { "argument": "type", - "description": "The type of message to be sent. `private` for a private message and `stream` for a [stream message](/api/stream-message).", - "required": true, - "example": "private" - }, - { - "argument": "to", - "description": "A JSON-encoded list containing the usernames of the recipients.", - "required": true, - "example": "wdaher@example.com" - }, - { - "argument": "content", - "description": "The content of the message. Maximum message size of 10000 bytes.", - "required": true, - "example": "Hello" - } - ], - "stream-message.md": [ - { - "argument": "type", - "description": "The type of message to be sent. `stream` for a stream message and `private` for a [private message](/api/private-message).", + "description": "The type of message to be sent. `stream` for a stream message and `private` for a private message.", "required": true, "example": "stream" }, diff --git a/templates/zerver/api/fixtures.json b/templates/zerver/api/fixtures.json index d1e1548dc1..69b3d5a6b0 100644 --- a/templates/zerver/api/fixtures.json +++ b/templates/zerver/api/fixtures.json @@ -271,11 +271,6 @@ "result": "error", "stream": "nonexistent_stream" }, - "private-message": { - "id": 134, - "msg": "", - "result": "success" - }, "register-queue": { "last_event_id": -1, "msg": "", @@ -308,7 +303,7 @@ "rendered": "

foo

", "result": "success" }, - "stream-message": { + "send-message": { "id": 134, "msg": "", "result": "success" diff --git a/templates/zerver/api/index.md b/templates/zerver/api/index.md index 8ca18d411d..c7a04404a0 100644 --- a/templates/zerver/api/index.md +++ b/templates/zerver/api/index.md @@ -4,14 +4,14 @@ Zulip's APIs allow you to integrate other services with Zulip. This guide should help you find the API you need: * First, check if the tool you'd like to integrate with Zulip -[already has a native integration](/integrations). + [already has a native integration](/integrations). * Next, check if [Zapier](https://zapier.com/apps) or [IFTTT](https://ifttt.com/search) has an integration; Zulip's native integrations with Zapier and IFTTT often allow integrating a new service with Zulip without writing any code. * If you'd like to send content into Zulip, you can [write a native incoming webhook integration](/api/incoming-webhooks-overview) - or use [Zulip's API for sending messages](/api/stream-message). + or use [Zulip's API for sending messages](/api/send-message). * If you're building an interactive bot that reacts to activity inside Zulip, you'll want to look at Zulip's [Python framework for interactive bots](/api/running-bots) or diff --git a/templates/zerver/api/private-message.md b/templates/zerver/api/private-message.md deleted file mode 100644 index 60a46e86fd..0000000000 --- a/templates/zerver/api/private-message.md +++ /dev/null @@ -1,95 +0,0 @@ -# Private message - -Send a private message to a user or multiple users. - -`POST {{ api_url }}/v1/messages` - -## Usage examples -
- -
- -
- -``` -curl {{ api_url }}/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." -``` -
- -
- -{generate_code_example(python)|private-message|example} - -
- -
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. - -```bash -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](/api). -
- -
-More examples and documentation can be found [here](https://github.com/zulip/zulip-js). -```js -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 - -{generate_api_arguments_table|arguments.json|private-message.md} - -## Response - -#### Return values - -* `id`: The ID of the newly created message - -#### Example response - -A typical successful JSON response may look like: - -{generate_code_example|private-message|fixture} - -A typical failed JSON response for when the recipient's email -address is invalid: - -{generate_code_example|invalid-pm-recipient-error|fixture} diff --git a/templates/zerver/api/stream-message.md b/templates/zerver/api/send-message.md similarity index 61% rename from templates/zerver/api/stream-message.md rename to templates/zerver/api/send-message.md index d1a6c2a0fd..23f06a5f60 100644 --- a/templates/zerver/api/stream-message.md +++ b/templates/zerver/api/send-message.md @@ -1,10 +1,11 @@ -# Stream message +# Send a message -Send a message to a stream. +Send a stream or a private message. `POST {{ api_url }}/v1/messages` ## Usage examples +
@@ -68,6 +83,7 @@ const config = { zuliprc: 'zuliprc-dev', }; +// Send a stream message zulip(config).then((client) => { // Send a message const params = { @@ -80,6 +96,18 @@ zulip(config).then((client) => { 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: 'I come not, friends, to steal away your hearts.', + } + + client.messages.send(params).then(console.log); +}); + ```
@@ -89,7 +117,7 @@ zulip(config).then((client) => { ## Arguments -{generate_api_arguments_table|arguments.json|stream-message.md} +{generate_api_arguments_table|arguments.json|send-message.md} ## Response @@ -100,8 +128,14 @@ zulip(config).then((client) => { #### Example response A typical successful JSON response may look like: -{generate_code_example|stream-message|fixture} +{generate_code_example|send-message|fixture} -A typical failed JSON response for when the target stream does not exist: +A typical failed JSON response for when a stream message is sent to a stream +that does not exist: {generate_code_example|nonexistent-stream-error|fixture} + +A typical failed JSON response for when a private message is sent to a user +that does not exist: + +{generate_code_example|invalid-pm-recipient-error|fixture} diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md index 07c7e54b4b..2566c075c4 100644 --- a/templates/zerver/help/include/rest-endpoints.md +++ b/templates/zerver/help/include/rest-endpoints.md @@ -1,7 +1,6 @@ #### Messages -* [Stream message](/api/stream-message) -* [Private message](/api/private-message) +* [Send a message](/api/send-message) * [Render message](/api/render-message) * [Update a message](/api/update-message) diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py index f662fe6500..c2b324fe9b 100644 --- a/zerver/lib/api_test_helpers.py +++ b/zerver/lib/api_test_helpers.py @@ -293,7 +293,7 @@ def render_message(client): fixture = FIXTURES['render-message'] test_against_fixture(result, fixture) -def stream_message(client): +def send_message(client): # type: (Client) -> int # {code_example|start} @@ -307,11 +307,34 @@ def stream_message(client): result = client.send_message(request) # {code_example|end} - fixture = FIXTURES['stream-message'] + fixture = FIXTURES['send-message'] test_against_fixture(result, fixture, check_if_equal=['result'], check_if_exists=['id']) - # test it was actually sent + # test that the message was actually sent + message_id = result['id'] + url = 'messages/' + str(message_id) + result = client.call_endpoint( + url=url, + method='GET' + ) + assert result['result'] == 'success' + assert result['raw_content'] == request['content'] + + # {code_example|start} + # 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) + # {code_example|end} + + test_against_fixture(result, fixture, check_if_equal=['result'], + check_if_exists=['id']) + + # test that the message was actually sent message_id = result['id'] url = 'messages/' + str(message_id) result = client.call_endpoint( @@ -336,33 +359,6 @@ def test_nonexistent_stream_error(client): fixture = FIXTURES['nonexistent-stream-error'] test_against_fixture(result, fixture) -def private_message(client): - # type: (Client) -> None - - # {code_example|start} - # 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) - # {code_example|end} - - fixture = FIXTURES['private-message'] - test_against_fixture(result, fixture, check_if_equal=['result'], - check_if_exists=['id']) - - # test it was actually sent - message_id = result['id'] - url = 'messages/' + str(message_id) - result = client.call_endpoint( - url=url, - method='GET' - ) - assert result['result'] == 'success' - assert result['raw_content'] == request['content'] - def test_private_message_invalid_recipient(client): # type: (Client) -> None request = { @@ -507,8 +503,7 @@ def test_invalid_stream_error(client): TEST_FUNCTIONS = { 'render-message': render_message, - 'stream-message': stream_message, - 'private-message': private_message, + 'send-message': send_message, '/messages/{message_id}:patch': update_message, 'get-stream-id': get_stream_id, 'get-subscribed-streams': list_subscriptions, @@ -575,9 +570,8 @@ def test_messages(client, nonadmin_client): # type: (Client, Client) -> None render_message(client) - message_id = stream_message(client) + message_id = send_message(client) update_message(client, message_id) - private_message(client) test_nonexistent_stream_error(client) test_private_message_invalid_recipient(client) diff --git a/zerver/tests/test_docs.py b/zerver/tests/test_docs.py index d5160055e5..9587bfc313 100644 --- a/zerver/tests/test_docs.py +++ b/zerver/tests/test_docs.py @@ -78,8 +78,7 @@ class DocPageTest(ZulipTestCase): self._test('/api/', 'The Zulip API') self._test('/api/api-keys', 'you can use its email and API key') self._test('/api/installation-instructions', 'No download required!') - self._test('/api/private-message', 'steal away your hearts') - self._test('/api/stream-message', 'rotten in the state of Denmark') + self._test('/api/send-message', 'steal away your hearts') self._test('/api/render-message', '**foo**') self._test('/api/get-all-streams', 'include_public') self._test('/api/get-stream-id', 'The name of the stream to retrieve the ID for.')