NAV

Using the public API

Authentication

All the public API endpoint requests (as well as subscribing to real-time channels via Socket API) require an access token, as described in the Authorization section. You also need to determine the unique ID for the visitor.

Authenticate a new visitor

An example request

POST https://service.giosg.com/api/v5/public/orgs/e6a08f51-c250-4074-847b-58d444dbbeb1/auth
{
    "visitor_secret_id": null,
    "visitor_global_id": null
}

An example response

{
    "visitor_id": "8a60b202474547dbb8ce19737e4c166f",
    "visitor_global_id": "a112586d51354fcbbcb9d55daee36e76",
    "visitor_secret_id": "2bc12b9cb90d4faf92141c45d560164584ad030d78cb06f91e",
    "organization_id": "e6a08f51-c250-4074-847b-58d444dbbeb1",
    "socket_url": "https://messagerouter.giosg.com/003/2/router",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.we2snuuhq-cnPk-GMJVoBhyZ7ZKPa95Qxe_3VkEaf_E",
    "expires_at": "2015-12-22T11:25:30.595Z",
    "expires_in": 1800
}

When a new visitor starts using the public API endpoints, you need retrieve the required identity and access token by making the following request:

POST /api/v5/public/orgs/<organization_id>/auth

You need to accept a JSON response with HTTP request headers.

The <organization_id> must be the ID of your organization account. You can get this on your giosg account settings.

When authenticating a new user, the payload may be an object with attribute(s) visitor_secret_id with value null and/or visitor_global_id with value null. You may even omit these attributes and POST just an empty payload object.

The response is an object with the following attributes:

Attribute Type Description
visitor_id string Your organization-specific public identifier. It is specific only to the context of the related organization (<organization_id>). For other organizations, you should make another request. This identifier can be sent to anyone.
visitor_global_id string Your global public identifier. It identifies you over all organizations. It is used to keep your identity anonymous, and is therefore indistinguishable from your visitor_id.
visitor_secret_id string Your secret identifier. You should store this to a local storage! Do not share this secret to anyone! Otherwise anyone can access your information or impersonate you.
organization_id ID ID of the organization to which this information is specific.
socket_url string URL to which any socket connection should be made if you want to subscribe to real-time channels.
access_token string The access token that you need to use to authorize access to any other public HTTP API endpoints or real-time channels.
expires_at date/time When this information (especially the access token) expires. You should renew this information before it expires.
expires_in integer After how many seconds this information (especially the access token) expires. You should renew this information before it expires. Useful for scheduling a timer for renewing the authentication.

In addition to the visitor_secret_id, you may also temporarily persist other information, such as your visitor_id, visitor_global_id and access_token. This may be useful e.g. for faster application startup. However, only store the most recent information received from the server.

Authenticate a returning visitor

An example request

POST https://service.giosg.com/api/v5/public/orgs/e6a08f51-c250-4074-847b-58d444dbbeb1/auth
{
    "visitor_secret_id": "a112586d51354fcbbcb9d55daee36e76",
    "visitor_global_id": "jljf7pdlotuo57fv7uaafjebriueguir42tx75c4rhds3yym"
}

An example response

{
    "visitor_id": "8a60b202474547dbb8ce19737e4c166f",
    "visitor_global_id": "jljf7pdlotuo57fv7uaafjebriueguir42tx75c4rhds3yym",
    "visitor_secret_id": "a112586d51354fcbbcb9d55daee36e76",
    "organization_id": "e6a08f51-c250-4074-847b-58d444dbbeb1",
    "socket_url": "https://messagerouter.giosg.com/004/1/router",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.LwimMJA3puF3ioGeS-tfczR3370GXBZMIL-bdpu4hOU",
    "expires_at": "2015-12-22T15:03:12.901Z",
    "expires_in": 1800
}

After the very first authentication as a new visitor, you usually want to renew your authentication. For example:

Re-authentication is done to the same endpoint than the first authentication:

POST /api/v5/public/orgs/<organization_id>/auth

However, you should send your visitor_secret_id and visitor_global_id, stored to your client, as an attribute of the payload object.

The response is similar than when authenticating as a new visitor. You should again persist the returned visitor_secret_id, an optionally other information.

Authorization

An example HTTP request header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.LwimMJA3puF3ioGeS-tfczR3370GXBZMIL-bdpu4hOU

