How to access the Campfire API with PHP

We have just started using Campfire internally so we can all chat as a group rather than individually over IM. Back in 2006 37signals posted how they were using an unofficial bot to post Subversion source control notices to the chat room and a Ruby library was released, but these are now either unavailable, unmaintained, old or simply don’t work.

Our products are developed in PHP and Python. I have used Ruby (on Rails) in the past but my preference was to use PHP to write a simple script that would pull in the latest entries from our source control activity RSS and “say” any new items in our Campfire chat room.

There is a very simple, official Campfire API that allows you to read and write to specific chat rooms. This is how you can use that API with PHP and Curl to post to your chat rooms.

Requirements

• PHP with Curl
• A Campfire user with an authentication token. You can create a separate user just for this or use your own, it doesn’t matter. The API token is from the “My Info” link in the top right corner.

The request

You can send your request using XML or JSON. I think JSON is easier to work with so used that, but the payload being sent is very small so it really doesn’t make much difference. It is literally just providing the body of the text you want to say:

{"message":{"body":"Hello"}}

Since it is so simple, I didn’t bother making it using json_encode(), but you could do this to save you having to handle escaping slashes.

If you use XML instead then make sure you specify this in the content type header below i.e. Content-type: application/xml instead of Content-type: application/json.

Authentication

You just need to authenticate using your token, within a CURLOPT_USERPWD curl option. No password is needed so we can just provide any value.

curl_setopt($ch, CURLOPT_USERPWD, 'authTokenHere:X');

so if your auth token was 27a3e5e8c1a4e75fbd0bed1465e413e4ea9b5c9c you would use:

curl_setopt($ch, CURLOPT_USERPWD, '27a3e5e8c1a4e75fbd0bed1465e413e4ea9b5c9c');

Executing the request

You do the post against your own unique room URL e.g.

http://boxedice.campfirenow.com/room/12345/speak.json

whichb you get from your browser when you click to enter a room. And put it all together with the following curl code:

$line = 'Lyra and her daemon moved through the darkening Hall, taking care to keep to one side, out of sight of the kitchen.';

$request = '{"message":{"body":"' . addslashes($line) . '"}}';

$ch = curl_init('http://boxedice.campfirenow.com/room/12345/speak.json');
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_USERPWD, 'authTokenHere:X');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-type: application/json'));
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);
curl_close($ch);

Response

The response to a succesful write operation is the status code “201 Created”. We also include the complete XML or JSON for the final resource in the response. This is because you can usually get away with creating a new resource with less than all its regular attributes.

Handling errors is through standard HTTP error codes – see their API docs for details.