Push Tutorial

GroupMe's push service lets you build your own full fledged chat client. It runs off of Faye , a websockets-based implementation of the Bayeux protocol , which enables bidirectional communications between web clients. Here at GroupMe, our iOS engineers use socketrocket to handle websockets, while our Android developers use the weberknecht websockets client library.

In case you don't have the luxury of using a library to abstract away the details of connecting to the push server, here's a step by step guide to doing so at the HTTP level.

A Few Notes:

• JSON strings in the POST body must use double quotes, for some reason single quotes returns a bad request
• Content-Type must be application/json
• Signature must refresh every hour

Step 1: Handshake

Send a POST to https://push.groupme.com/faye. The body should look like this:

[
  {
    "channel":"/meta/handshake",
    "version":"1.0",
    "supportedConnectionTypes":["long-polling"],
    "id":"1"
  }
]

If all is good, we should respond with:

[
    {
      "id":"1",
      "channel":"/meta/handshake",
      "successful":true,
      "version":"1.0",
      "supportedConnectionTypes":["long-polling","cross-origin-long-polling","callback-polling","websocket","in-process"],
      "clientId":"0wgyczg0sbd91m0uc8wyv09qblos",
      "advice": {"reconnect":"retry","interval":0,"timeout":30000}
    }
  ]

Step 2: Subscribe to the user channel

The user channel is where new message events get published. With the signature you got from the previous step, subscribe to the user channel, via a POST to https://push.groupme.com/faye, with the following body:

[
  {
    "channel":"/meta/subscribe",
    "clientId":"1c5k4zq1mycffe161kgqp13gnvvn",
    "subscription":"/user/<userid>",
    "id":"2",
    "ext":
      {
        "access_token":"<your API access token>",
        "timestamp":1322556419
      }
  }
]

A note about the id - this number should increment with each successive call to the server. I'm not sure what happens if you keep it static.

GroupMe's response:

[
  {
    "id":"2",
    "clientId":"1c5k4zq1mycffe161kgqp13gnvvn",
    "channel":"/meta/subscribe",
    "successful":true,
    "subscription":"/user/1000112"
  }
]

And you're subscribed to that channel.

Step 3: Subscribe to the Group Channel

The group channel allows you to receive typing notifications, which occur when another group member is in the middle of typing a message. That POST is similar. The body looks like:

[
  {
    "channel":"/meta/subscribe",
    "clientId":"1c5k4zq1mycffe161kgqp13gnvvn",
    "subscription":"/group/<groupid>",
    "id":"2",
    "ext":
      {
        "access_token":"<your API access token>",
        "timestamp":1322556419
      }
  }
]

Step 4: Poll for data

At this point, you should be ready to receive incoming push events from us. You have some options at this point: you can perform long-polling over HTTP, but we recommend dropping down to websockets if you have the option. POST to /faye Body:

[
  {
    "channel":"/meta/connect",
    "clientId":"0bopcao0ta10ju0d4kco10592sji",
    "connectionType":"long-polling",
    "id":"3"
  }
]

Response, if there's nothing to report:

[
  {
    "id":"53",
    "clientId":"0w1hcbv0yv3puw0bptd6c0fq2i1c",
    "channel":"/meta/connect",
    "successful":true,
    "advice": {"reconnect":"retry","interval":0,"timeout":30000}
  },
  {
    "channel": "/user/185",
    "data":{"ping":true},
    "clientId":"0w1hcbv0yv3puw0bptd6c0fq2i1c",
    "id":"54",
    "ext": {"access_token":"<access token>","timestamp":1322557872},
    "authenticated":true
  }
]

Response, if the push server has a message to send back to you:

[
    {
      "id":"5",
      "clientId":"0w1hcbv0yv3puw0bptd6c0fq2i1c",
      "channel":"/meta/connect",
      "successful":true,
      "advice":{"reconnect":"retry","interval":0,"timeout":30000}
    },
    {
      "channel":"/user/185",
      "data": {
        "type":"line.create",
        "subject": { "name":"Andygv",
        "avatar_url":null,
        "location": { "name":null, "lng":null,"foursquare_checkin":false,"foursquare_venue_id":null,"lat":null},
        "created_at":1322557919,
        "picture_url":null,
        "system":false,
        "text":"hey",
        "group_id":"1835",
        "id":"15717",
        "user_id":"162",
        "source_guid":"GUID 13225579210290"
      },
      "alert":"Andygv: hey"
    },
    "clientId":"1lhg38m0sk6b63080mpc71r9d7q1",
    "id":"4uso9uuv78tg4l7csica1kc4c",
    "authenticated":true
  }
]

---

Questions? Check out our GroupMe API Support Google Group.