You need to provide a valid access token on your Authorization HTTP header for all the public API requests (except when authenticating).

Authorization: Bearer <access_token>

Accept Header

You also need to define that you accept JSON-formatted responses by providing the Accept HTTP header:

Accept: application/json

Alternatively, if you are unable to customize headers, you may add format=json GET parameter.

Resource identifiers

Unless stated otherwise, all the resources in the system are identified with a Universally Unique Identifier (UUID). It is always represented as a string ID, in lower case and including dashes.

For example: 9ae65e7d-56c5-11e5-af8d-6c4008c08dfe

Paginated collections

An example of a JSON response with a paginated collection

{
  "next": "https://service.giosg.com/api/v5/examples?cursor=da965a3ea0164c8ab8baef1d4654e2d3",
  "previous": null,
  "results": [
    {"name": "Example Resource 1"},
    {"name": "Example Resource 2"},
    {"name": "Example Resource 3"},
    {"name": "Example Resource 4"},
    {"name": "Example Resource 5"}
  ]
}

Some of the API endpoints return paginated collections. That means that for large collections of resources, not all resources are returned in a single response, but the response contains an URL that can be used to fetch the next chunk (page) of results.

Paginated collections are objects with the following attributes.

Attribute Type Description
next string Full URL for requesting the next page. This is null if the current page is the last page.
previous string Full URL for requesting the previous page. This is null if the current page is the first page
results array of objects The list containing the result resources for the current page. Each item is an object whose attributes depend on the returned resource type.

Ordering collections

A paginated collection can usually be ordered by using an ordering attribute.

The allowed sorting criteria depends on the endpoint, but the basic usage is always the same. You have an allowed set of sorting attributes, e.g. first_name, last_name and created_at. You may then choose the primary sorting key and any secondary sorting keys with a comma-separated string, e.g. last_name,first_name.

Any sorting order is ascending by default, but may be reverted to descending order by prefixing with a minus (-) character, e.g. -created_at or last_name,-created_at.

Date/time format

Unless stated otherwise, all the date/times returned by API endpoints are ISO-8601 strings with format YYYY-MM-DDTHH:MM:SS.MSSZ, for example: 2015-08-31T16:32:17.879Z. Also, any date/time URL parameters or attributes send as a request payload accept this same format.

Unless stated otherwise, the times are expressed in UTC timezone!

Rooms API

Rooms

The room resource that the visitor can access has the following attributes.

Attribute Type Description
id ID The unique identifier of this room
display_name string Name of the room
language_code string Language of this room in ISO 639-1 code, or null if undefined.
is_online boolean Are there any users online in this room that the the visitor can chat with
brand object The brand used in this room as an object. Contains almost same attributes as in HTTP API section without organization specific information. null if default.

Retrieve room details

Get a single room object by its ID. This may be a shared room.

GET https://service.giosg.com/api/v5/public/orgs/<organization_id>/rooms/<room_id>

Retrieve room’s brand details

Get a single room brand object used in room by room’s ID. This may be a shared room.

GET https://service.giosg.com/api/v5/public/orgs/<organization_id>/rooms/<room_id>/brand

Returns 404 if the organization has not defined brand for the room.

Online users in a Room

Visitors can fetch a collection of online users in a room

Attribute Type Description
id ID Unique identifier
public_name string The name of the user as it would be displayed for the visitor. This is user’s alias if they have one, otherwise it is their real name.
avatar object The avatar of the user as an object. It contains attributes idand url. This is null if the user has no avatar.

Retrieve a list of online users in a room

GET https://service.giosg.com/api/v5/public/orgs/<organization_id>/rooms/<room_id>/online_users

Chat API

Chats

A chat represents a single conversation. In practice, there is usually zero or one visitor member and an arbitrary number of user (“operator”) members.

A chat has the following attributes:

