Implementing Custom Chat Client


The easiest way to use giosg chat is to embed giosg script on a web page. The script creates visitors, tracks the usage and makes it possible to open a chat in a page without need for programming. If the need is to use giosg chat in some other environment than web, like for example mobile apps, you can use giosg REST API directly and create the UI yourself. You can always use chat widgets to quickly create mobile web view but sometimes that is not enough.

The purpose of this page is to list things to consider and show relevant API calls to create a custom integration from visitor side to giosg chat. The operator side is not considered in this document and it is assumed that the operators use giosg’s own UIs. It is also assumed that the terms used are familiar to you.

Visitor mapping

The first thing you need to figure out is how to map giosg’s visitors to you devices and/or users. When a user is starting his/her first conversation the system should create a giosg visitor. The response contains many fields and the most interesting ones are visitor_id, visitor_secret_id and access_token. You should map visitor_id to your own device or user id.

When a returning user is starting a chat the system should authenticate the visitor.

The access token you receive from the auth call is used for authorization of API calls. So every API call listed in this document requires you to use authorization.

Getting visitor chats

If you want to show chat history for the visitor you can use list visitor chats endpoint. This can be done for example when opening a contact view before actually chat conversation.

Operator online status

You can get initial room operator online status using the online users endpoint. It can be called to get initial value of the online status. Later it is better to start listening realtime changes for room online users.

Creating a chat

Before sending any messages, a chat must be created. There is an API to create a chat. You need to store chat_id to send chat messages and listen to changes in chat. Since the chat is created using a customer integration the chat_type field should be set to external. It is noteworthy that external chat session does not close automatically and should be closed explicitly using end chat endpoint.

Sending messages

When operator sends a message, the visitor can show it by listening to realtime changes in the chat. Visitor can communicate to the operator by using send a chat message endpoint.

Typing status

If you want to show typing status of a visitor you need to change visitor chat status. Check composing_status field.

Realtime changes

Instead of polling changes it is recommended to use Socket API. This is normally done in the client side so for example in the mobile app.