Synchronization comments

Comments synchronization

Comments synchronization allows you to save Cackle comments in your local database server for storage and indexing by search engines. For synchronization you need to receive comments for each page of your site by using the following API.

API for getting channel's list

HTTP method	Endpoint	Limit	Description
GET	http://cackle.me/api/3.0/comment/chan/list.json	1 every 5 seconds	To receive comments on a particular page of the site. A maximum of 100 comments for 1 request. The request data encoding UTF-8.

Request parameters:

Parameter	Mandatory	Type	Description
id	Yes	The widget ID	You can get in the admin panel, on menu "Install" tab "CMS Platform" and choose WordPress.
siteApiKey	Yes	The widget API key	You can get in the admin panel, on menu "Install" tab "CMS Platform" and choose WordPress.
accountApiKey	Yes	The account API key	You can get in the admin panel, on menu "Install" tab "CMS Platform" and choose WordPress.
gtModify	No	Date in milliseconds	Passing this parameter, the API will return comments which modification time greater than modified. Without this parameter, you will have all channels

API for getting comments for the specific channel

HTTP method	Endpoint	Limit	Description
GET	http://cackle.me/api/3.0/comment/list.json	1 every 5 seconds	To receive comments on a particular page of the site. A maximum of 100 comments for 1 request. The request data encoding UTF-8.

Request parameters:

Parameter	Mandatory	Type	Description
id	Yes	The widget ID	You can get in the admin panel, on menu "Install" tab "CMS Platform" and choose WordPress.
siteApiKey	Yes	The widget API key	You can get in the admin panel, on menu "Install" tab "CMS Platform" and choose WordPress.
accountApiKey	Yes	The account API key	You can get in the admin panel, on menu "Install" tab "CMS Platform" and choose WordPress.
chan	Yes	The page ID (channel)	More info about channel.
commentId	No	The Cackle comment ID	Passing this parameter, the API will return comments which id greater than commentId. Cannot be passed with the modified parameter.
modified	No	Date in milliseconds	Passing this parameter, the API will return comments which modification time greater than modified. Cannot be passed with the commentId parameter.

How to use this API

To successfully configure synchronization using this API we recommend the following two actions:

I. Save all Cackle channels
I. Save all Cackle comments in the local database
III. Catch of add/changes Cackle comments
IV. Sync lib on phps

I. Save all Cackle channels

To save all the comments, you must have a list of all channels (chan parameter) on your website.

Algorithm

1. Calling API for getting all channels without parameter gtModify:
http://cackle.me/api/3.0/comment/chan/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}
2. In json API response there is channel's array:
{"chans":[ {"id":101, "channel": '101', modified: ...}, {"id":102, "channel": '102', modified: ...}, ... {"id":216, "channel": '216'. modified ...} ]}
3. If channels less than 100, all channels on this site should be saved to local database(as separate records or object of array) in order to further pass on them to sync, and also save max of channel's 'modified' from all channels, which will continue to be used for getting modified channels(param gtModify);
4. If they are 100, wait 5 seconds and you can call the API again to retrieve the next packet, go to item 1 with 'page' param;

II. Save all Cackle comments in the local database

To save all the comments, you must have a list of all channels (chan parameter) on your website.

Algorithm

1. Callable API for the selected channel (chan parameter) with parameter commentId=0:
http://cackle.me/api/3.0/comment/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}&chan={chan}&commentId=0
2. In the JSON response of the API comes in an array of comments sorted by id from old to new:
{"comments":[ {"id":101, "siteId": ...}, {"id":102, "siteId": ...}, ... {"id":216, "siteId": ...} ]}
3. If comments less than 100, it is all the comments on this channel, save comments in the local database;
4. Wait 5 seconds and you can call the API again for the next channel, i.e. go to paragraph 1;
5. If 100 comments, on this channel any more comments. Save all 100 comments in a local DB and save the id of the last comment from the array of "comments" (it will be the maximum in the above example, this 216);
6. Wait 5 seconds and call the API again for the current channel with commentId parameter is the id of the last saved comment from paragraph 5 (commentId=216);
7. The response comes with next comments for the current channel with comments an id greater than commentId parameter;
8. Go to paragraph 3 (if comments < 100) or 5 (if comments 100).

