Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

Conversations Push Proxy

An XEP-0357: Push Notifications app server that relays push messages between the user’s server and push services like Google Firebase Cloud Messaging (FCM) or Apple Push Notification Service (APNS).

Note: p2 is open source and closed contribution. It’s purpose is to document the privacy implications of using push services. Enthusiast users who are building Conversations from source are recommended to build Conversations without push capabilities. The app will work fine without push (The State of Mobile XMPP in 2016).

Commercial support for running p2 is available from the developer Daniel Gultsch.


Due to restrictions in Firebase Cloud Messaging (and most other push services), only the developer can create push notifications for their apps. For this reason a user’s server wouldn’t be able to wake up a user’s device directly but has to proxy that wake up signal through the infrastructure of the app developer.

Here is a quick description of how this relationship is set up.

All examples below use real world values from my personal device with a test account. The fact that I’m comfortable making that publicly available can act as an indication on how non privacy sensitive that data is.

What Conversations sends to the app server

  • FCM Token: The FCM token is essentially the address of the device that will be used to address push notifications to. That address can change over time. The address is generated by the Google Play Service on the user’s phone. Conversations has no influence over how and when this is (re)generated and can only request it.

  • Secure Device Id: Since the FCM token can change over time the app server needs a second unique ID per device so when it receives a new FCM token it knows whether this one replaces an existing device or is for an entirely new device. Conversations uses the Android ID which is a unique string that is generated by the Android operating system and persists over the life time of the app. In older versions of Android this used to be shared across all apps. Nowadays every app gets its own ID generated by the OS.

  • The app server then generates a random string (Node ID in the language of the XEP) and stores a combination of the FCM Token, the node id, the domain of the account (not the entire account) and a hashed string of the account jid + the secure device id. Since the account jid is essentially salted with the secure device id the app server operator won’t be able to reverse the account jids by looking at the database. The node id is sent back to the client.

<iq from="" id="cXo5bNCF6wgD" to="" type="set">
  <command xmlns="" action="execute" node="register-push-fcm">
    <x xmlns="jabber:x:data" type="submit">
      <field var="token">
      <field var="android-id">
<iq from="" id="cXo5bNCF6wgD" to="" type="result">
  <command xmlns="" action="complete" node="register-push-fcm" sessionid="1526463999190">
    <x xmlns="jabber:x:data" type="form">
      <field type="jid-single" var="jid">
      <field type="text-single" var="node">
      <field type="text-single" var="secret">

What Conversations sends to the user’s server

After registering with the App server, Conversations sends the node ID and the jid of the app server ( to the user's server.

<iq type='set' id='x42'>
  <enable xmlns='urn:xmpp:push:0' jid='' node='eKxTS5n3bOe0'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'><value></value></field>
      <field var='secret'><value>KK4+H5WMfpRG/2zCbuKq6wpX</value></field>

What the app server stores

device                                   | domain    | token                                                                                                                                                    | node         | secret                
ec164939a8485ee6b7f7871071a11c7bb18aead5 | | eeDXSJjASJY:APA91bEKxhXK54-vHhY9O55JmU2R0nDJL2rRENm-W9uPY6x3jHi0i0OyvPu6js9jVPZqDeX9ZQydZCBZE19o7a0kK4_n88fCgufXjaOlvalh9VibB2zOI7dQRTaDNB3H5s4dicpWD0m4 | eKxTS5n3bOe0 | KK4+H5WMfpRG/2zCbuKq6wpX

What the user’s server sends to the app server

When a push is required (this is determined with internal logic of the user’s server that is out of scope of this document) the user’s server will send the node id to the app server. The user’s server can also add additonal information like number of messages pending, the sender jid of the last message and even the body of the last message. Whether or not this information is included is up to the implementation and the configuration of the user’s server and is out of scope for this document as well. Whether or not the app server receives that additional information it will just ignore it and not process it. The sender jid for the push is the the jid of the server. Since the app server didn’t store the account jid and since the account jid is not included in the push it won’t know for which account the push is actually for. It will just be able to look up the corresponding FCM token based on the node id.

An example of that communication can be found in XEP-0357 Section 7.

What the app server sends via Google to the user’s device

Upon receiving a push request from a XMPP server, the app server looks up the hashed account jid + secure device id combination and the FCM token. It then sends the hash via Google to the user's device, using the token (remember: 'token' means 'device address' in FCM language).

The hash can then be used by Conversations to determine which of a number of accounts should be woken up. The hash is not reversible but since Conversations has a limited number of accounts and also knows the secure device id it can just calculate all hashes. Google only sees that hash and nothing else.


Further optimizations

An alternative design omits registration with the app server and instead stores the token on the user’s server. For each push the XMPP server includes all information the app server needs to execute the push. The app server becomes a true proxy that doesn’t require its own database.