Liveworld Content API

Overview

LiveWorld Moderation Server APIs are implemented using REST (Representational State Transfer) APIs. The code samples in this guide use Ruby.

You must connect using TLS 1.2 or higher using an SSL/encrypted connection.

You can use the following API methods to integrate with the moderation server:

• Sending Content
• Retrieving Enriched Content
• Posting a Confirmation
• Retrieving Published Replies

The following lists the tasks that you can perform using the Moderation Server APIs:

• Send content to the Liveworld Moderation Server for review
• Ask for enriched content that has been sent in previously, and reviewed
• Retrieve replies to content that has been sent in previously

Base URLs

For all API access in this document, use the following base URLs:

For testing:

https://modserver-uat.scms.liveworld.com

For production:

https://modserver.scms.liveworld.com

Sending Content

To send content into the Moderation Server, you perform an http POST operation to the path:

/EndPointClientAxis2/rest/moderation_contents.json

• After successfully creating an object, the POST method generates a response code of 201.
• Upon an error, the body of the response may contain an error message.
• A successful post will return the object that was created.
• Please verify that the object that comes back has a tracking_id that matches the one you sent to verify the object was created successfully.

The following fields are required in your data payload:

Field	Description
seed	The seed is the current timestamp in milliseconds. This value must be less than 5 minutes from the current time, so it must be a new seed with each request.
hash_value	The MD5 hash (you must create on each request) of the secret key (assigned by LiveWorld) concatenated with the seed.
customer_id	The customer ID (constant value) assigned by LiveWorld.
system_id	The system ID (constant value) assigned by LiveWorld.
body	The body of the post, description of image or video. It is optional for images and video. (Max length: 65,535 characters)
subject	The subject of the post, caption of images, or title of video. (Max length: 2000 characters)
content_id	The unique id of this content that you generate. (Max length: 255 characters)
tracking_id	The ID for this specific request. If two different people report a message as abusive, they are assigned the same content ID, but different tracking IDs. (Max length: 255 characters) Note: It is very important that all requests have unique tracking IDs.
content_time_stamp	The timestamp when this content was created, in milliseconds.

The following fields are optional: These fields default to a max length of 255 characters, unless noted otherwise.

Field	Description
author_id	The username of the author.
author_email	The email of the author.
author_ip	The IP address of the author.
nvpairs	An array of additional data you want to send in for moderators to consider. (Max length: unlimited)
content_type	text, image, or video. The default value is text.
content_url	For image or video, the URL of the image or video. For text, the URL to view the content in context. (Max length: 2000 characters)

Note: For images and video, please supply the link to view the content in an nvpair named href. See the example below for proper syntax.

For testing, you may also specify a special value for the moderation_status field:

• 0 default; allow content to be queued normally for enrichment
• 208 ​to auto-approve the content; it will be immediately available using the retrieval api
• 224 to auto-reject the content; it will be immediately available using the retrieval api

Example code to submit content:

require 'faraday'
require 'json'
require 'digest/md5'

secret_key = "adsfadfad"
seed = (Time.now.to_f * 1000.0).to_i.to_s  # "1580505807859"
hash_value = Digest::MD5.hexdigest("#{secret_key}#{seed}") # "8670f5984e21ef40213af0ee6ebb13e9"

data = {
  seed: seed,
  hash_value: hash_value,
  customer_id: 'customer_name',
  system_id: 'system_name',
  subject: 'test',
  body: 'lorem ipsum',
  content_id: '123456789',
  tracking_id: 'unique:id:12345:ABC',
  content_time_stamp: seed,
  author_email: 'test@test.com',
  author_id: 'user_handle',
  content_type: 'text',
  nvpairs: [{name: "href", value: "http://mywebsite.com/mypost/"}]
}

conn = Faraday.new(url: 'https://modserver-uat.scms.liveworld.com/EndPointClientAxis2/rest/moderation_contents.json')

response = conn.post do |req|
  req.headers['Content-Type'] = 'application/json'
  req.body = data.to_json
end


