Colloquy for iPhone -- Push Notification Server

Colloquy is a great IRC client for Mac, as well as the iPhone. Currently, to run Colloquy on the iPhone you must purchase the mobile version from the App Store. The other option is to download the source and build it yourself, but you must be a registered iPhone developer to run it on an actual iPhone. Also, if you intend to use push notifications (via the Colloquy ZNC plugin), you must have a push certificate as well.

Getting Started

I am going to assume that you have znc installed, and you know how to use it. Next, we need to install the Colloquy ZNC module, so that Colloquy can communicate with ZNC (and allow us to have push functionality). See this page for complete instructions.

The module for ZNC accepts commands from the Colloquy client, notably information on push notifications(device token, etc,.).

Modifying the Colloquy Mobile Source

Next, we need to download and build the source. Once you have downloaded the source and loaded up the Mobile Colloquy project in Xcode, we need to make a few modifications.


To run any application on an actual iPhone device, it must be signed. Login to your Developer portal on Apple’s site and generate a certificate (and make sure to enable push). Download the certificate and install it. Next, assign that certificate to the Colloquy Mobile Project. Project…Edit Active Target. Make sure that under the Properties tab, you have the same Identifier name that you used when generating the certificate. Go to Build, and then Code Signing Identity and select the certificate.

Modifying the source

Next, find the CQConnectionsController.m file (Controllers/Connections) and change the following line from:

[self sendRawMessage:@"PUSH service 7906"];

and change it to:

[self sendRawMessage:@"PUSH service 7906"];

This will make the client tell the Colloquy ZNC module to send push notifications to our custom server.

Build the project and put it onto your device.

Push Server

I wrote a simple python script that waits on port 7906, receives a connection from the Colloquy ZNC module, and then pushes a notification to your phone (via Apple’s Push Service).

The script requires your push certificate and private key file so it can authenticate to Apple’s push service.

Export the push certificate and private key as a .p12 from Keychain Access. After that, we have to convert it to PEM format:

openssl pkcs12 -in key.p12 -out certs.pem -nodes

where key.p12 is the file exported from Keychain access.

After that, you may need to put that certs.pem file on your server that you are running ZNC on.

Installing the Colloquy Push Server

Run the following to install the Colloquy Push Server:

sudo easy_install

Next, run the command to make sure installation was successful.

The usage looks like this:

usage: /usr/local/bin/ [-p listen_port] [--sandbox] [-b] certs_file
	Command Summary:
		certs_file	        PEM encoded Apple Push certificate and private key file(absolute path)
		-p listen_port	Default Listen Port: 7906	
		--sandbox 	Connect to Sandbox Service
		-b		        Run in background

Now, let’s start the push server in the foreground. Make sure to specify the full path to the pem file we created. ~/certs.pem


Finally, connect to your ZNC server with the custom built Colloquy Mobile. Your iPhone should register with the ZNC module. After, exit the Colloquy Mobile application and pull up Colloquy (or any other IRC client) on your desktop. Send yourself a message, and see if you get the push notification!

I realize this process may not be completely clear, so if you have any questions, I would be happy to walk you through the process.

Also, I just wrote this up today, so it may not be production ready :).