Fetching chat conversations

Overview¶

Giosg platform provides APIs for fetching chat conversations and all related metadata. The first section guides you through which endpoints to use to fetch the chats, chatlogs and metadata. The second part of this guide helps you to setup a notification service to get notified when a chat ends. The third part is covering encryption and decryption of chat conversations in giosg.

Prerequisites¶

Access token:

Get API token for authentication

Api tokens can be created here: Log in to Console → Settings Menu → Company → Access tokens

Once you have obtained your API tokens, define the Authorization HTTP header for all your API requests:

1	`Authorization: Token <api token>`

You should replace the <api_key> with your API tokens

Note

Remember that the api-token is connected to the user that created the token which means that if the user is deleted also the token is invalidated. You can create an extra user and create the token with this user, remember to name the user so that it doesn’t get deleted by mistake e.g “Reporting api-user do not delete”

Generic authorization function that can be used for all endpoints described below¶

You may use below functions for all Javascript and Python calls to handle the authorization and the request

Python

import requests

GIOSG_SERVICE_BASE_URL = "https://service.giosg.com"
API_TOKEN = "<giosg account token>"
organization_id = "<uuid>"

def get_with_auth(url_path):
    url = "{base_domain}{url_path}".format(
        base_domain=GIOSG_SERVICE_BASE_URL,
        url_path=url_path
    )
    response = requests.get(url, headers={
        "Content-Type": "application/json",
        "Authorization": "Token {}".format(API_TOKEN)
    })
    response.raise_for_status()
    return response.json()

Javascript

const orgId = '<org_id>'
const apiToken = '<Api_token>'

async function getWithAuthorization(url = "") {
    const response = await fetch(url, {
        method: "GET",
        headers: {
            "Content-Type": "application/json",
            Authorization: `Token ${apiToken}`,
        },
    });
    return await response.json();
}

Fetching the chats¶

First you need to decide which chat conversations you want to fetch. This could be all organization's chats or chats for specific giosg Rooms.

First you need to decide which chat conversations you want to fetch.
This could be all organization's chats or chats for specific giosg Room. In the below examples the chats are listed for the whole organization. Endpoint https://service.giosg.com/api/v5/orgs/<organization_id>/owned_chats lists all the chats for the organization.

Please check List organization's owned chats API for more information what filters you can apply when querying the chats.

Python

organization_id = "<uuid>"

def get_chats():
    return get_with_auth("/api/v5/orgs/{}/owned_chats".format(organization_id))

print(get_chats())

Javascript

// Fetch example to list all chats for a organization
getWithAuthorization(`https://service.giosg.com/api/v5/orgs/${orgId}/owned_chats`).then(
    (data) => {
        console.log(data);
    }
);

Fetching the chats per room¶

You can order the chats to show from newest to oldest and only include chats with messages by adding query parameters: ?ordering=-created_at&has_user_messages=true&has_visitor_messages=true.

See List chats at a room API

Fetching open chats and ending them¶

If you are using external type of chats which are not ended automatically you might end up in old open chats. To handle these ghost chats you can use the APIs to fetch and end them. First you have to specify what is the time frame you want to wait before ending a chat (for example 1 week or 1 month).

You can fetch open chats by using these query parameters ?ordering=-created_at&is_ended=false.

Then you can check the updated_at field to check when the chat has been updated. If it has not been updated in a time frame you've specified you can end the chat.

See List chats at a room API and List organization's owned chats API.

Listing the messages for a chat¶

When you have all the chats listed you can get the messages by looping through the result from the owned chats response for every chat id using this endpoint: /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/messages

See List chat messages API

Python

organization_id = "<uuid>"
chat_id = "<chat id>"

def get_messages(chat_id):
    return get_with_auth("/api/v5/orgs/{}/owned_chats/{}/messages".format(organization_id, chat_id))

print(get_messages(chat_id))

Javascript

//Fetch example to list all messages in a chat
const chat_id = '<chat_id>'

getWithAuthorization(`https://service.giosg.com/api/v5/orgs/${orgId}/owned_chats/${chat_id}/messages`).then(
    (data) => {
        console.log(data);
    }
);

Memberships¶

If you need to know who has been involved in the chat you can get the memberships for each chat with this endpoint: /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/memberships

See Chat memberships API

Hint: Store the member id for the visitor if you use visitorvarialbes so that you can use it for fetching the variables set in the chat.

Python

organization_id = "<uuid>"
chat_id = "<chat id>"

def get_memberships(chat_id):
    return get_with_auth("/api/v5/orgs/{}/owned_chats/{}/memberships".format(organization_id, chat_id))

print(get_memberships(chat_id))

Javascript

//Fetch example to list memberships in a chat
const chat_id = '<chat_id>'

getWithAuthorization(`https://service.giosg.com/api/v5/orgs/${orgId}/owned_chats/${chat_id}/memberships`).then(
    (data) => {
        console.log(data);
    }
);

Fetch visitor data for a chat¶

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/visitors/<visitor_id>/variables

See List chat visitor variables API

The visitor id you need to pass in this api-call stored chat membership call can be used used here

Python

organization_id = "<uuid>"
chat_id = "<chat id>"
visitor_id = "<visitor id>"

def get_visitor_variables(chat_id, visitor_id):
    return get_with_auth("/api/v5/orgs/{}/owned_chats/{}/visitors/{}/variables".format(organization_id, chat_id, visitor_id))

print(get_visitor_variables(chat_id, visitor_id))

Javascript

//Fetch example to list memberships in a chat
const chat_id = '<chat_id>'
const visitor_id = 'visitor_id'

getWithAuthorization(`https://service.giosg.com/api/v5/orgs/${orgId}/owned_chats/${chat_id}/visitors/${visitor_id}/variables`).then(
    (data) => {
        console.log(data);
    }
);

Listing tags used in a chat¶

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/tags

See List tags of a chat API.

Python

organization_id = "<uuid>"
chat_id = "<chat id>"

def get_tags(chat_id):
    return get_with_auth("/api/v5/orgs/{}/owned_chats/{}/tags".format(organization_id, chat_id))

print(get_tags(chat_id))

Javascript

const chat_id = "<chatid>"

getWithAuthorization(`https://service.giosg.com/api/v5/orgs/${orgId}/owned_chats/${chat_id}/tags`).then(
    (data) => {
        console.log(data);
    }
);

Get notifications about an ended chat (optional)¶

If you would like to get a notification every time a chat ends and then fetch the messages for it you could configure a new Giosg App from "Settings" -> "Apps" -> "Add new app".

Only thing you need to configure in this app is the basic information like name, description, the app trigger url (This is the url of your server which gets called) and the trigger event that in your case would be "Run on background when chat ends" (see below screenshot).

When the app is configured and installed you will get an http get request to the configured url.

Giosg Apps

Giosg App triggers

Trigger setup¶

Screenshot

App trigger setup

Conclusion¶

In the first part of the tutorial we showed you what endpoints and rest-api calls you can use to fetch chats and metadata connected to them. The second part guided you through the process of adding notifications about ended chats.

Endpoins used in this tutorial¶

List organization's owned chats API

List chats at a room API

List chat messages API

Chat memberships API

List chat visitor variables API

List tags of a chat API