Sharing API \ Publish to multiple social networks at once

Send a POST request to this resource to publish content on behalf of a user to his social network accounts.

Resource/URIAdvanced Sharing API Required GET POST PUT DELETE
Sharing API Messages /sharing/messages.json List published messages Publish a new message
Sharing API Message /sharing/messages/<sharing_message_token>.json Get message details Re-Publish a message Delete a message

Workflow

Request: the code to send to the API

Send a POST request to the resource /sharing/messages.json and include the structure below as POST data to publish content to one or more social networks simultaneously. The API takes care of dispatching the message accordingly.

The message representation ultimately depends on the provider. For Twitter for example the message will be published as a new Tweet and for Facebook & LinkedIn as a post on the user's wall.

Publish on behalf of a user_token PHP SDK

Publish a new message on behalf of a user to multiple social networks at once.

Use the following structure as POST data and include a user_token to post content on behalf of a user. The message will be published to all providers specified with the providers node. If a user has for example linked a Facebook and a Twitter account, you can publish content to both social network accounts at once.

			{
				"request": {
					"sharing_message": {
						"publish_for_user": {
							"user_token": "#user_token#",
							"providers": [ 
								"#provider_key1#",
								"#provider_key2#"
							]
						},
						"parts":{
							"text":{
								"body": "#text_body#"
							},
							"video":{
								"url": "#video_url#"
							},
							"picture":{
								"url": "#picture_url#"
							},
							"link":{
								"url": "#link_url#",
								"name": "#link_name#",
								"caption": "#link_caption#",
								"description": "#link_description#"
							},
							"uploads":[
								{
									"name": "#upload_file_name#",
									"data": "#upload_file_data#"
								}
							],
							"flags": {
				          "enable_tracking": "#flag_enable_tracking#"
				       }
						}		     
			    }
			  }
			}
Key Description
* #user_token# The unique token of the user to post the content for.
Example: 9a76c7f6-3705-48a8-8ea6-e862ed86d5d8
* #provider_key1# The key of the first social network to publish the message to.
Example: facebook
#provider_key2# The key of the second social network to publish the message to.
Example: twitter
* #text_body# The text to be published on the social network.
#video_url# The URL of a video to be included in the publication.
Example: http://www.example.com/my_video.swf
#picture_url# The URL of a picture to be included in the publication.
Example: http://www.example.com/my_picture.png
#link_url# A link to be included in the publication.
Example: http://www.example.com/my_page.html
#link_name# The name of the included link.
Example: My page on example.com
#link_caption# The caption of the included link.
Example: Visit us for more
#link_description# The description of the included link.
Example: Our website is about examples.
#upload_file_name# The name of the file to be uploaded.
Example: image.png
#upload_file_data# The base64 encoded representation of the file data.
Example: <?php $data = base64_encode(file_get_contents('image.png')); ?>
#flag_enable_tracking# A flag to turn on (flag=1, default) or to turn off (flag=0) the automatic shortening of URLs included in the post.
Example: 0

Publish on behalf of an identity_token PHP SDK

Publish a new message to a single social network account.

Use the following structure as POST data and include an identity_token to post content for a social network identity.

			{
				"request": {
					"sharing_message": {
						"publish_for_identity": {
							"identity_token": "#identity_token#"
						},
						"parts":{
							"text":{
								"body": "#text_body#"
							},
							"video":{
								"url": "#video_url#"
							},
							"picture":{
								"url": "#picture_url#"
							},
							"link":{
								"url": "#link_url#",
								"name": "#link_name#",
								"caption": "#link_caption#",
								"description": "#link_description#"
							},
							"uploads":[
								{
									"name": "#upload_file_name#",
									"data": "#upload_file_data#"
								}
							],
							"flags":{
				          "enable_tracking": "#flag_enable_tracking#"
							}
						}		     
			    }
			  }
			}
Key Description
* #identity_token# The unique token of the identity to post the content for.
Example: 03939f19-98bd-4a07-a949-531f15ed346b
* #provider_key1# The key of the first social network to publish the message to.
Example: facebook
#provider_key2# The key of the second social network to publish the message to.
Example: twitter
* #text_body# The text to be published on the social network.
#video_url# The URL of a video to be included in the publication.
Example: http://www.example.com/my_video.swf
#picture_url# The URL of a picture to be included in the publication.
Example: http://www.example.com/my_picture.png
#link_url# A link to be included in the publication.
Example: http://www.example.com/my_page.html
#link_name# The name of the included link.
Example: My page on example.com
#link_caption# The caption of the included link.
Example: Visit us for more
#link_description# The description of the included link.
Example: Our website is about examples.
#upload_file_name# The name of the file to be uploaded.
Example: image.png
#upload_file_data# The base64 encoded representation of the file data.
Example: <?php $data = base64_encode(file_get_contents('image.png')); ?>
#flag_enable_tracking# A flag to turn on (flag=1, default) or to turn off (flag=0) the automatic shortening of URLs included in the post.
Example: 0

Result: the code returned by the API

You can publish a message to multiple providers simultaneously and you will therefore always obtain a resultset with a publications node with different result codes - one response for each of the social networks.

The obtained sharing_message_token uniquely identifies the published message. Use it to obtain the message details, to publish the message once again or to delete it.

If you have enabled link tracking, the links contained in your message will be shortened. If a user clicks on a shortened url, the click is counted and the user is instantly redirected to the original url. Use the shorturl_token to retrieve the statistics about the clicks on the URL.

Example Resultset

	{
	  "response": {
	    "request": {
	      "date": "Tue, 20 Dec 2011 19:11:42 +0100",
	      "resource": "/sharing/messages.json",
	      "status": {
	        "flag": "multistatus",
	        "code": 207,
	        "info": "Your request has partially been processed, multiple results and response codes available"
	      }
	    },
	    "result": {
	      "data": {
	        "sharing_message": {
	          "sharing_message_token": "a1ddb4d0-9263-4872-b0e7-18a5565bf78b",
	          "date_creation": "Tue, 20 Dec 2011 19:11:41 +0100",
	          "publications": {
	            "count": 2,
	            "entries ": [
	              {
	                "status": {
	                  "flag": "success",
	                  "code": 200,
	                  "message": "Message published successfully to identity"
	                },
	                "provider": "facebook",
	                "provider_publication_reference": "1234445556_77788899900011122",	  
	                "user_token": "c1d82726-e81d-4e89-82af-fed19df8f64e",
	                "identity_token": "32eb78f4-f82e-4833-8a7b-fa0348c6ff5d",
	                "date_publication": "Tue, 20 Dec 2011 19:11:41 +0100",
	                "shorturls": {
	                  "count": 1,
	                  "entries": [
	                    {
	                      "shorturl_token": "6bTth",
	                      "original_url": "http://www.oneall.com/",
	                      "short_url": "http://oal.lu/6bTth",
	                      "date_creation": "Tue, 20 Dec 2011 19:11:41 +0100",
	                      "num_referrals": 0 
	                    }
	                  ]
	                }
	              },
	              {
	                "status": {
	                  "flag": "error_user_has_no_identity_for_this_provider",
	                  "code": 404,
	                  "message": "The API could not publish the message: this user has no identity for Twitter"
	                },
	                "provider": "twitter",
	                "user_token": "c1d82726-e81d-4e89-82af-fed19df8f64e"
	              }
	            ]
	          }
	        }
	      }
	    }
	  }
	}

User Contributed Notes