ap JSON.parse(response.body)
{
                               "id" => "customer_name:system_name:unique:id:12345:ABC",
                        "system_id" => "system_name",
                          "nvpairs" => [
                            [0] {
                               "name" => "href",
                              "value" => "http://mywebsite.com/mypost/",
                            }
                          ],
                            "state" => "waiting_for_modtool",
                      "tracking_id" => "unique:id:12345:ABC",
                          "subject" => "test",
                             "body" => "lorem ipsum",
                       "content_id" => "123456789",
                     "author_email" => "test@test.com",
                        "author_ip" => nil,
                     "content_type" => "text",
                           "locale" => nil,
                    "response_code" => 0,
                "moderation_status" => 1,
               "moderator_comments" => nil,
                  "moderator_email" => nil,
                 "reporter_comment" => nil,
            "reporter_comment_type" => 0,
                   "reporter_email" => nil,
                      "reporter_ip" => nil,
                      "content_url" => nil,
    "moderation_status_description" => nil,
                      "reason_list" => nil,
                        "parent_id" => nil,
                          "root_id" => nil,
                        "brand_rep" => false,
               "content_time_stamp" => 1523557567328,
              "reporter_time_stamp" => 0,
            "created_in_modtool_at" => 0,
                        "sentiment" => "not_set",
                       "topicality" => "not_set",
                     "content_tags" => nil,
                        "author_id" => "user_handle",
                     "moderator_id" => nil,
                      "reporter_id" => nil,
                             "type" => 0,
                       "time_stamp" => 1523558642129,
                "return_time_stamp" => 1523558642129,
                      "customer_id" => "customer_name",
                 "response_reasons" => []
}

Retrieving Enriched Content

To retrieve content, you perform an http GET operation to the path:

/EndPointClientAxis2/rest/moderation_contents.json

This endpoint accesses a queue of enriched items awaiting download. Once downloaded, the first 100 items will be removed from the queue and no longer available from our API. There is a way to bypass this auto-removal if necessary (read below.)

The following fields are required in your data payload:

Field	Description
seed	The seed is the current timestamp in milliseconds. This value must be less than 5 minutes from the current time, so it must be a new seed with each request.
hash_value	The MD5 hash (you must create on each request) of the secret key (assigned by LiveWorld) concatenated with the seed.
customer_id	The customer ID (constant value) assigned by LiveWorld.
system_id	The system ID (constant value) assigned by LiveWorld.

The following fields are optional:

Field	Description
mark_as_processed	Defaults to true. Set to false to leave this item in the queue, in case you wish to retrieve it again in your next call or if you are also calling the confirmations endpoint to confirm that you have received a content item and it has been processed on your end.

Note: You may retrieve content as often as you need, but requests made too quickly (faster than every 10 seconds or so) may be subject to rate limiting.

Each request returns up to 100 content items.

By default, anytime you retrieve data, the content posts sent will be marked as processed, and will be removed from your queue. You may bypass this and leave those items in your queue by passing an extra parameter, mark_as_processed: false, which is useful during testing.

After successfully retrieving the object, the GET method generates a response code of 200, and the response is a list of content objects (or an empty list, if there are no new items).

The moderation_status field may have these special values, if the item has been enriched using our platform:

• 19: The content item was approved: take whatever “approval” action is appropriate to your platform (such as displaying or highlighting).
• 35: The content item was rejected: take whatever “rejection” action is appropriate to your platform (such as deleting or hiding).

If the item was rejected and a reason was provided by the moderator, this will show up in the moderation_status_description field as a string based on whatever was configured as rejection reasons inside our platform.

Example code to retrieve content:

require 'faraday'
require 'json'
require 'digest/md5'

secret_key = "adsfadfad"
seed = (Time.now.to_f * 1000.0).to_i.to_s

secret_key = "adsfadfad"
seed = (Time.now.to_f * 1000.0).to_i.to_s  # "1580505807859"
hash_value = Digest::MD5.hexdigest("#{secret_key}#{seed}") # "8670f5984e21ef40213af0ee6ebb13e9"

data = {
  seed: seed,
  hash_value: hash_value,
  customer_id: 'customer_name',
  system_id: 'system_name'
}

conn = Faraday.new(url: 'https://modserver-uat.scms.liveworld.com/EndPointClientAxis2/rest/moderation_contents.json')

response = conn.get do |req|
  req.headers['Content-Type'] = 'application/json'
  req.params = data
end

ap JSON.parse(response.body)
[
    [0] {
                                   "id" => "customer_name:system_name:unique:id:12345:ABC",
                            "system_id" => "system_name",
                              "nvpairs" => [
            [0] {
                     "name" => "href",
                    "value" => "http://mywebsite.com/mypost/"
            },
            [1] {
                     "name" => "language_stats",
                    "value" => "danish: 64% \nicelandic: 36% \n"
            }
        ],
                                "state" => "waiting_for_content_source",
                          "tracking_id" => "unique:id:12345:ABC",
                              "subject" => "test",
                                 "body" => "lorem ipsum",
                           "content_id" => "123456789",
                         "author_email" => "test@test.com",
                            "author_ip" => nil,
                         "content_type" => "text",
                               "locale" => "en_US",
                        "response_code" => 0,
                    "moderation_status" => 19,
                   "moderator_comments" => nil,
                      "moderator_email" => nil,
                     "reporter_comment" => nil,
                "reporter_comment_type" => 0,
                       "reporter_email" => nil,
                          "reporter_ip" => nil,
                          "content_url" => nil,
        "moderation_status_description" => nil,
                          "reason_list" => nil,
                            "parent_id" => nil,
                              "root_id" => nil,
                            "brand_rep" => false,
                   "content_time_stamp" => 1523557567000,
                  "reporter_time_stamp" => nil,
                "created_in_modtool_at" => 1523560493000,
                            "sentiment" => "not_set",
                           "topicality" => "not_set",
                         "content_tags" => [
                                    [0] "Test Tag"
                         ],
                            "author_id" => "user_handle",
                         "moderator_id" => nil,
                          "reporter_id" => nil,
                                 "type" => 0,
                           "time_stamp" => 1523560733364,
                    "return_time_stamp" => 1523560733364,
                          "customer_id" => "customer_name",
                     "response_reasons" => []
    }
]

