Loading...

Celly Developer API

To discuss the Celly API, get help, or share your project, join the @api cell

Summary

Customize your social network with the Celly API.  With this API you can send and receive messages to your cells in  a way that best suits your needs.

Client ID & Client Secret

In order to use the Celly API you must first acquire a client_id  and client_secret. These can be found on the profile ->   settings page. Then, click "manage api keys". After filling out  the form you will be provided with a client_id and client_secret.  Make sure to never share the client_secret.

Sase URL

All API interactions should be prefixed with the base URI

https://cel.ly/api

Authentication & authorization

OAuth v2 will be used for authentication. This will allow us the ability to set individual permissions for client applications, and give our users control over what that application is allowed to do with their account.

Authentication endpoints

The authentication endpoints will be constructed from the API Root URI and "oauth/" followed by the specific endpoint.

  • authorize  The endpoint at which a client application can request a new client authentication code
    • request example:
      <BaseURI>/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>
    • response example:
      <redirectURI>?code=<authentication_code>
  • token  This endpoint is where a client application can request/revoke/cycle their app token. The token is unique per application and user (or not logged-in).
    • request example:
    • <BaseURI>/token

      POST body

      client_id=<client_id>&client_secret=<client_secret>&grant_type=authorization_code&code=<authorization_code>

Sample authentication flow

  1. a user opens a client application
  2. no access token exists for the current user, so the user is redirected to the  authorize  endpoint
  3. the user logs in and authorizes permissions for the API
  4. the user is then redirected to the client application with an authorization token
  5. the authorization token is used to retrieve a request token from the  token  endpoint
  6. the request token is sent along with each request to the api to access resources

API Endpoints

all endpoints requests require an oauth_token be provided in the query, form, or header parameters

  • users  endpoints for manipulating Celly user accounts
  • messages  endpoints for individual messages sent on Celly
  • cells  cells are collections of messages, users, receptors, hashtags, and hashlinks
  • me  interact with information about the current logged in user

/users

endpoint:  /users/{uniqueName}

This endpoint allows you to lookup information about other Cellyusers.

{
  "response": {
    "status": "UNKNOWN",
    "score": 19,
    "avatarSource": "DEFAULT",
    "profileScore": 12,
    "sharingScore": 1,
    "avatar": "avatar20",
    "messages": [],
    "msgingScore": 0,
    "rank": 16248,
    "avatarImageId": "avatar20",
    "userId": 940575164,
    "userName": "me",
    "curationScore": 6
  },
  "oauth_token": "1608...ec0c8",
  "uri": "/users/someUser",
  "stat": "OK"
}

endpoint:  /users/{uniqueName}/new-message

This endpoint will send a message to a user.

{
  "response": {
    "body": "what up?",
    "timeWithZone": "09/19/13 11:36:02AM -07:00",
    "avatarSource": "DEFAULT",
    "type": "DIRECT",
    "avatar": "avatar28",
    "timestamp": 1379615762000,
    "time": "09/19 11:36AM",
    "cellId": 939864254,
    "source": "API",
    "avatarImageId": "avatar28",
    "userId": 939864254,
    "userName": "someUser",
    "sendToSelf": false,
    "fullName": "Some User",
    "messageId": 941202652
  },
  "oauth_token": "1608...c0c8",
  "uri": "/users/someuser/new-message",
  "stat": "OK"
}

/messages

endpoint:  /messages

This can be used lookup messages and send messages to  users and cells.

POST
{
  "oauth_token" : "4374...d58b",
  "message" : {
    "body" : "text to post",
    "cellId" : 12345,
    "type" : "DIRECT"    // if cellId is a userId
  }
}
RESPONSE
{
  "response":  {
    "timestamp":1371170621000,
    "time":"06/13 10:43AM",
    "body":"new api test",
    "timeWithZone":"06/13/13 10:43:41AM -07:00",
    "cellId":3530844,
    "source":"API",
    "nonsense":"ok",
    "userId":3523813,
    "userName":"testuser",
    "avatar":"avatar14",
    "type":"MESSAGE",
    "messageId":3555408
  },
  "oauth_token" : "4374...d58b",
  "uri":"/messages",
  "stat":"OK"
}

/cells

endpoint:  /cells/{uniqueName}

This endpoint provides information about cells.

GET
  ?oauth_token=4350...d58b