Attribute Type Editable Description
id ID read-only Unique identifier for the chat
token string read-only A legacy Giosg-signed encoded unique string for the chat
created_at date/time read-only When the chat conversation started
updated_at date/time read-only When the chat conversation was last time updated
is_waiting boolean read-only This is true for new chats that are started by a visitor and they require a response by a user (and the chat has not ended yet). Otherwise this is false.
waiting_started_at date/time read-only When the chat became waiting. This is the timestamp when the is_waiting attribute changed true. It does not change when the is_waiting becomes false. Default value for this is null and it stays so if the chat never became waiting.
is_ended boolean optional Whether or not the chat has ended. Once ended, messages and members of the chat cannot be altered any more. Updating this to true immediately and permanently locks the chat. Defaults to false.
ended_at date/time read-only When the chat conversation ended (or null if not yet ended)
room_id ID read-only ID of the room in which the chat occurred
is_autosuggested boolean read-only Whether or not the chat started with an autosuggestion
is_encrypted boolean read-only Whether or not the messages of this chat are stored encrypted.
message_count integer read-only How many messages there are in total in this chat at the moment. NOTE that this only includes messages with type msg, so this does not include autosuggestions, or join/leave messages.
user_message_count integer read-only How many messages there were by operator in this chat
visitor_message_count integer read-only How many messages there were by visitor in this chat
member_count integer read-only How many people (visitor and users) have attended or sent messages to this chat.
user_member_count integer read-only How many users have sent at least one message to the chat.
visitor_member_count integer read-only How many visitors have attended this chat.
present_participant_count integer read-only How many people (visitor and users) there are currently participating and present at this chat.
present_user_participant_count integer read-only How many users there are currently participating and present at this chat.
present_visitor_participant_count integer read-only How many visitor there are currently participating and present at this chat
visitor_wait_time float read_only How many seconds the visitor had to wait for an answer to the first sent message. This is null if the visitor has not got an answer yet.

List visitor’s chats

You can get a list of all chats of the visitor.

GET https://service.giosg.com/api/v5/public/visitors/cdca48c949a5966bf8aa53ff79452b60/chats
{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "b8126675-e874-11e7-8623-8c85901fa51f",
      "room_id": "b13abd9c-c301-11e7-8e89-8c85901fa51f",
      "room_organization_id": "b084711c-c301-11e7-ad3d-8c85901fa51f",
      "created_at": "2017-12-27T06:36:06.015Z",
      "is_waiting": false,
      "waiting_started_at": null,
      "ended_at": null,
      "updated_at": "2017-12-27T06:36:06.062Z",
      "is_encrypted": false,
      "is_autosuggested": true,
      "is_ended": false,
      "message_count": 0,
      "user_message_count": 0,
      "visitor_message_count": 0,
      "present_participant_count": 0,
      "present_user_participant_count": 0,
      "present_visitor_participant_count": 0,
      "member_count": 1,
      "user_member_count": 0,
      "visitor_member_count": 1,
      "legacy_id": "vnzv4klw3n2h3i5fauaafoasmz26q5ar46dchdefsap2khym",
      "legacy_room_id": "ck4bs2fhokfkm3k5waaafmj2xwomgair46hitdefsap2khym"
    }
  ]
}

GET /api/v5/public/visitors/<visitor_id>/chats

This API endpoint returns a paginated collection. They are sorted by the creation time of the chats, in ascending order.

Retrieve visitor’s chat

Get a single chat object by its ID.

GET /api/v5/public/visitors/<visitor_id>/chats/<chat_id>

Create a new chat

Start a new chat with a visitor in the given room.

POST /api/v5/public/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>/chats

The visitor will automatically be added as member of the chat by creating a chat membership resource. This endpoint will attempt to get an existing open chat in this room where the visitor is already a member, instead of creating a new chat. This will update visitor’s is_participating status.

You may want to start chat with a specific user or users. This endpoint can take user_member_ids list as payload. This will try to find existing chat for visitor and all the given users. user_member_ids list must contain only ID’s of users who have access to this room.

This endpoint will return:

End a chat

Example request that closes a chat

PUT https://service.giosg.com/api/v5/public/visitors/bed3221e-879e-43df-8d0e-d63f8c1f012d/chats/100067c3-2dda-4343-b403-1bb6caf1d14d

Example payload

{
    "is_ended": true
}

Conversations between users and visitors usually end automatically when no one has sent any messages to the chat after a certain time. However, visitor may also explicitly end the chat conversation.

Once ended, no new chat messages or chat memberships can be added to the chat anymore! Chat cannot be reopened. You should create a new chat if you want to continue conversation with the other person.

You can end explicitly a chat in which you are a member by updating the is_ended attribute to true:

