Need Help? Support

Sharing Content to Services

The /types endpoints allow you to share content out to multiple services at once. We currently support sharing statuses, news, and photos to multiple services at once. We also support Facebook Open Graph actions.

The URL pattern for sharing looks like

POST /types/:type?access_token=my_token&to=one,two,...

URL parameters:

  • :type The type of data you wish to share.

Query parameters:

  • to A comma-delimited list of supported services you wish to share to. Eg, facebook,twitter.
  • services DEPRECATED A synonym for to

The response is a JSON object with an entry for each service you shared to.

Example URL:

https://api.singly.com/types/statuses?access_token=my_token&to=facebook,linkedin&body=Test

Example Response:

Choosing the author and destination

Facebook

Users who administer Facebook Pages can share on behalf of the page. Do this by specifying a full ID@facebook in the from parameter.

In order to share stories as Facebook Pages, your application must explicitly request the manage_pages permission during authorization. Singly does not do this by default. Your URL will look like:

https://api.singly.com/oauth/authenticate?service=facebook&scope=manage_pages&...

Then for some page_id that your user manages to, POST to

https://api.singly.com/types/:type?from=<page_id>@facebook&to=...&...

Query parameters:

  • from The profile you wish to share as.

LinkedIn

LinkedIn users can send messages to their connections.

To send a message, your application must request the w_messages permission during authorization. (See LinkedIn's documentation for a full description of permissions.) Singly will pass this permission through the scope query parameter:

https://api.singly.com/oauth/authenticate?service=linkedin&scope=w_messages

Then to message a user, POST to /types/messages:

https://api.singly.com/types/messages?to=userID@linkedin&title=Subject&body=Message

Query parameters:

  • to The user who should receive the message. This is the application-specific user ID reported by an endpoint like /friends/linkedin. It is not the user's global LinkedIn ID, nor is it their custom URL nickname.
  • title The subject line of the message
  • body The contents of the message

Twitter

Twitter users can send a Direct Message to anyone who follows them.

In order to send Direct Messages, your application must be set to "Read, Write and Access direct messages" on your Twitter application configuration page. During user authorization, you must also pass Singly the dm flag.

To send a Direct Message, specify a Twitter user in the to parameter:

https://api.singly.com/types/messages?to=singly@twitter&body=Hi!

Tumblr

Users may have multiple blogs hosted on Tumblr, so simply specifying to=tumblr is not specific enough. Instead, specify to=blogname@tumblr.

If the blog is hosted on Tumblr (eg, apijoy.tumblr.com), the subdomain is enough:

to=apijoy@tumblr

If the blog has a custom domain, you must include the full hostname:

to=blog.singly.com@tumblr

Messages

Messages are sent between specific users of a service. Because of the one-to-one nature of messages, most services require that the user grant your application a special permission, for example the Direct Message permission on Twitter or the w_messages permission on LinkedIn.

URL:

POST /types/messages?access_token=my_token&to=...&body=my_message

Query parameters:

  • to The Twitter or LinkedIn user who should receive the message, including the service name (beaugunderson@twitter, for example).
  • title The subject line of the message (when applicable).
  • body The contents of the message.

Supported Services:

  • twitter
  • linkedin

Statuses

Statuses are simple text updates like a tweet or a Facebook status.

URL:

POST /types/statuses?access_token=my_token&to=...&body=my_message

Query parameters:

  • body The text of the status to share

Supported Services:

  • facebook
  • linkedin
  • twitter
  • yammer
  • tumblr

News

News links are URLs to content on the web, like a blog post.

URL:

POST /types/news?access_token=my_token&to=...&body=my_message&url=http://...

Query parameters:

  • body Text describing the link
  • url The link

Supported Services:

  • facebook News is posted to Facebook as a status update with an attachment.
  • twitter News is posted as tweets. If your body text does not already contain the link, it will be appended.
  • tumblr News is posted as a new blog post. If you include a title, it becomes the text of the link. Otherwise, the post displays the URL.

Photos

Photos are pictures taken by your users.

URL:

POST /types/photos?access_token=my_token&to=...

POST Body:

  • photo The photo you wish to upload
  • body (Optional) Text describing the photo (not currently supported by Tumblr)

Supported Services:

  • facebook Photos are uploaded to your application's album on Facebook. If an album does not already exist, Facebook will create it.
  • twitter Photos are uploaded directly to Twitter and attached to a tweet.
  • tumblr Photos are uploaded as a new post.

Open Graph Actions

Facebook's Open Graph allows you to publish actions your user takes to their activity stream on Facebook. Common examples include reading an article or listening to a song, and your application can define custom actions and objects for your users to interact with.

This endpoint is distinct from the rest, since it applies only to Facebook. For full details and options, see Facebook's documentation.

URL:

POST /services/facebook/og/:action?og_param=value&...

URL Parameters:

  • :action The Open Graph action your user is performing. It could be a built-in action like music.listens or one of your app's custom actions, for example singly:published_app.

Query Parameters:

  • og_* Anything beginning with og_ will have the og_ stripped and be passed through to Facebook. This will commonly be an Open Graph object to go with your action, like og_song=song_url, but covers all standard or custom Open Graph parameters.