up


Custom Feed API Documentation

Imported Feeds in Convo let you share content from a website to your company News Feed automatically, eliminating the time and effort required to do this manually. This content is sent to a Convo backend service that publishes the link to your News Feed.

You can access this functionality through the Convo Imported Feed API. The API is available to all Premium networks at no extra charge and helps you create richer, more meaningful and customized feeds by importing content from the web that matter most to you and your team.

An Imported Feed can be added by anyone. Since posts that are automatically imported through the API are expected to be of a higher volume, we have split the Imported Feed stream from your main News Feed, but you can always view the Imported Feed by selecting it from the groups list or by typing in the Feed's name in the search box.

All Imported Feeds in the network are visible to network members in the group list. When you want an Imported Feed to remain private, you can set up access and permission options so only those you approve have access. Just like Groups The Imported Feed creator or an existing member can invite a new user to subscribe or "Follow" an Imported Feed.

Authenticating the API calls

The API uses the HTTP Authorization header to pass authentication information. The Authorization header should have the following form:

Authorization: AccessKeyID:Signature

Each network in Convo is pre-assigned a AccessKeyID/SecretAccessKey pair. The AccessKeyID identifies the network, the API (eg. Imported Feed API) and the SecretAccessKey that was used to calculate the signature. The access keys are available to the network Administrator in the admin panel.


 

The signature is the HMAC-SHA1 (RFC 2104) digest of the request data. When a request is received, the signature is calculated using the secret key and if it matches the signature sent in the request then the request is authorized.

Following is a sample Python script for generating the Authorization header: request_params = urllib.urlencode({'param1': 'value1', ...})

access_key_id = 'sample_id' secret_access_key = 'sample_secret' stringToSign = request_params signature = hmac.new(secret_access_key, stringToSign, hashlib.sha1).hexdigest()

headers = {"Content-type": "application/x-www-form-urlencoded", "Authorization": access_key_id + ":" + signature}


Throttling

API calls should be throttled at 1 call per second. Exceeding this rate will result in a failed request with response code 403 (Forbidden).


Imported Feed API v1:

Post a web link:

To post a web link to an imported feed, send a Https POST request to the following Url with the following parameters. The post data should be form url encoded.

POST //www.convo.com/api/v1/importedfeed

Parameters:

url:
Url of the web link.

title:
Title of the web link. 128 characters max (will be truncated if larger).

description (optional):
Description of the web link. 250 characters max (will be truncated if larger).

image (optional):

site_name (optional):
Name of the website that the link belongs to.

resource_id:
Id of the imported feed.


 

Response:

201 Created: Web link successfully added to imported feed.

400 Bad Request: Insufficient or invalid parameters.

401 Unauthorized: Authentication failed. Invalid or missing Authorization header.

403 Forbidden: Exceeded throttle limit.

404 Not Found: Resource does not exist.


Click here for a sample script:

Here is a sample script in Python to post a web link to an imported feed using the API. Before executing, substitute the API Access Key ID and Secret Access Key (available in Convo admin panel) and the details of the web link (resource_id, url, title, description, image, site_name). "resource_id" is the ID of the Imported Feed to which the link will be posted. This can be read from the Imported Feed Settings view in Convo.


Learn more about how Convo can change your business. Contact us.
Or, sign up for a free Convo network