LoudVoice API \ Author Sessions \ Start session

Resource/URI - Discussions GET POST PUT DELETE
Discussions /loudvoice/discussions.json List all discussions Create a discussion – –
Discussion /loudvoice/discussions/<discussion_token>.json Read a discussion – Update a discussion Delete a discussion
Discussion messages /loudvoice/comments/<discussion_token>/comments.json Read discussion comments – – –
Resource/URI - Authors GET POST PUT DELETE
Authors /loudvoice/authors.json List all authors Create an author – –
Author /loudvoice/authors/<author_token>.json Read an author – Update an author Delete an author
Resource/URI - Author Sessions GET POST PUT DELETE
Author Sessions /loudvoice/authors/sessions.json List all sessions – Create or update a session –
Author Session /loudvoice/authors/sessions/<session_token>.json – – – Delete a session
Resource/URI - Comments GET POST PUT DELETE
Comments /loudvoice/comments.json List all comments Create a comment – –
Comment /loudvoice/comments/<comment_token>.json Read a comment – Update a comment Delete a comment
Resource/URI - Votes GET POST PUT DELETE
Votes /loudvoice/votes.json List all
votes 		– – –
Vote /loudvoice/votes/comments/<comment_token>/authors/<author_token>.json Read a vote – Cast a vote Delete a vote

Workflow

Send a PUT request to the endpoint /loudvoice/authors/sessions.<format> in order to start a new session. This endpoint supports different data formats corresponding to different use cases.

Use case 1/3 · Start a session and automatically create/update the author.

This is the most common scenario. You simply send over the user information from your database and LoudVoice will automatically synchronize the user's details and create a new or update the existing session. 

{
  "request": {
    "author_session": {
      "author": {
        "author_reference": "#author_reference#",
        "allow_create_new": #allow_create_new#,
        "name": "#name#",
        "email": "#email#",
        "description": "#description#",
        "picture_url": "#picture_url#",
        "website_url": "#website_url#"
      },
      "session": {
        "expires_in": #expires_in#
      }
    }
  }
}
Key Description
Author Reference
author_reference
string 		Your custom reference for this author, e.g. the unique id of the user in your system. If this value is specified, LoudVoice first tries to load the corresponding author. If no author can be found, a new one will be created on the fly.
Example : USER-123456
allow_create_new
boolean 		If you specify an author_reference, LoudVoice either updates or creates the author. If you don't want new authors to be created automatically, then use this flag to disable the creation. In this case you can still create references using the API.
Default : true
Author Metadata
* name
string 		Author name, as displayed in the LoudVoice widget. Required for new authors.
Example: John Doe
email
string, email 		Author email address
Example: john.doe@example.com
description
string 		Author description
Example: A writer by day and a reader by night
picture_url
string, uri 		The fully qualified URL of the author's avatar
Example: https://www.example.com/john/avatar.png
website_url
string, uri
 The fully qualified URL of the author's website
Example: http://www.example.com/
Session Metadata
expires_in
integer 		This value defines the number of seconds before the session expires due to inactivity of the user.
Default: 1209600 (14 days)

Use case 2/3 · Start a session for a user that has logged in with Social Login.

If you have implemented our Social Login service then you will obtain an identity_token for each user that logs in with a social network account. This token can then be used to start a new session. 

{
    "request": {
        "author_session": {
            "author": {
                "identity_token": "#identity_token#",
            },
            "session": {
                "expires_in": #expires_in#
            }
        }
    }
}
Author
#identity_token#
string, uuid-v4 		This token is received whenever a user logs in with a social network using our Social Login service.
Example: d86196e7-969d-48ad-8fe1-63a1f074f9b0
Session
expires_in
integer 		This value defines the number of seconds before the session expires due to inactivity of the user.
Default: 1209600 (14 days)

Use case 3/3 · Start a session for a previously created author.

If you have created the author by using the LoudVoice API, then you can simply use the received author_token to start a new session for that author. 

{
    "request": {
        "author_session": {
            "author": {
                "author_token": "#author_token#",
            },
            "session": {
                "expires_in": #expires_in#
            }
        }
    }
}
Author
#author_token#
string, uuid-v4 		This token is received whenever you create a new author.
Example: d86196e7-969d-48ad-8fe1-63a1f074f9b0
Session
expires_in
integer 		This value defines the number of seconds before the session expires due to inactivity of the user.
Default: 1209600 (14 days)

Result: the code returned by the API

The API returns one of the following HTTP status codes:

  • 201: A new author was created;
  • 200: An existing author was found and updated;
  • xxx: An error occured while processing the request.

Example Resultset

{
  "response": {
    "request": {
      "date": "Mon, 26 Mar 2018 17:35:43  0200",
      "resource": "/loudvoice/authors/sessions.json",
      "status": {
        "flag": "success",
        "code": 200,
        "info": "Your request has been processed successfully"
      }
    },
    "result": {
      "data": {
        "author_session": {
          "author_session_token": "27641d04-ff73-4b03-9bfd-ba28e781c9be",
          "date_creation": "Mon, 26 Mar 2018 17:33:12  0200",
          "date_last_update": null,
          "date_expiration": "Mon, 09 Apr 2018 17:33:12  0200",
          "expires_in": 1209600,
          "author": {
            "author_token": "875b8930-eff8-4c2d-a594-3f4cc4ed4d0d",
            "author_reference": "122311",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "description": "A writer by day and a reader by night",
            "picture_url": "https://www.example.com/john/avatar.png",
            "website_url": "https://www.example.com/",
            "num_comments": 0,
            "date_last_comment": null,
            "date_creation": "Mon, 26 Mar 2018 17:33:12  0200",
            "date_last_update": null
          }
        }
      }
    }
  }
}

User Contributed Notes