Sharing API \ Publish to multiple social networks at once PHP SDK

Advanced Sharing API Resources

Resource/URI	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

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

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 API may return one of the following status codes

200: The message has been published successfully to each of the chosen providers.
207: The message has been published successfully to some but not to all of the chosen providers. Examine the status section of each publications sub-result for further information about the success or failure of the method execution.
4xx: The message has been published to none of the chosen providers

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"
	              }
	            ]
	          }
	        }
	      }
	    }
	  }
	}