Push Tutorial

GroupMe's push service lets you build your own full-fledged chat client. It uses a publish-subscribe model based on the Bayeux protocol , which enables bidirectional communication between the server and connected clients over websockets or HTTP long-polling.

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","websocket"],
      "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.