Posting a Confirmation

This endpoint is used in conjunction with the GET moderation_contents.json endpoint called with the mark_as_processed field set to false. After you process the moderated content, you perform an http POST operation to post a confirmation object to the path:

/EndPointClientAxis2/rest/confirmations.json

• After successfully confirming content items, the POST method generates a response code of 200.
• This will mark the content items specified by their tracking_ids as processed.
• Once confirmed, these content items will be removed from the queue and no longer available from our API.
• Upon an error, the body of the response may contain an error message with the tracking_ids of the items that were not confirmed.

The following fields are required in your data payload:

Field	Description
seed	The seed is the current timestamp in milliseconds. This value must be less than 5 minutes from the current time, so it must be a new seed with each request.
hash_value	The MD5 hash (you must create on each request) of the secret key (assigned by LiveWorld) concatenated with the seed.
customer_id	The customer ID (constant value) assigned by LiveWorld.
system_id	The system ID (constant value) assigned by LiveWorld.
tracking_ids	An array containg the tracking_id of each content item you wish to confirm. Ex: ["twitterresource:1398857:1608230879101", "twitterresource:1398859:1608230947515"]

Example code to confirm content:

require 'faraday'
require 'json'
require 'digest/md5'

secret_key = "adsfadfad"
seed = (Time.now.to_f * 1000.0).to_i.to_s  # "1580505807859"
hash_value = Digest::MD5.hexdigest("#{secret_key}#{seed}") # "8670f5984e21ef40213af0ee6ebb13e9"

data = {
  seed: seed,
  hash_value: hash_value,
  customer_id: 'customer_name',
  system_id: 'system_name',
  tracking_ids: ["twitterresource:1398857:1608230879101", "twitterresource:1398859:1608230947515"]
}

conn = Faraday.new(url: 'https://modserver-uat.scms.liveworld.com/EndPointClientAxis2/rest/confirmations.json')

response = conn.post do |req|
  req.headers['Content-Type'] = 'application/json'
  req.params = data
end

ap JSON.parse(response.body)
{
    "success" => [
        [0] "twitterresource:1398857:1608230879101",
        [1] "twitterresource:1398859:1608230947515"
    ],
     "errors" => []
}

Retrieving Published Replies

When our agents add a reply to content that was submitted, these replies go into their own queue. Perform a GET operation to the path:

/EndPointClientAxis2/rest/info_content.json

The following fields are required in your data payload:

Field	Description
seed	The seed is the current timestamp in milliseconds. This value must be less than 5 minutes from the current time, so it must be a new seed with each request.
hash_value	The MD5 hash (you must create on each request) of the secret key (assigned by LiveWorld) concatenated with the seed.
customer_id	The customer ID (constant value) assigned by LiveWorld.
system_id	The system ID (constant value) assigned by LiveWorld.
status	Always enter 3. (This indicates a 3rd party API connection)

The following fields are optional:

Field	Description
mark_as_processed	Defaults to true. Set to false to leave this item in the queue, in case you wish to retrieve it again in your next call.

The result is an array of replies. Each object contains a set of name-value pairs that will allow you to take the reply and post it using your own workflow.

Example code to retrieve replies:

require 'faraday'
require 'json'
require 'digest/md5'

secret_key = "adsfadfad"
seed = (Time.now.to_f * 1000.0).to_i.to_s  # "1580505807859"
hash_value = Digest::MD5.hexdigest("#{secret_key}#{seed}") # "8670f5984e21ef40213af0ee6ebb13e9"


data = {
  seed: seed,
  hash_value: hash_value,
  customer_id: 'customer_name',
  system_id: 'system_name',
  status: 3
}

conn = Faraday.new(url: 'https://modserver-uat.scms.liveworld.com/EndPointClientAxis2/rest/info_content.json')

response = conn.get do |req|
  req.headers['Content-Type'] = 'application/json'
  req.params = data
end

