Tutorials

Podio provides a push service to give you realtime notifications about events happening in your inbox, global stream or any workspace you are a part of. The push service is based on CometD / Bayeux.

The push service endpoint is:

https://push.podio.com/faye

Working with push service

Make life easier for yourself and grab a CometD / Bayeux client. Faye is an excellent choice. In order to authenticate with the push service you will need to sign your subscriptions. You will get the signatures needed from the Podio API. The general flow is:

Authenticate with the Podio API as the user you want to receive push notifications for.
Use a normal API operation (e.g. Get User Status or Get Item) to get the object you want push for. The object will contain a push property which holds the channel, signature and timestamp.
Connect to the push service using CometD and subscribe to the channel you found in the previous step.
Listen to incoming push messages. Each type of push event will contain slightly different data. It's likely that you will want to use additional API operations to get more information about what happened.

Authentication

Whenever you subscribe to a channel you need to provide extra information in the subscribe call for each channel. You get this information from the API operation, but you need to amend your CometD subscription request manually. The specific way depends on the library you're using (see below for a faye example).

The subscribe call in CometD is just a JSON hash, which you need to extend with an additional "ext" key:


{
  "channel": "/meta/subscribe",
  "subscription": "", // channel received from API call,
  "ext": {
    "private_pub_signature": "", // signature received from API call
    "private_pub_timestamp": ""  // timestamp received from API call
  }
}

Sample code: node.js and faye

You can find a basic implementation using node.js and faye on GitHub.

Push carriers

The following types of objects carry a push signature.

Carrier Object	Push Events
User	notification_unread, notification_create
Space	stream_create
Item	comment_create, comment_update, comment_delete, grant_create, grant_delete, file_attach, file_delete, create, update, delete, rating_like_create, rating_like_delete, stream_event, subscribe, unsubscribe, typing, viewing
Task, Status, File, Action	comment_create, comment_update, comment_delete, file_attach, file_delete, create, update, delete, rating_like_create, rating_like_delete, stream_event, subscribe, unsubscribe, typing, viewing
Conversation	conversation_starred_count, conversation_unread_count, conversation_starred, conversation_unstarred, conversation_read, conversation_unread, conversation_read_all, conversation_event
Live	live_settings, live_end, live_accept, live_decline

Push event reference

The push payload have the same structure for all events:


{
  "ref": // The reference to the carrier of the event
  {
    "type": "", // The type of object,
    "id": ""    // The id of the object
  },
  "event": "",      // The type of the event,
  "created_by": // The entity who caused the event
  {
    "type": "", // The type of entity, f.ex. "user" or "app",
    "id": ""    // The id of the entity, f.ex. the id of the user or app
  },
  "created_via": "", // The id of the OAuth client who caused the event, if any,
  "data": ""         // Details about the specific event, depends on the event type
}

Below each push event and it's associated data is described.

notification_unread

When the unread notification counter changes. The carrier is the user who is the target of the notifications.


{
  "count": // The new number of unread notifications
}

notification_create

When there is a new notification for the user. The carrier is the user who is the target of the notification.


{
  "text": "", // A default text to show for the notification,
  "link": "", // The link to the object that was the source of the notification,
  "icon": "", // The name of the icon to use,
  "notification_id": "", // The id of the notification,
  "settings": // The users push notification settings
  {
    "sound": "", // True if a sound should be emitted, false otherwise,
    "browser": "" // True if the notification should be shown using the browsers native system, false otherwise
  }
}

stream_create

When a new event happens in the stream. The carrier is the space the event occurred in.


{
  "context_ref": // The main object that the event happened on
  {
    "type": "", // The type of the object,
    "id": "" // The id of the object
  },
  "data_ref": // The object that was the cause of the event
  {
    "type": "", // The type of the object,
    "id": "" // The id of the object
  },
  "app_id": "" // The id of the app the event was on, if any
}

comment_create, comment_update, comment_delete

When a comment is created, updated or deleted. The carrier of the event is the object the comments are on.


{
  "data_ref": // The reference to the comment
  {
    "type": "comment",
    "id": // The id of the comment
  }
}

grant_create, grant_delete

When a grant is created or deleted on the object. The carrier of the event is the object the grant is on.


{
  "data_ref": // The reference to the grant
  {
    "type": "grant",
    "id": // The id of the grant
  }
  "count": "" // The total number of grants on the object
}

file_attach, file_delete

When a file is attached or removed from an object. The carrier of the event is the object the file is attached to.


{
  "data_ref": // The specific reference where the file is attached
  {
    "type": "", // The type of reference,
    "id": "" // The id of the reference
  }
}

create, update, delete

When an object is created, updated or deleted. The carrier is the object in question, where supported object types are item, status and task.


{
  "data_ref": // The reference to the object itself
  {
    "type": "", // The type of object,
    "id": "" // The id of the object
  }
}

rating_like_create, rating_like_delete

When an object is liked or unliked. The carrier is the main object the like is associated with.


{
  "data_ref": // The reference to the object rated
  {
    "type": "", // The type of the object,
    "id": "" // The id of the object
  },
  "type": "", // The type of rating, e.g. "like",
  "count": "" // The total number of ratings of the given type
}

stream_event

When a new event happens on object. The carrier is the object the event happened on.


{
  "type": "", // The type of event, see the stream area for details,
  "data_ref": // The object that was the cause of the event
  {
    "type": "", // The type of the object,
    "id": "" // The id of the object
  }
}

subscribe, unsubscribe

When a user subscribes or unsubscribes from an object. The carrier is the object on which the subscription is changed.


{
  "data_ref": // The reference to the subscription
  {
    "type": "subscription",
    "id": "" // The id of the subscription
  },
  "count": "" // The total number of active subscribers
}

typing, viewing

When the active viewers and "typers" on an object changes. The carrier is the object the users are typing on/viewing. The data is the user_id's of the currently active viewers and typers.


[
  // {user_id},
  // ... (more users)
]

conversation_starred_count, conversation_unread_count

When a conversation is starred/unstarred and read/unread. The carrier of the event is the active user.


{
  "count": // The number of starred/unread conversation events
}

conversation_starred, conversation_unstarred

When a conversation is starred/unstarred


  {
    "conversation_id": // The id of the conversation that was changed
  }

conversation_read, conversation_unread

When a conversation is read/unread


{
  "conversation_id": "", // The id of the conversation that was changed,
  "unread_count": "", // The number of unread events on the conversation,
  "total_unread_count": "" // The total number of unread events
}

conversation_read_all

When all conversations was marked as read

conversation_event

When a message is added to a conversation, a participant is added to a conversation, a participant leaves a conversation or the subject of a conversation is changed. The carrier of the event is the user's own object.


{
  "conversation_id": "", // The id of the conversation,
  "event_id": "", // The id of the event,
  "action": "", // The action that was performed. See the conversation area for details.
  "text": "", // A short excerpt of the event, f.ex. a preview of the message,
  "created_on": "", // The date and time when the event was created. This can be compared to the "last_event_on" on the conversation to see if this is never than the already known.
  "created_by": "", // The byline of the user who created the event,
  "unread_count": "", // The number of unread events on the conversation,
  "total_unread_count": "" // The total number of unread events on all conversations
}

live_settings

When the settings on the live session changes. The carrier is the live object.


  {
    "settings": // The updated settings
  }

live_end

Sent when the live session ends. The carrier is the live object.


{
  "end_reason": // The reason the live session ended
}

live_accept, live_decline

Sent when a user accepts or declines a live session (call).


{
  "user_id": // The id of the user who accepted or declined the call
}