PUT /api/v5/public/visitors/<visitor_id>/chats/<chat_id>

or

PATCH /api/v5/public/visitors/<visitor_id>/chats/<chat_id>

You need to define the is_ended attribute with value true as a payload.

Chat memberships

The visitor and each user who has participated to a chat is added as a chat membership to the chat.

Attribute Format Editable Description
member_id ID/string read-only ID of the user or visitor being present at the chat.
member_type string read-only Either visitor or user.
member_public_name string read-only The name of the user/visitor as it would be displayed for the visitor. This is user’s alias if they have one, otherwise it is their real name. For visitors, this is any custom username (e.g. set by API data) or null
member_avatar object read-only If the user/visitor has an avatar image, then this is is an object with id and url attributes. Otherwise this is null.
chat_id ID read-only ID of the chat.
created_at date/time read-only When the user/visitor was added as a chat member.
updated_at date/time read-only When the this membership was updated.
message_count integer read-only How many messages the user/visitor has sent to the chat. This may be 0, e.g. when operator has joined the chat but has not sent any message yet.
is_participating boolean required Whether or not the user/visitor has the chat “open”. In practise this reflects the state of the chat window. When the user/visitor closes the chat window, it is supposed that he is no more participating the chat (but the membership still remains)
is_present boolean read-only Whether or not the user/visitor is currently present. Equals the is_present attribute of the member.
composing_status string required One of the following: idle, typing, typed. The typing status will be automatically downgraded to typed if the composing status has not been refreshed for a while.

List chat memberships

GET https://service.giosg.com/api/v5/public/visitors/3b90ef7c93484af4965a79ace7bc9a62/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/memberships
{
  "next": "https://service.giosg.com/api/v5/public/visitors/3b90ef7c93484af4965a79ace7bc9a62/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/memberships?cursor=45d9e7358e1249c491b4fa0212310f55",
  "previous": null,
  "results": [
    {
      "member_id": "378ad5a0-bb89-481b-978b-4268b368cfef",
      "member_type": "user",
      "member_public_name": "Customer Service",
      "member_avatar": {
        "id": "7f9cb877-0fd9-4c27-90b0-bd4c2842da3d",
        "url": "http://www.example.com/avatar/5ef1a0ef-8b61-4473-8706-9669e30b47e6.jpg"
      },
      "chat_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "created_at": "2015-02-13T11:31:36.042",
      "is_participating": true,
      "is_present": true,
      "composing_status": "idle",
      "message_count": 8
    },
    {
      "member_id": "3b90ef7c93484af4965a79ace7bc9a62",
      "member_type": "visitor",
      "member_public_name": null,
      "member_avatar": null,
      "chat_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "created_at": "2015-02-13T12:14:34.154",
      "is_participating": true,
      "is_present": true,
      "composing_status": "typing",
      "message_count": 7
    }
  ]
}

You may get a paginated collection of all memberships of a chat.

GET /api/v5/public/visitors/<visitor_id>/chats/<chat_id>/memberships

Returns 404 if the chat is not one of the visitor’s chats.

List chat memberships of a visitor

As an alternative to list a visitor’s chats, you can also list a visitor’s chat memberships as a paginated collection. This includes each chat membership object that represents the visitor in each of his chats.

GET /api/v5/public/visitors/<visitor_id>/chat_memberships

Change visitor chat status

Example request for making the visitor typing at the chat

PUT /api/v5/public/visitors/5cd16aaf35d6488094a5f160afa29767/chat_memberships/e9f4c403-0d0f-4bb8-9883-8f2eb5c9079b

Example request payload

{
  "is_participating": true,
  "composing_status": "typing"
}

The participation status should be refreshed when the visitor opens or closes a chat. In addition, you should frequently notify the backend about the composing status of the visitor. For example, you should make a request when the visitor starts typing a message for the chat (and more requests frequently if the visitor keeps typing, stops typing or clears the composition area).

You can change the chat status of the visitor:

PUT https://service.giosg.com/api/v5/public/visitors/<visitor_id>/chat_memberships/<chat_id>

Chat messages

Chat consists of a number of messages. Some of them are actual typed messages from either operator or visitor, and some of them are automatically added events about the chat, especially when an operator has joined or leaved the chat.

