Register E2EE push device
POST https://your-org.zulipchat.com/api/v1/mobile_push/register
Register a device to receive end-to-end encrypted mobile push notifications.
Changes: New in Zulip 11.0 (feature level 406).
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
# Register a push device.
request = {
"token_kind": "fcm",
"push_account_id": 2408,
"push_key": "MTaUDJDMWypQ1WufZ1NRTHSSvgYtXh1qVNSjN3aBiEFt",
"bouncer_public_key": "bouncer-public-key",
"encrypted_push_registration": "encrypted-push-registration-data",
}
result = client.call_endpoint(url="/mobile_push/register", method="POST", request=request)
print(result)
curl -sSX POST https://your-org.zulipchat.com/api/v1/mobile_push/register \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode token_kind=fcm \
--data-urlencode push_account_id=2408 \
--data-urlencode push_key=MTaUDJDMWypQ1WufZ1NRTHSSvgYtXh1qVNSjN3aBiEFt \
--data-urlencode bouncer_public_key=bouncer-public-key \
--data-urlencode encrypted_push_registration=encrypted-push-registration-data
Parameters
token_kind string required
Example: "fcm"
Whether the token was generated by FCM or APNs.
Must be one of: "fcm", "apns".
push_account_id integer required
Example: 2408
A random integer generated by the client that will be included
in mobile push notifications along with encrypted payloads to
identify pushes as being related to this registration.
Must be unique in the client's table of accounts.
push_key string required
Example: "MTaUDJDMWypQ1WufZ1NRTHSSvgYtXh1qVNSjN3aBiEFt"
Key that the client would like the server to use to encrypt notifications,
encoded with Base64.
The key is a byte sequence beginning with a single byte that encodes which
cryptosystem to use, followed by the key to use for that cryptosystem.
This byte sequence is encoded using standard Base64 encoding as defined in RFC 4648.
The client should avoid sharing the key anywhere else: in particular it should
generate a fresh key for each server, and to the extent possible keep the key
out of any backups of the client's data.
Supported cryptosystems are:
0x31: LibSodium's SecretBox symmetric key encryption
system. Keys are 32 bytes, which the server will use with libsodium's
crypto_secretbox_easy. See the NaCl documentation, which
details how this system uses XSalsa20 and Poly1305 to provide authenticated
encryption.
Changes: New in Zulip 12.0 (feature level 432). This replaced the
push_public_key parameter which had a prototype asymmetric cryptosystem, and
did not have a natural way to support multiple cryptosystems.
bouncer_public_key string required
Example: "bouncer-public-key"
Which of the bouncer's public keys the client used to encrypt the
PushRegistration dictionary.
When the bouncer rotates the key, a new asymmetric key pair is created,
and the new public key is baked into a new client release. Because
the bouncer routinely rotates key, this field clarifies which
public key the client is using.
encrypted_push_registration string required
Example: "encrypted-push-registration-data"
Ciphertext generated by encrypting a PushRegistration dictionary
using the bouncer_public_key, encoded using a RFC 4648 standard
base64 encoder.
The PushRegistration dictionary contains the fields token,
token_kind, timestamp, and (for iOS devices) ios_app_id.
The dictionary is JSON-encoded before encryption.
Response
Example response(s)
Changes: As of Zulip 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
ignored_parameters_unsupported array.
A typical successful JSON response may look like:
{
"msg": "",
"result": "success"
}
Error when the server is not configured to use push notification service:
{
"code": "PUSH_SERVICE_NOT_CONFIGURED",
"msg": "Server is not configured to use push notification service.",
"result": "error"
}