Example

Let your site http://mysite.com registered in Cackle with id 1, siteApiKey 123, accountApiKey 321.
According algorithm for getting channel we should do the following things:

1. Call API:
http://cackle.me/api/3.0/comment/chan/list.json?id=1&siteApiKey=123&accountApiKey=321
2. Response will be:
{"chans":[ {"id":1, "channel": '1', url: 'http://mysite.ru/page1',...}, {"id":2, "channel": '2', url: 'http://mysite.ru/page2',...}, {"id":3, "channel": '3', url: 'http://mysite.ru/page3',...} {"id":4, "channel": '4', url: 'http://mysite.ru/page4',...} ]}
3. If channel less than 100, save channel to local database, and also save maximum of channel's 'modify' param;

On the supposed site we have 4 pages and each include Cackle comments widget:

http://mysite.com/page1 - 3 comments
http://mysite.com/page2 - 230 comments
http://mysite.com/page3 - 125 comments
http://mysite.com/page4 - 99 comments

According to the algorithm to store all the comments we need to do the following:

1. Call API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page1&commentId=0
2. The response comes:
{"comments":[ {"id":1, "siteId": ...}, {"id":2, "siteId": ...}, {"id":3, "siteId": ...} ]}
3. Comments less than 100 and that all comments on this channel, save comments in the local database;
For /page1 saved all 3 comments.

1. Call API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page2&commentId=0
2. The response comes:
{"comments":[ {"id":4, "siteId": ...}, {"id":5, "siteId": ...}, ... {"id":104, "siteId": ...} ]}
5. Comments are 100 means the page has more comments. Stored received 100 comments in a local database and remember the id of the last comment 104;
6. Call API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page2&commentId=104
7. The response comes:
{"comments":[ {"id":105, "siteId": ...}, {"id":106, "siteId": ...}, ... {"id":205, "siteId": ...} ]}
5. Comments are 100 means the page has more comments. Stored received 100 comments in a local database and remember the id of the last comment 205;
6. Call API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page2&commentId=205
7. The response comes:
{"comments":[ {"id":206, "siteId": ...}, {"id":207, "siteId": ...}, {"id":236, "siteId": ...} ]}
5. Comments less than 100 and that all comments on this channel, save comments in the local database;
For /page2 saved all 230 comments.

1. Call API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page3&commentId=0
2. The response comes:
{"comments":[ {"id":237, "siteId": ...}, {"id":238, "siteId": ...}, ... {"id":337, "siteId": ...} ]}
5. Comments are 100 means the page has more comments. Stored received 100 comments in a local database and remember the id of the last comment 337;
6. Call API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page3&commentId=337
7. The response comes:
{"comments":[ {"id":338, "siteId": ...}, {"id":339, "siteId": ...}, ... {"id":363, "siteId": ...} ]}
5. Comments less than 100 and that all comments on this channel, save comments in the local database;
For /page3 saved all 125 comments.

1. Call API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page4&commentId=0
2. The response comes:
{"comments":[ {"id":364, "siteId": ...}, {"id":365, "siteId": ...}, ... {"id":463, "siteId": ...} ]}
3. Comments less than 100 and that all comments on this channel, save comments in the local database;
For /page4 saved all 99 comments.

II. Catch of add/changes Cackle comments

To track adds or changes (edit, delete, moderate, voting) Cackle comments, you must have a list of all channels (chan parameter) on your site and saved for each channel, time of last modification (modified parameter).

Algorithm for getting modified channels

1. Сall API to receive all channels with parameter 'gtModify' stored during initial channel's list receiving:
http://cackle.me/api/3.0/comment/chan/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}
2. In json response api, there is array of channels:
{"chans":[ {"id":101, "channel": ...}, {"id":102, "channel": ...}, ... {"id":216, "channel": ...} ]}
3. If channels less than 100, all channels on this site should be saved to local database(as separate records or object of array) in order to further pass on them to sync, and also save max of channel's 'modified' from all channels, which will continue to be used for getting modified channels(param gtModify);
4. If they are 100, wait 5 seconds and you can call the API again to retrieve the next packet, go to item 1 with 'page' param;