Attribute Type Editable Description
id ID read-only Unique identifier for the message
type string required Whether the message is an actual message (msg), autosuggest (autosuggest), a join event (join), a leave event (leave), an action event (action), or a message from system (system). When POSTing a message, this can be set to msg, action, or system.
chat_id ID read-only ID of the chat.
created_at date/time read-only When the message was sent
sender_type string required Whether the sender is operator (user), visitor (visitor), or triggered by rule (rule). When POSTing a new message with these endpoints, this will accept only visitor and rule as sender types.
sender_id ID/string optional Identifier for the sender. If the sender is a user, then this is the user’s ID. For visitor this is an unique string. If the sender was a rule, it is the ID of the rule which triggered this message.
sender_public_name string read-only A display name for the sender as the visitor would see the him. This value might change if the sender type was rule. Note: If the message_type is rule, then this field is required.
sender_avatar object read-only If the sender has an avatar image, then this is an object with id and url attributes. Otherwise this is null.
message string required Content text of the message. The maximum length is 2000 characters. This will always be the decrypted if the decryption key is still being stored at the server. Otherwise, this will be null if the server cannot decrypt the message any more. In cases where the chat message’s type was action, this can be either the text of the chosen attachment action or title of the attachment. If neither are provided, this is null. Note: If the message’s type is action, then this field is read-only.
is_encrypted boolean read-only Whether or not the message is stored encrypted. If true and message is null, it means that the message cannot be decrypted anymore.
attachments list of objects read-only List of chat message attachments for this chat message. These represent rich or interactive content provided in this message.
response_to_message_id ID read-only Unique identifier of the message this was a response to. null if it wasn’t a response.
response_to_attachment_id ID read-only Unique identifier of the chosen attachment this was a response to. null if it wasn’t a response.
response_to_attachment object read-only The chosen attachment of the response. null if it wasn’t a response.
response_to_action_id ID read-only Unique identifier of the chosen attachment action this was a response to. null if it wasn’t a response.
response_to_action object read-only The chosen attachment action of the response. null if it wasn’t a response.
response_value string read-only The chosen attachment value of the response. If the chosen attachment was an action, then this is the value of the action. Otherwise this may be the attachment’s title_link_url, image_url, image_link_url or a link provided in text field (Markdown). null if it wasn’t a response.

List chat messages

GET https://service.giosg.com/api/v5/public/visitors/f7a5a3b83d2e40dfb0dedd6c0e284214/chats/450fc49e-277e-4dd6-af0f-6e9dcb885b09/messages
{
  "next": "https://service.giosg.com/api/v5/public/visitors/f7a5a3b83d2e40dfb0dedd6c0e284214/chats/450fc49e-277e-4dd6-af0f-6e9dcb885b09/messages?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
      "type": "autosuggest",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "created_at": "2015-02-13T11:30:03.045",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "message": "How may I help you?",
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    },
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "type": "msg",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "created_at": "2015-02-13T11:31:36.042",
      "sender_type": "visitor",
      "sender_id": "f7a5a3b83d2e40dfb0dedd6c0e284214",
      "sender_public_name": null,
      "message": "Yes, actually you could.",
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    },
    {
      "id": "a3a3b8ed-7336-431a-8350-8f5be471a09e",
      "type": "join",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "created_at": "2015-02-13T11:31:38.123",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    },
    {
      "id": "487a4dce-503a-43d0-bd62-1e1a7582c93b",
      "type": "msg",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "created_at": "2015-02-13T11:32:01.654",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "message": "OK, what do you want to know?",
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    }
  ]
}

Get the collection of all chat messages in the given chat.

GET /api/v5/public/visitors/<visitor_id>/chats/<chat_id>/messages

Send a chat message

POST https://service.giosg.com/api/v5/public/visitors/be82243cf82540c49a629543022a3de2/chats/4a591004-4c18-4260-bbb4-fc9f9f9a048d/messages

Example request payload for normal message

{
  "type": "msg",
  "message": "Thank you for your help!"
}

Send a new chat message with type msg to a chat.

POST /api/v5/public/visitors/<visitor_id>/chats/<chat_id>/messages

Returns 404 if the chat is not one of the visitor’s chats or the visitor does not exist. Returns 403 if the visitor has been banned.