RESPONSE
{
  "response":  {
    "logo":"http://www.blah.com/blah.jpg",
    "unread":0,
    "subscribed":false,
    "emailOn":true,
    "access":"PUBLIC",
    "type":"OPEN_CHAT",
    "forceUserName":false,
    "body":"testcell",
    "cellId":3530844,
    "admin":true,
    "lastSync":0,
    "omitUserName":false,
    "role":"ADMIN",
    "user":false,
    "lastRead":0,
    "lastMsg":  {
      "timestamp":1371170621000,
      "sender":"testuser",
      "body":"new api test",
      "time":"06/13 10:43AM",
      "source":"API",
      "entityId":3555408,
      "type":"MESSAGE",
      "avatar":"avatar14"
    }
  },
  "oauth_token":"4350...d58b",
  "uri":"/cells/testcell",
  "stat":"OK"
}
POST
{
    "oauth_token" : "4350...d58b",
    "fullName": "Test Cell",
    "coverPhotoImage": "http://myurl.com/blah.jpg",
    "logoImage": "http://myurl.com/blah2.jpg",
    "cellType": "CHAT|BROADCAST|FEEDBACK" // CHAT is unmoderated, BROADCAST is only admins can post, and FEEDBACK everyone can post but all messages must be approved
    "access": "PUBLIC|INVITE_ONLY|PASSWORD|MUST_BE_INVITED|BIO_APPROVE|EMAIL_DOMAIN",
    "tagString": "a,list,of,comma,separated,tags",
    "password": "password", // only needed for PASSWORD access cells
    "emailDomain": "blah.com", // only needed for EMAIL_DOMAIN access cells
    "webPublic": true, // can you cell be listed in public directories?
    "forceUserName": true, // do users need a username to join?
    "hideMembers": false, // should the list of users be kept secret
    "omitUserName": false, // omit usernames from sms messages?
    "description": "This is my cell :D",
    "website": "http://www.blah.com",
    "location": "Portland, OR",
    "sms": true
}
RESPONSE
{
  "oauth_token":"4350...d58b",
  "uri":"/cells/testcell",
  "stat":"OK"
}

endpoint:  /cells/{uniqueName}/new-message

Use this endpoint to send a message to a cell.

POST
{
  "message" : {
    "body" : "some text"
  }
}
RESPONSE
{
  "response":  {
    "timestamp":1371170621000,
    "time":"06/13 10:43AM",
    "body":"new api test",
    "timeWithZone":"06/13/13 10:43:41AM -07:00",
    "cellId":3530844,
    "source":"API",
    "nonsense":"ok",
    "userId":3523813,
    "userName":"testuser",
    "avatar":"avatar14",
    "type":"MESSAGE",
    "messageId":3555408
  },
  "oauth_token":"4350...dd58b",
  "uri":"/cells/{uniqueName}/new-message",
  "stat":"OK"
}

/me

endpoint:  /me

This endpoint provides information about the current user.

GET
  ?oauth_token=4350...d58b
RESPONSE
{
  "response":  {
    "cells":  [
      {
        "name":"testcell",
        "entityId":3530844,
        "uri":"/cells/testcell"
      },
      {
        "name":"ubiquillsocialmedia",
        "entityId":3546359,
        "uri":"/cells/ubiquillsocialmedia"
      }
    ],
    "emailPreference":"ON",
    "UUID":"b47717fd-cd33-4a29-b844-b1d96c1f0372",
    "timeZone":"Pacific",
    "avatar":"avatar14",
    "push":true,
    "pushSound":"CELLY_DEFAULT",
    "discoverable":true,
    "phoneNumber":"5551234567",
    "sessionId":"115106118107135113137118101119106121112135101117:3523813",
    "email":"tester@email.com",
    "userId":3523813,
    "accountType":"PREMIUM",
    "smsPreference":"OFF",
    "userName":"testuser",
    "hasAvatar":true,
    "hasPassword":true
  },
  "oauth_token":"4350...d58b",
  "uri":"/me",
  "stat":"OK"
}

endpoint:  /me/new-message

Use this to post notes to yourself.

POST
{
  "message" : {
    "body" : "some text"
  }
}
RESPONSE
{
  "response":  {
    "body":"new api test blah blah",
    "timeWithZone":"06/13/13 11:55:54AM -07:00",
    "type":"DIRECT",
    "avatar":"avatar14",
    "timestamp":1371174954000,
    "body":"new api test blah blah",
    "time":"06/13 11:55AM",
    "cellId":3523813,
    "source":"API",
    "nonsense":"ok",
    "userId":3523813,
    "userName":"testuser",
    "messageId":3555409
  },
  "oauth_token":"4350...d58b",
  "uri":"/me/new-message",
  "stat":"OK"
}

Help

Solutions

Developers

Company

Policies

loading
loading
loading
sup
loading