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 /loudvoice/discussions/discussion.json?
discussion_reference=<discussion_reference>
Read a discussion Update a discussion Delete a discussion
Discussion messages /loudvoice/comments/<discussion_token>/comments.json /loudvoice/discussions/discussion/comments.json?
discussion_reference=<discussion_reference>
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 /loudvoice/authors/author.json?
author_reference=<author_reference>
Read an author Update an author Delete an author
Resource/URI - Author Sessions GET POST PUT DELETE
Author Sessions /loudvoice/authors/sessions.json Create/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 comment
Comment /loudvoice/comments/<comment_token>.json Read a comment Update comment Delete a comment

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.

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/update his 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#,
            }
        }
    }
}
Author
Link the author to your existing user identifier (optional)
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 details
* name
string
Author name, as displayed in the LoudVoice widget. Required for new authors.
Example: John Doe
email
string
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
Session data
expires_in
integer
This parameter defines the number of seconds before the session expires due to inactivity of the user.
Default: 1209600 (14 days)

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#",
            }
        }
    }
}
Key Description
#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

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#",
            }
        }
    }
}
Key Description
#author_token#
string, uuid-v4
This token is received whenever you create a new author.
Example: d86196e7-969d-48ad-8fe1-63a1f074f9b0

Result: the code returned by the API

The API returns one of the following HTTP status code:

  • 201: A new author has been created;
  • 200: An existing author has been 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