ap JSON.parse(response.body)
[
    [0] {
                "id" => 45,
         "system_id" => 71,
           "nvpairs" => [
            [0] {
                     "name" => "replyType",
                    "value" => "New Tweet",
                "unique_id" => 45,
                       "id" => "45:0"
            },
            [1] {
                     "name" => "body",
                    "value" => "New comment for you to post!",
                "unique_id" => 45,
                       "id" => "45:1"
            },
            [2] {
                     "name" => "Authentication Id",
                    "value" => "11",
                "unique_id" => 45,
                       "id" => "45:2"
            }
        ],
             "state" => "waiting_for_content_source",
        "created_at" => "2018-04-13T16:29:31.044Z",
        "updated_at" => "2018-04-13T16:38:28.767Z",
          "systemId" => "system_name",
        "customerId" => "customer_name"
    }
]

Retrieving Twitter Content Post Metrics (Likes)

To retrieve Twitter Like Metrics, you perform an http GET operation to the path:

/EndPointClientAxis2/rest/twitter_metrics.json

This endpoint accesses a queue of Twitter Metrics collected for the Content Posts in your system that are awaiting download. Once downloaded, the first 100 metrics will be removed from the queue and no longer available from our API. There is a way to bypass this auto-removal if necessary (read below.)

The following fields are required in your data payload:

Field	Description
seed	The seed is the current timestamp in milliseconds. This value must be less than 5 minutes from the current time, so it must be a new seed with each request.
hash_value	The MD5 hash (you must create on each request) of the secret key (assigned by LiveWorld) concatenated with the seed.
customer_id	The customer ID (constant value) assigned by LiveWorld.
system_id	The system ID (constant value) assigned by LiveWorld.

The following fields are optional:

Field	Description
mark_as_processed	Defaults to true. Set to false to leave this item in the queue, in case you wish to retrieve it again in your next call.

Note: You may retrieve metrics as often as you need, but requests made too quickly (faster than every 10 seconds or so) may be subject to rate limiting.

Each request returns up to 100 metrics. The oldest metrics will be returned first.

By default, anytime you retrieve data, the metrics returned will be marked as processed, and will be removed from your queue. You may bypass this and leave those metrics in your queue by passing an extra parameter, mark_as_processed: false, which is useful during testing.

After successfully retrieving the metrics, the GET method generates a response code of 200, and the response is a list of metrics (or an empty list, if there are no new items).

Response Fields:

Field	Description
content_id	Tweet id.
queried_at	Timestamp of when the metric was collected from the Twitter API in seconds (UTC).
content_source	Social media source.
previously_queried_at	Previous timestamp of when the metric was collected from the Twitter API in seconds (UTC). This value will be 0 the first time a metric is collected for a Tweet.
like_count	Current count of likes for the Tweet.
like_delta	The change in like count since the previous Twitter API query. This value will be equal to like_count the first time a metric is collected for a Tweet.

Notes on Metric Collection:

Metrics will appear in the queue for a Tweet:

• the first time metrics are collected for the Tweet
• any time there is a metric delta

Metrics will not appear in the queue for a Tweet:

• if there is no metric delta (the exception to this is a “heartbeat” metric that will be sent once every 24 hours regardless of a metric delta)
• if the Tweet was created more than 2 weeks ago

Example code to retrieve metrics:

require 'faraday'
require 'json'
require 'digest/md5'

secret_key = "adsfadfad"
seed = (Time.now.to_f * 1000.0).to_i.to_s

secret_key = "adsfadfad"
seed = (Time.now.to_f * 1000.0).to_i.to_s  # "1580505807859"
hash_value = Digest::MD5.hexdigest("#{secret_key}#{seed}") # "8670f5984e21ef40213af0ee6ebb13e9"

data = {
  seed: seed,
  hash_value: hash_value,
  customer_id: 'customer_name',
  system_id: 'system_name'
}

conn = Faraday.new(url: 'https://modserver-uat.scms.liveworld.com/EndPointClientAxis2/rest/twitter_metrics.json')

response = conn.get do |req|
  req.headers['Content-Type'] = 'application/json'
  req.params = data
end

ap JSON.parse(response.body)
[
    [ 0] {
                   "content_id" => "1310231913047580672",
                   "queried_at" => 1601403783,
               "content_source" => "Twitter",
        "previously_queried_at" => 1601403701,
                   "like_count" => 59,
                   "like_delta" => 4
    },
    [ 1] {
                   "content_id" => "1310231488689041408",
                   "queried_at" => 1601403783,
               "content_source" => "Twitter",
        "previously_queried_at" => 1601403657,
                   "like_count" => 3577,
                   "like_delta" => 284
    }, ...
]

Production

When you are ready to begin working in production, we will create another set of credentials for you (customer, system, secret key) in our production environment. You can then update your URL to use the production URI:

https://modserver.scms.liveworld.com

For support concerning this documentation, please email our support team:

help@liveworld.com