Social Sharing API \ Publish a message to one or more social networks

Workflow

1. Request: the code to send to the API

Send a POST request to the resource /sharing/messages.<format> and include the structure below as POST data to publish a new message to one or more social networks (code example).

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. You can publish a message on multiple social networks simultaneously, the API takes care of dispatching the message accordingly.

1. Publish a new message on behalf of a user to multiple social network simultaneously
2. Publish a new message on behalf of a user to a given social network identity

1.1. Publish a new message on behalf of a user to multiple social network simultaneously

		{
			"request": {
				"sharing_message": {
					"publish_for_user": {
						"user_token": "<user_token>",
						"providers": [
							"facebook",
							"twitter",
							"linkedin"
						]
					},
					"parts": {
						"text": {
		          "body": "Message Body"
		        },
		        "picture": {
		          "url": "http://www.example.com/my_picture.png"
		        },
		        "video": {
		          "url": "http://www.example.com/my_video.mov"
		        },
		        "link": {
		          "url": "http://www.example.com/url1.html",
		          "name": "Example Site",
		          "caption": "Text Below Link",
		          "description": "Link description, can contain an url http://www.example.com/url2.html"
		        }
		        "flags": {
		          "enable_tracking": "1"
		        }
		      }		     
		    }
		  }
		}

1.2. Publish a new message on behalf of a user to a given social network identity

		{
		  "request": {
		    "sharing_message": {
		      "publish_for_identity": {
		        "identity_token": "<identity_token>"	
		      },
		      "parts": {
						"text": {
		          "body": "Message Body"
		        },
		        "picture": {
		          "url": "http://www.example.com/my_picture.png"
		        },
		        "video": {
		          "url": "http://www.example.com/my_video.mov"
		        },
		        "link": {
		          "url": "http://www.example.com/url1.html",
		          "name": "Example Site",
		          "caption": "Text Below Link",
		          "description": "Link description, can contain an url http://www.example.com/url2.html"
		        }
		        "flags": {
		          "enable_tracking": "1"
		        }
		      }	
		    }
		  }
		}

2. Result: the code returned by the API

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

If the overall response status is 207, you should examine the status section of each publications sub-result for further information about the success or failure of the method execution.

sharing_message_token

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.

tracked_shorturls

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 details of an url.

Result Example

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