zulip/templates/zerver/api/private-message.md

Private message

Send a private message to a user or multiple users.

POST {{ api_url }}/v1/messages

Usage examples

• Python
• JavaScript
• curl
• zulip-send

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.

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](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);

});

</div>

</div>

</div>

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