User Subscriptions
User subscriptions are useful if you want to be notified when people who authenticated your app post new media on Instagram. This implementation of subscriptions leverages parts of the Pubsubhubub protocol.
Process
Create a Callback URL
When we have new updates to send your server, we do a simple POST with a payload containing updates to a URL on your server. This callback URL must support GET and POST methods.
When you add a subscription, we will send a GET request to your callback URL to verify the existence of the URL. When we have new data, we'll POST this data to your callback URL. We'll explain more about what this URL needs to do later on this page.
https://your-callback.com/url/
Create a Subscription
To create a subscription, you make a POST request to the subscriptions endpoint.
curl -F 'client_id=CLIENT-ID' \
-F 'client_secret=CLIENT-SECRET' \
-F 'object=user' \
-F 'aspect=media' \
-F 'verify_token=myVerifyToken' \
-F 'callback_url=http://YOUR-CALLBACK/URL' \
https://api.instagram.com/v1/subscriptions/
If you run this command with your own callback_url, client_id and client_secret you'll notice it will fail with the error: "Challenge Verification Failed". In order to keep someone else from creating unwanted subscriptions, we must verify that the endpoint would like this new subscription. We do this by following the Pubsubhubub challenge flow.
When you POST with the info above to create a new subscription, we simultaneously submit a GET request to your callback URL with the following parameters:
- hub.mode - This will be set to "subscribe"
- hub.challenge - This will be set to a random string that your callback URL will need to echo back in order to verify you'd like to subscribe.
- hub.verify_token - This will be set to whatever verify_token passed in with the subscription request. It's helpful to use this to differentiate between multiple subscription requests.
For instance, the GET you'll see coming will look like this:
https://your-callback.com/url/?hub.mode=subscribe&hub.challenge=15f7d1a91c1f40f8a748fd134752feb3&hub.verify_token=myVerifyToken
In order to verify the subscription, your server must respond to the GET request with the hub.challenge parameter only:
15f7d1a91c1f40f8a748fd134752feb3
If this request succeeds and everything else about your subscription succeeds as well, you'll get a subscription JSON response from your original POST with the created subscription:
{
"meta": {
"code": 200
},
"data": [
{
"id": "1",
"type": "subscribe",
"object": "user",
"aspect": "media",
"callback_url": "https://your-callback.com/url/"
}
]
}
User subscriptions
In the previous example, we set up a subscription to receive updates whenever one of our client's authenticated users posts a media. Note that this subscription is for all of the client's authenticated users, not just a specific user.
Other than the required client_id, client_secret, and callback_url parameters, the two parameters you need to include in order to subscribe to all photo updates from a user are:
- object: The object you'd like to subscribe to (in this case, "user")
- aspect: The aspect of the object you'd like to subscribe to (in this case, "media"). Note that we only support "media" at this time, but we might support other types of subscriptions in the future.
List your subscriptions
If you'd like to see your current subscriptions, all you have to do is make a GET request to the /subscriptions endpoint
https://api.instagram.com/v1/subscriptions?client_secret=CLIENT-SECRET&client_id=CLIENT-ID
You will recieve the following response:
{
"meta": {
"code": 200
},
"data": [
{
"id": "1",
"type": "subscription",
"object": "user",
"aspect": "media",
"callback_url": "http://your-callback.com/url/"
}
]
}
Delete Subscriptions
To delete subscriptions, you make a DELETE request to the subscriptions endpoint. You can clear subscriptions either by object type or subscription ID, by specifying an "object" or "id" URL parameter respectively. You can clear all your current subscriptions by passing "object=all".
curl -X DELETE 'https://api.instagram.com/v1/subscriptions?client_secret=CLIENT-SECRET&object=all&client_id=CLIENT-ID'
If you'd like to remove a specific subscription, just include the ID of the subscription as a parameter:
curl -X DELETE 'https://api.instagram.com/v1/subscriptions?client_secret=CLIENT-SECRET&id=1&client_id=CLIENT-ID'