The sender_type is automatically set to visitor and sender_id is set to <visitor_id>.

If this is the first message with type msg in the chat, then its is_waiting attribute is automatically set to true. (This only affects the authenticated users)

POST https://service.giosg.com/api/v5/public/visitors/be82243cf82540c49a629543022a3de2/chats/4a591004-4c18-4260-bbb4-fc9f9f9a048d/messages

Example request payload for system message

{
  "type": "system",
  "sender_id": "f8c932ab-0b0f-11e8-91b8-f45c89c72de3",
  "sender_type": "rule",
  "sender_public_name": "Customer service",
  "message": "There is some traffic in our system"
}

Send a new chat message with type system to a chat.

POST /api/v5/public/visitors/<visitor_id>/chats/<chat_id>/messages

Returns 404 if the chat is not one of the visitor’s chats or the visitor does not exist. Returns 403 if the visitor has been banned.

The required parameters for this endpoint are: - type, this has to be system. - sender_id, this should be the ID of the rule which triggered this message. - sender_type, this has to be rule. - sender_public_name, this has to match rule action’s send message’s sender_public_name field. Note: This value is only obtainable from settings page currently. - message, this has to match rule action’s value. Note: This is only obtainable from settings page currently.

This endpoint returns 400 if: - there is no real Rule with the given sender_id. - type and sender_type are not both in correct formats. - the rule action’s sender_public_name and given sender_public_name differ. - the rule action’s value and given message differ.

Reply to chat message attachment

There are some additional fields that need to be included in payload when the visitor reacts to the attachment. These fields are:

Attribute Type Editable Description
type string required Type of this message. This should be action this case.
response_to_message_id ID required ID of the original message with attachments which the visitor reacted.
response_to_attachment_id ID required ID of the attachment which the visitor reacted.
response_to_action_id ID optional ID of the attachment action which the visitor reacted. In cases where the attachment does not have this field, it can be neglected.
response_value string required String representation of the attachment field (title_link_url, image_url, image_link_url or a link inside markdown) to which the visitor reacted. This should be omitted in cases where the visitor reacted to an action. Note: If the chosen attachment was an action, then this field is read-only.

Note: In cases where visitor sends a message of type action, the message field is NOT required!

POST https://service.giosg.com/api/v5/public/visitors/be82243cf82540c49a629543022a3de2/chats/4a591004-4c18-4260-bbb4-fc9f9f9a048d/messages

Example request payload

{
  "type": "action",
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "57931251-4b4d-11e7-bf24-f45c89c72de3",
  "response_value": "http://running-shoes.com/nike-free-rn"
}

Example response

{
  "id": "899042d4-4aaf-11e7-899c-f45c89c72de3",
  "type": "action",
  "chat_id": "4a591004-4c18-4260-bbb4-fc9f9f9a048d",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "visitor",
  "sender_id": "be82243cf82540c49a629543022a3de2",
  "sender_public_name": null,
  "sender_name": null,
  "message": "Nike Free RN",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "attachments": [],
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "57931251-4b4d-11e7-bf24-f45c89c72de3",
  "response_to_attachment": {
    "id": "57931251-4b4d-11e7-bf24-f45c89c72de3",
    "title": "Nike Free RN",
    "title_link_url": null,
    "text": "Women's running shoe, 100€",
    "image_url": "http://s3.amazon.com/fjifew932mlfs.png",
    "image_link_url": "http://running-shoes.com/nike-free-rn",
    "link_target": "_blank"
  },
  "response_to_action_id": null,
  "response_to_action": null,
  "response_value": "http://running-shoes.com/nike-free-rn"
}

Send a new chat message with type action to a chat.

POST /api/v5/public/visitors/<visitor_id>/chats/<chat_id>/messages

The basic concept for this is as same as sending a new chat message to the chat with different payload for type field. Note that you must also include the rest of the required fields.

Chat tags

List all tags used on visitor’s chat. This API returns only hashed versions of tag names.

Attribute Format Editable Description
hashed_name string read-only Hash of the tag name added to visitor’s chat.
chat_session_id ID/string read-only ID of chat session this tag belongs to.
room_id ID/string read-only ID of the room where chat session belongs to.
created_at date/time read-only When the tag was added to chat.

List chat tags