Algorithm for getting comments changes for the spicific channel

1. Call API for the selected channel (chan parameter) with the parameter modified=<time in milliseconds> (usually modified taken from the last comment when saved synchronization of all Cackle comments or just now):
http://cackle.me/api/3.0/comment/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}&chan={chan}&modified=1657072210181
2. In the JSON response of the API comes in an array of comments with a modification time greater than modified parameter
{"comments":[ {... "modified":"1432421378073"}, {... "modified":"1432447569166"}, ... {... "modified":"1432467294131"} ]}
3. Save for current channel (chan parameter) the modification time of the last comment (in the example above 1432467294131);
4. Wait 5 seconds and you can call the API again for the next channel with an initial modified, that is, go to paragraph 1;
5. If we used all the channels, then turn to the first channel and the called API with modified parameter stored for this channel (in the example 1432467294131);
6. Next, move to the next channel and call the API with the previously stored modified specifically for this channel.

In practice, implementing the algorithm, you typically create a separate table that stores the value [chan, modified]. When someone visits your website page, you can determine the channel (chan) and take modified (from [chan, modified] table), then you can call API. Also be sure to check the timer between requests, it needs to be at least 5 seconds.

Example

Let your site http://mysite.com registered in Cackle with id 1, siteApiKey 123, accountApiKey 321 and gtModify 1455652041007 saved in the previous steps of getting channels list.

1. Calling API:
http://cackle.me/api/3.0/comment/chan/list.json?id=1&siteApiKey=123&accountApiKey=321&gtModify=1455652041007
2. Response:
{"chans":[ {"id":1, "channel": '1', url: 'http://mysite.ru/page1',...}, {"id":2, "channel": '2', url: 'http://mysite.ru/page2',...},
3.Channels less than 100, save channels to local database for getting modified comments, and also save channels 'modify' param for future requests;

So, on supposed site there are 2 pages and each include Cackle comments widget:

http://mysite.ru/page1
http://mysite.ru/page2

For the implementation of the algorithm must be created in the DB table with the channel and time of last modification [chan, modified]:

CREATE TABLE chan_modified (chan character varying(1000), modified bigint, CONSTRAINT chan_modified_pkey PRIMARY KEY (chan));

To insert the initial value (modified just select as the current time):

INSERT INTO chan_modified VALUES ('/page1', 1432421378073); INSERT INTO chan_modified VALUES ('/page2', 1432421378073);

1. Call API for the first channel /page1:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page1&modified=1432421378073
2. In the JSON response most likely will come empty array {"comments":[]} because hardly anyone will have time to post or edit comments;
3. Wait 5 seconds and you can call the API again for the next channel /page2 with his modified;
4. Albeit it took some time and /page1 appeared two comments, called API with chan=/page1&modified=1432421378073:
{"comments":[ {"id":1, "siteId": ... "modified":"1432422582935"}, {"id":2, "siteId": ... "modified":"1432422739512"} ]}
5. Save both comments in the database with their Cackle id (1, 2);
6. Update in the table chan_modified field modified from the latest comment for the current channel /page1:
UPDATE chan_modified SET modified = 1432422739512 WHERE chan = '/page1';
7. Wait 5 seconds and you can call the API for the next channel /page2;
8. Suppose after some time the comment with id 1, was edited by the author on the page /page1;
9. Making the API request with chan=/page1&modified=1432422739512 get this comment:
{"comments":[{"id":1, "siteId": ... "modified":"1432423183461"}}]}
10. As Cackle id we are also stored in the database, it is easy to find the comment with id 1, and update it;
11. Update in the table chan_modified field modified for the current channel /page1:
UPDATE chan_modified SET modified = 1432423183461 WHERE chan = '/page1';
12. Wait 5 seconds and you can call the API to the next channel.

IV. Sync lib on php

Sync lib on php - Cackle comments sync