Register E2EE push device
POST https://rustaceans-ai.zulipchat.com/api/v1/mobile_push/register
Register a device to receive end-to-end encrypted mobile push notifications,
or update such a registration.
To perform an initial registration, clients must provide both the
push key fields (push_key and push_key_id) and the token fields
(token_kind, token_id, bouncer_public_key, and encrypted_push_registration).
Once registered, clients should use this endpoint to rotate push_key or
FCM/APNs provided token:
- Rotate push key: Provide only the push key fields.
- Rotate token: Provide only the token fields.
Changes: In Zulip 12.0 (feature level 468), the endpoint
was significantly redesigned to support rotation of push_key and
token provided by FCM/APNs.
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 device for push notifications.
request = {
"device_id": device_id,
"token_kind": "fcm",
"push_key": "MTaUDJDMWypQ1WufZ1NRTHSSvgYtXh1qVNSjN3aBiEFt",
"push_key_id": 2408,
"bouncer_public_key": "bouncer-public-key",
"encrypted_push_registration": "encrypted-push-registration-data",
"token_id": "hGsEWGmyyfI=",
}
result = client.call_endpoint(url="/mobile_push/register", method="POST", request=request)
print(result)
curl -sSX POST https://rustaceans-ai.zulipchat.com/api/v1/mobile_push/register \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode device_id=1 \
--data-urlencode push_key_id=2408 \
--data-urlencode push_key=MTaUDJDMWypQ1WufZ1NRTHSSvgYtXh1qVNSjN3aBiEFt \
--data-urlencode token_kind=fcm \
--data-urlencode token_id=hGsEWGmyyfI= \
--data-urlencode bouncer_public_key=bouncer-public-key \
--data-urlencode encrypted_push_registration=encrypted-push-registration-data
Parameters
device_id integer required
Example: 1
push_key_id integer optional
Example: 2408
A random unsigned 32-bit integer generated by the client as an identifier
for push_key. It will be included in mobile push notifications
along with encrypted payloads to identify the push_key to decrypt.
push_key string optional
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.
token_kind string optional
Example: "fcm"
Whether the token was generated by FCM or APNs.
Must be one of: "fcm", "apns".
token_id string optional
Example: "hGsEWGmyyfI="
Identifier for the FCM/APNs provided token to the device,
produced by taking the first 8 bytes of the SHA-256 hash of
the token, then encoding those bytes using standard Base64 encoding
as defined in RFC 4648.
bouncer_public_key string optional
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.
The public key is encoded using standard Base64 encoding as defined
in RFC 4648.
encrypted_push_registration string optional
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"
}