GET https://service.giosg.com/api/v5/public/visitors/3b90ef7c93484af4965a79ace7bc9a62/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/tags
{
  "next": "https://service.giosg.com/api/v5/public/visitors/3b90ef7c93484af4965a79ace7bc9a62/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/tags?cursor=45d9e7358e1249c491b4fa0212310f55",
  "previous": null,
  "results": [
    {
      "hashed_name": "ce5116c10b7580a409a230c5b4285c5329417189",
      "chat_session_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "room_id": "77f140cf-6f04-11e8-a060-60f81db14236",
      "created_at": "2015-02-13T11:31:36.042"
    },
    {
      "hashed_name": "25d4d74e6e37f5b1a455fd7a45fda2acc2ce0ee4",
      "chat_session_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "room_id": "77f140cf-6f04-11e8-a060-60f81db14236",
      "created_at": "2015-02-13T12:14:34.154"
    }
  ]
}

You may get a paginated collection of all tags of a chat.

GET /api/v5/public/visitors/<visitor_id>/chats/<chat_id>/tags

Returns 404 if the chat is not one of the visitor’s chats. Returns empty list if chat doesn’t have any tags.

Socket API

You can listen real-time notifications about any interesting changes in the system by subscribing a channel on the message router.

Retrieving message router information

GET https://service.giosg.com/api/v5/messagerouter

An example response

{
    "url": "https://messagerouter.giosg.com/003/2/router",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.we2snuuhq-cnPk-GMJVoBhyZ7ZKPa95Qxe_3VkEaf_E",
    "expires_at": "2015-12-22T11:25:30.595Z",
    "expires_in": 1800
}

In order to make a connection to the message router you need to make a HTTP request to the following endpoint:

GET /api/v5/messagerouter

This returns an object with the following attributes:

Attribute Type Description
url string The URL where the client should open the socket connection.
access_token string A JWT access token that is required when subscribing to real-time channels.
expires_at date/time When the access token expires. You should retrieve a new token before this.
expires_in integer After how many seconds the access token will expire. You should retrieve a new token before this.

Subscribing socket channels

Both users and visitors use a socket connection to receive real-time notifications about the changes. Notifications are delivered through channels.

Subscribing the channels is done in the following way:

Step 1: The client opens a connection with message router

["sub", ["<channel_id>", "<access_token>"], {"query": 1234567}]

Step 2: The client sends a sub message with an arbitrary but unique query ID for a channel they want to subscribe.

The <channel_id> must be the ID of the channel being subscribed. The channel ID matches the URL path of the API endpoint where the resource or resource collection would be retrieved. For example: /api/v5/public/visitors/e725acaa886f414986257bfe98d4db1c/chats or /api/v5/orgs/dc5e32c1-54d2-4010-8c04-8b66e565698e/rooms/3f7f6058-af90-4499-b769-9bb348af5736.

The <access_token> must be the JWT access token string. If the token is valid and it grants the permission to the requested channel, then the subscription will be accepted.

["__qr__", [[]], {"query": 1234567}]

Step 3: The client receives a __qr__ message (query response) whenever the subscription is confirmed. The response message contains the same query identifier. The client is now receiving notifications to this channel.

If the <access_token> was not valid or it did not grant access to the channel, then the object also contains fail attribute with value true.

["changed", ["<channel_id>", {
    "action": "<action_type>",
    "resourceId": "f39b84ae-c54c-4de3-a096-9ecde4f07f34",
    "resource": {
        "id": "f39b84ae-c54c-4de3-a096-9ecde4f07f34",
        "name": "Resource Name",
        "created_at": "2015-08-31T16:32:17.879Z"
    }
}]]

Step 4: The client receives a changed message as a notification about an added, removed or changed resource.

There are three possible values for the action:

Action Description
added A new resource has been added to the collection the channel represents. The resource field contains the full resource object.
changed Attributes of a resource have changed. The resourceId attribute describes which resource was changed (see below). The resource field contains only the changed attributes of the resource.
removed A resource has been removed from the collection the channel represents. The resourceId attribute describes which resource was removed (see below).

When the channel represents a collection of resources, the resourceId attribute describes which existing resource was altered. In most cases, the resourceId matches the value of the resource’s id attribute. However, in some cases the identity attribute may have some other name, so it is client’s responsibility to assign the changes to the correct resource.