Skip to content

Chats 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 UUID read-only Unique identifier for the chat.
created_at datetime read-only When the chat conversation started.
updated_at datetime read-only When the chat conversation was last time updated.
waiting_started_at datetime read-only When the chat became waiting. This is 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 datetime read-only When the chat conversation ended (or null if not ended).
room_id UUID read-only ID of the room in which the chat occurred.
room_name string read-only Name of the room in which the chat occurred.
room_organization_id UUID read-only ID of the organization which owns the room in which the chat occurred.
chat_type string read-only Whether the chat's type is operator (operator), visitor (visitor), group (group), task (task) or from some external source (external). When POSTing a new chat with new chat with a visitor in a room endpoint this will automatically be set as visitor and when using create a new empty chat endpoint this be set as operator. Chats with type operator and group are chat sessions between only users. Chats with type visitor are chat sessions that has a visitor membership. Chats with type task will be closed automaticaly by room options ttl. Chats with type external are chat sessions that are from external source (e.g. some integration). These chat's do not close automatically.
is_private boolean read-only Whether or not the chat is marked as private for its operators.
is_real_conversation boolean read-only Whether or not the chat is an actual conversation.
is_autosuggested boolean read-only Whether or not the chat started with an automatic autosuggestion message.
is_encrypted boolean read-only Whether or not the messages of this chat are stored encrypted.
encrypted_symmetric_key string read-only The encrypted symmetric key (AES) with which all the chat messages in this chat are encrypted. This attribute is available only if is_encrypted is true.
message_count integer read-only How many chat 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 chat messages there were by operators in this chat.
visitor_message_count integer read-only How many chat messages there were by visitors in this chat.
has_messages boolean read-only Whether or not there are any messages in chat.
has_user_messages boolean read-only Whether or not there are any user messages in chat.
has_visitor_messages boolean read-only Whether or not there are any visitor messages in chat.
first_visitor_message_url string read-only Full URL of the page that the visitor was on when they sent their first message to this chat, or null if contains no message from the visitor.
first_visitor_message_url_title string read-only Title of the page that the visitor was on when they sent their first message, or null if contains no message from the visitor.
autosuggest_url string read-only Full URL of the page that the visitor was on when they received an autosuggest, or null if this chat does not contain an autosuggestion.
autosuggest_url_title string read-only Title of the page that the visitor was on when they received an autosuggest, or null if this chat does not contain an autosuggestion.
tag_count integer read-only How many tags there are associated with this chat.
is_waiting boolean optional 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.
is_pending boolean read-only This is true if is_waiting is true and the chat has no present user members (i.e. present_user_participant_count is 0). Otherwise this is false.
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.
duration float read-only Duration of the chat in seconds. This is time difference from first message time to last message time in chat. This value is null until the chat has ended.
active_duration float read-only How many seconds of the chat duration was considered to be active time. This is calculated so that after each message chat is assumed to be active for 60 seconds and idle after that if no new messages are received. This value is null until the chat has ended.

Warning

The following attributes also exists but they are deprecated, so you should avoid using them.

Attribute Type Editable Description
token string read-only A legacy Giosg-signed encoded unique string for the chat. You probably won't need this in new implementations!
legacy_conversation_state string read-only A legacy conversation state of the chat. You probably won't need this in new implementations!
legacy_room_id string read-only A legacy ID of the chat's room. You probably won't need this in new implementations!

List chats at a room

1
GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/rooms/9926bdfa-56e0-11e5-b98c-6c4008c08dfe/chats

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/rooms/9926bdfa-56e0-11e5-b98c-6c4008c08dfe/chats?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "token": "uibdbtmk5etolmjaduaafnqpl2ujzkyr4slkq3cabdai37qm",
      "created_at": "2015-02-13T11:31:36.042",
      "ended_at": null,
      "waiting_started_at": null,
      "updated_at": "2015-02-13T12:38:36.431",
      "room_id": "9926bdfa-56e0-11e5-b98c-6c4008c08dfe",
      "room_name": "Customer Support",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "chat_type": "visitor",
      "is_private": false,
      "is_real_conversation": false,
      "is_autosuggested": false,
      "is_encrypted": true,
      "encrypted_symmetric_key": "0d59ab43b5704f08b2aec117658f4bc29a9b0c248547404298bb8a3f06eab7206455a0ddfa1d4972a364d7766eccb4ca",
      "message_count": 0,
      "user_message_count": 0,
      "visitor_message_count": 0,
      "has_messages": false,
      "has_user_messages": false,
      "has_visitor_messages": false,
      "first_visitor_message_url": "http://www.customerpage.com/settings",
      "first_visitor_message_url_title": "Profile Settings",
      "autosuggest_url": "http://www.customerpage.com/",
      "autosuggest_url_title": "Site Frontpage",
      "tag_count": 2,
      "is_waiting": true,
      "member_count": 2,
      "duration": 120,
      "active_duration": 77,
      "user_member_count": 1,
      "visitor_member_count": 1,
      "present_participant_count": 1,
      "present_user_participant_count": 1,
      "present_visitor_participant_count": 1,
      "legacy_conversation_state": "waiting",
      "legacy_room_id": "7sbjsyokgkdmyoifwyaafzll6sdthgar42sbv5c4rhds3yym"
    }
  ]
}

You can list chats for a room:

GET /api/v5/orgs/<organization_id>/rooms/<room_id>/chats

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

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.
created_at_after datetime (none) Returns chats created after the given datetime (ISO 8601)
created_at_before datetime (none) Returns chats created before the given datetime (ISO 8601)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission
  • 404 if room was not found

List organization's owned chats

1
GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_chats

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_chats?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "token": "uibdbtmk5etolmjaduaafnqpl2ujzkyr4slkq3cabdai37qm",
      "created_at": "2015-02-13T11:31:36.042",
      "ended_at": null,
      "waiting_started_at": null,
      "updated_at": "2015-02-13T12:38:36.431",
      "room_id": "9926bdfa-56e0-11e5-b98c-6c4008c08dfe",
      "room_name": "Customer Support",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "chat_type": "visitor",
      "is_private": false,
      "is_real_conversation": false,
      "is_autosuggested": false,
      "is_encrypted": true,
      "encrypted_symmetric_key": "0d59ab43b5704f08b2aec117658f4bc29a9b0c248547404298bb8a3f06eab7206455a0ddfa1d4972a364d7766eccb4ca",
      "message_count": 0,
      "user_message_count": 0,
      "visitor_message_count": 0,
      "has_messages": false,
      "has_user_messages": false,
      "has_visitor_messages": false,
      "first_visitor_message_url": "http://www.customerpage.com/settings",
      "first_visitor_message_url_title": "Profile Settings",
      "autosuggest_url": "http://www.customerpage.com/",
      "autosuggest_url_title": "Site Frontpage",
      "tag_count": 2,
      "is_waiting": true,
      "member_count": 2,
      "user_member_count": 1,
      "visitor_member_count": 1,
      "present_participant_count": 1,
      "present_user_participant_count": 1,
      "present_visitor_participant_count": 1,
      "legacy_conversation_state": "waiting",
      "legacy_room_id": "7sbjsyokgkdmyoifwyaafzll6sdthgar42sbv5c4rhds3yym"
    }
  ]
}

You can list owned chats for an organization:

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

This API endpoint returns a paginated collection of owned chats. These are chats that belong to rooms owned by the organization. They are sorted by the creation time of the chats, in descending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.
created_at_after datetime (none) Returns chats created after the given datetime (ISO 8601)
created_at_before datetime (none) Returns chats created before the given datetime (ISO 8601)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled

Retrieve details of organization's owned chat

You can retrieve details of organization's owned chat:

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

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

End organization's owned chat

Example request that closes a chat

1
PATCH https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_chats/58f5055c-56e0-11e5-9354-6c4008c08dfe

Example payload

1
2
3
{
  "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, users and bots 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. Ending a chat also changes the chat's is_waiting status to false.

Organization user can explicitly end a chat which their organization own by updating the is_ended attribute to true:

PUT /api/v5/orgs/<organization_id>/owned_chats/<chat_id>

or

PATCH /api/v5/orgs/<organization_id>/owned_chats/<chat_id>

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

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Change organization's owned chat to not waiting status

Example request that changes waiting status of a chat to not waiting

1
PATCH https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_chats/58f5055c-56e0-11e5-9354-6c4008c08dfe

Example payload

1
2
3
{
  "is_waiting": false
}

Organization user can change waiting status of a chat which their organization own by updating the is_waiting attribute to false:

PUT /api/v5/orgs/<organization_id>/owned_chats/<chat_id>

or

PATCH /api/v5/orgs/<organization_id>/owned_chats/<chat_id>

You need to define the is_waiting attribute with value false as a payload.

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 400 chat has already been ended
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

List organization's involved chats

You can list chats where users of an organization are members of:

GET /api/v5/orgs/<organization_id>/involved_chats

This API endpoint returns a paginated collection of involved chats, chats that have at least one chat membership of a user that belongs to the organization. They are sorted by the creation time of the chats, in descending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.
created_at_after datetime (none) Returns chats created after the given datetime (ISO 8601)
created_at_before datetime (none) Returns chats created before the given datetime (ISO 8601)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled

Retrieve details of organization's involved chat

You can retrieve details of organization's involved chat:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

List organization's routed chats

You can list chats that are routed to your organization:

GET /api/v5/orgs/<organization_id>/routed_chats

This API endpoint returns a paginated collection of routed chats. Routed chats include chats that are owned by your organization and chats from rooms that have been shared to your organization. They are sorted by the creation time of the chats, in descending order.

For users with reports permission, this API returns chats from all shared rooms, while for others it only returns chats from those organization's shared rooms that have the private_chat_history organization setting disabled. If your organization has private_chat_history organization setting enabled, users without reports permission do not have access to owned chats nor any chats from shared rooms.

Both routed_chats and owned_chats APIs are very similar. Generally, if something works with owned_chats API, then it likely works with routed_chats API too.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.
created_at_after datetime (none) Returns chats created after the given datetime (ISO 8601)
created_at_before datetime (none) Returns chats created before the given datetime (ISO 8601)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled

Retrieve details of organization's routed chat

You can retrieve details of organization's routed chat:

GET /api/v5/orgs/<organization_id>/routed_chats/<chat_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

List pending chats of a room

One of the most important use cases is that the users (chat "agents" or "operators") want to serve visitors that have started a new chat. You can get a paginated collection of pending chats for a specific room that the user has permission:

GET /api/v5/orgs/<organization_id>/rooms/<room_id>/pending_chats

This is a small subset of all the chats of the room, with the following differences:

  • Only includes chats where is_pending is true

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission
  • 404 if room was not found

List visitors chats in a room

You can find out all chats that visitor has in the room with this api.

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

This API endpoint returns a paginated collection of visitor chats. These are chats that belong to room owned by the organization. They are sorted by the creation time of the chats, in descending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.
created_at_after datetime (none) Returns chats created after the given datetime (ISO 8601)
created_at_before datetime (none) Returns chats created before the given datetime (ISO 8601)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled

List pending chats of a user

You usually want to just show pending chats for all rooms the user has access to. One approach is to first list the user's rooms and then get the pending chats for each room. However, there is a more convenient shortcut to get a paginated collection of pending chats of each room the user has access:

GET /api/v5/users/<user_id>/pending_chats

Please note that because this lists pending chats, whether or not the user is a member (chat membership) of the chat does not affect the listed chats.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

List routed chats of a user

This will list all the chats for every room where the user has been linked to using a router. This returns an ordered paginated collection of routed chats.

GET /api/v5/users/<user_id>/routed_chats

Please note that because this lists routed chats, whether or not the user is a member (chat membership) of the chat does not affect the listed chats.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

Retrieve details of user's routed chat

You can retrieve details of user's routed chat:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

List chats of a user

You can get a collection of chats where user is a member:

GET /api/v5/users/<user_id>/chats

This returns a paginated collection. It is sorted by the creation time of the chat, in descending order.

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or updated_at (- for descending results).
is_participating boolean (none) If true, only return chats where <user_id> is participating. If false, exclude chats where <user_id> is currently participating.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the users

Create a new chat with a visitor in a room

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

POST /api/v5/users/<user_id>/rooms/<room_id>/visitors/<visitor_id>/chats

Creating a new chat using this endpoint does not require any attributes and therefore the payload is not required. This endpoint will attempt to get an existing recent chat where the given user can join, instead of creating a new chat. In addition, we will automatically (and atomically) create a membership for this user and chat. NOTE: The “private chats” setting affects the decision whether to create or resume a chat.

This endpoint returns:

  • 200 if existing chat was found
  • 201 if a new chat was created
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 403 if user does not have access to the room
  • 404 if visitor was not found
  • 409 if some else has already a chat with the visitor

Create a new empty chat for user

Start a new chat without a visitor for user. Other users/teams/partner organizations can be invited to this chat by using chat invitations.

POST /api/v5/users/<user_id>/chats

Creating a new chat using this endpoint does not require any attributes and therefore the payload is not required.

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

List visitor's chats in a room

You can get a collection of chats where the visitor is a member, in the given room:

GET /api/v5/users/<user_id>/rooms/<room_id>/visitors/<visitor_id>/chats

This returns paginated collection. It is sorted by the creation time of the chat, in descending order.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if room was not found
  • 404 if visitor was not found

End a chat

Example request that closes a chat

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

Example payload

1
2
3
{
  "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, users 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. Ending a chat also changes the chat's is_waiting status to false.

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

PUT /api/v5/users/<user_id>/chats/<chat_id>

or

PATCH /api/v5/users/<user_id>/chats/<chat_id>

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

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Change a chat to not waiting status

Example request that changes waiting status of a chat to not waiting

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

Example payload

1
2
3
{
  "is_waiting": false
}

You can explicitly change waiting status of a chat in which you are a member by updating the is_waiting attribute to false:

PUT /api/v5/users/<user_id>/chats/<chat_id>

or

PATCH /api/v5/users/<user_id>/chats/<chat_id>

You need to define the is_waiting attribute with value false as a payload.

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 400 chat has already been ended
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Chat memberships

The visitor as well as each user who have attended to the chat (i.e. they are "chat members") are represented with a chat membership objects.

Attribute Format Editable Description
member_id UUID/string read-only ID of the user or visitor being present at the chat.
member_type string read-only Either visitor or user.
member_name string read-only The name of the user/visitor as it would be displayed for the operator. For users this the actual name. For visitors this is any custom name, or null.
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.
member_organization_id UUID read-only ID of the member's organization.
room_id UUID read-only ID of the room where the chat takes place.
room_organization_id UUID read-only ID of the room's organization where the chat takes place.
chat_id UUID read-only ID of the chat.
created_at datetime read-only When the user/visitor was added as a chat member.
last_seen_at datetime optional When the user/visitor was last seen at. This field may be updated by clients to let other clients know that user has seen the conversation and messages were read. This field may be null if the value was not set yet.
updated_at datetime read-only When the this membership was updated.
chat_created_at datetime read-only When the chat started.
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_bot boolean read-only Whether the participating user is bot user or not.
is_user_deleted boolean read-only Whether the participating user is deleted or not. The changes to this field are not broadcasted from the websocket.
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 except if user's is_participating is false then the is_present will be also false.
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.

Warning

The following attributes also exists but they are deprecated, so you should avoid using them.

Attribute Type Editable Description
legacy_member_id string read-only A legacy ID of the user. You probably won't need this in new implementations!

List chat memberships

1
GET /api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/rooms/aad26fe2-c8f3-45dc-931b-4b0b5e06467d/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/memberships

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/memberships?cursor=45d9e7358e1249c491b4fa0212310f55",
  "previous": null,
  "results": [
    {
      "member_id": "378ad5a0-bb89-481b-978b-4268b368cfef",
      "member_type": "user",
      "member_name": "John Smith",
      "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"
      },
      "member_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "chat_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "room_id": "e39930de-0957-11e7-87e4-f45c89c72de3",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "created_at": "2015-02-13T11:31:36.042",
      "last_seen_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T11:32:36.042",
      "chat_created_at": "2015-02-13T11:30:36.042",
      "is_bot": false,
      "is_user_deleted": false,
      "is_participating": true,
      "is_present": true,
      "composing_status": "idle",
      "message_count": 8
    },
    {
      "member_id": "3b90ef7c93484af4965a79ace7bc9a62",
      "member_type": "visitor",
      "member_name": null,
      "member_public_name": null,
      "member_avatar": null,
      "member_organization_id": null,
      "chat_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "room_id": "e39930de-0957-11e7-87e4-f45c89c72de3",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "created_at": "2015-02-13T12:14:34.154",
      "last_seen_at": "2015-02-13T12:14:34.154",
      "updated_at": "2015-02-13T12:15:34.154",
      "chat_created_at": "2015-02-13T11:30:36.042",
      "is_bot": false,
      "is_user_deleted": false,
      "is_participating": true,
      "is_present": true,
      "composing_status": "typing",
      "message_count": 7
    }
  ]
}

You can get a paginated collection of all the memberships of the chat:

GET /api/v5/orgs/<organization_id>/rooms/<room_id>/chats/<chat_id>/memberships

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission
  • 404 if room was not found
  • 404 if chat was not found

Or alternatively:

GET /api/v5/users/<user_id>/chats/<chat_id>/memberships

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found

Or alternatively you can list memberships of a routed chat of the user:

/api/v5/users/<user_id>/routed_chats/<chat_id>/memberships

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if the related chat does not exist or it is not routed to the user

Or list organization's owned chat's memberships:

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

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Or list organization's involved chat's memberships:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/memberships

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Or list organization's routed chat's memberships:

GET /api/v5/orgs/<organization_id>/routed_chats/<chat_id>/memberships

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Also, as an alternative to list a user's chats, you may list their own chat memberships. Each result is a chat member resource for each of the chat of the user:

GET /api/v5/users/<user_id>/chat_memberships

This endpoint takes the following GET-parameters:

Parameter Type Default Description
is_participating boolean (none)  If true, then return only chats where user is participating. If false, return only chats where user is not participating.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

List visitor's chat memberships

You can get a paginated collection of all the memberships of the visitor by chat:

GET /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/chat_memberships

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if visitor was not found

List pending chat's memberships

You can get a paginated collection of pending chat's memberships:

GET /api/v5/users/<user_id>/pending_chats/<chat_id>/memberships

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the chat was not pending anymore

Join user to a pending chat

Example request for joining a user to a chat

1
POST https://service.giosg.com/api/v5/users/0f34f1b2-2922-4a2e-9706-8cca0a1b3eec/pending_chats/62eb5cd5-5d52-4bb1-b711-ba31f864e775/memberships

Example request payload

1
2
3
4
{
  "is_participating": true,
  "composing_status": "idle"
}

You can add your user as a member (chat membership) to one of their pending chats:

POST /api/v5/users/<user_id>/pending_chats/<chat_id>/memberships

You should define whether you want to be participating the chat with is_participating. You usually want to set this true when creating a new membership. Also, the composing_status is required, but may usually want to set it initially to idle.

Notice

This endpoint returns 404 if the chat is no more considered "pending" at the moment, effectively preventing multiple users adding themselves as members to the same pending chat.

If you want to prevent other users "taking" this pending chat, then ensure that

The chat will then be marked as "non-pending" and the chat is removed from "pending chats" of other users. However, if your user becomes absent before sending any messages to the chat, then the chat is returned to "pending chats" (but your user will still remain a chat member).

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the chat was not pending not anymore
  • 404 if the chat has ended
  • 409 if the user was not present

Join user to a routed chat

Example request for joining a user to a routed chat

1
POST https://service.giosg.com/api/v5/users/0f34f1b2-2922-4a2e-9706-8cca0a1b3eec/routed_chats/62eb5cd5-5d52-4bb1-b711-ba31f864e775/memberships

Example request payload

1
2
3
4
{
  "is_participating": true,
  "composing_status": "idle"
}

You can add your user as a member (chat membership) to one of their routed chats:

POST /api/v5/users/<user_id>/routed_chats/<chat_id>/memberships

You should define whether you want to be participating the chat with is_participating. You usually want to set this true when creating a new membership. Also, the composing_status is required, but may usually want to set it initially to idle.

This endpoint returns:

  • 201 if the request was successful and the new membership was created
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if the related chat does not exist or it is not routed to the user
  • 404 if the chat has ended
  • 409 if there is already a present user member in the chat AND the organization has "private chats" enabled AND the joining user does not have the reports permission

Join user to a organization's chat

Example request for joining a organization's user to a chat

1
POST https://service.giosg.com/api/v5/orgs/0f34f1b2-2922-4a2e-9706-8cca0a1b3eec/owned_chats/62eb5cd5-5d52-4bb1-b711-ba31f864e775/memberships

Example request payload

1
2
3
4
5
{
  "member_id": "2ffbfa02-c1f1-11e6-87fa-f45c89c72de3",
  "is_participating": true,
  "composing_status": "idle"
}

You can add your organization's user as a member (chat membership) to a organization's owned chats:

POST /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/memberships

This endpoint returns:

  • 200 if an existing membership was found
  • 201 if a new membership was created
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Or you may join to your organization's involved chat:

POST /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/memberships

This endpoint returns:

  • 200 if an existing membership was found
  • 201 if a new membership was created
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Or you can add your organization's user as a member to a routed chat:

POST /api/v5/orgs/<organization_id>/routed_chats/<chat_id>/memberships

This endpoint returns:

  • 200 if an existing membership was found
  • 201 if a new membership was created
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

You should define whether you want to be participating the chat with is_participating. You usually want to set this true when creating a new membership. Also, the composing_status is required, but may usually want to set it initially to idle. Note that the member_id is required field for this endpoint.

If is_participating is set as true and the chat was pending, then this will remove this chat from pending chats for all users.

Update a chat membership of a user

Example request for making the operator typing at the chat

1
PUT https://service.giosg.com/api/v5/users/ce771dbe-afbf-4e58-bbcb-9855ecacee9a/chat_memberships/62eb5cd5-5d52-4bb1-b711-ba31f864e775

Example request payload

1
2
3
4
5
{
  "is_participating": true,
  "composing_status": "typing",
  "last_seen_at": "2015-02-13T11:31:36.042"
}

The chat membership's is_participating attribute should be refreshed when the user opens or closes a chat.

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

Also it is highly recommended that clients update last_seen_at field whenever user interface displays chat to user. This allows other clients to know if messages have been received and read/seen by the other users.

You can change the chat status of the user similarly than described in the previous session:

PUT /api/v5/users/<user_id>/chat_memberships/<chat_id>

You should provide the is_participating attribute with either true or false value, indicating whether or not the user should be currently present at the chat. Also, you need to provide the composing_status attribute describing whether or not the user is typing or has typed a message.

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the chat has ended
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 409 if the user was not present

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.

If you want to get link previews for each link, you need to call the link preview api. You need to parse the link urls from the messages by yourself.

Attribute Type Editable Description
id UUID read-only Unique identifier for the message
type string read-only Whether the message is an actual message (msg), autosuggest (autosuggest), a join event (join), a leave event (leave), a shopping cart locked event (shoppingcart_locked), an action event (action) from attachment reaction, a call request (call_request), a call information (call_ended), a interaction data (interaction_submit), a tag created (tag_created), a tag deleted (tag_deleted), or a message from system (system). When POSTing a message, this will automatically be set to msg.
chat_id UUID read-only ID of the chat.
room_id UUID read-only ID of the room in which the chat occurred.
created_at datetime read-only When the message was sent.
sender_type string read-only Whether the sender is operator (user), visitor (visitor), or triggered by rule (rule). When POSTing a new message with these endpoints, this will automatically be set to user.
sender_id UUID/string read-only 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 him. This value might change if the sender type was rule.
sender_name string read-only A display name for the sender as an operator would see him. This value might change if the sender type was rule.
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 this case your client needs to decrypt the chiphertext in encrypted_message. 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.
is_encrypted boolean read-only Whether or not the message is stored encrypted. When true, the encrypted_message attribute contains the encrypted chiphertext of the message.
encrypted_message string read-only The encrypted chiphertext of the message, if encryption is used for the chat. This attribute is only present if is_encrypted is true.
sensitive_data_purged_at datetime read-only When the message's sensitive data was purged. This means that the message and visitor's sender_name and sender_public_name are set as null. This is null if the data was not purged.
selected_reply_suggestion_id UUID optional The chat reply suggestion that was selected as a basis for this message. NOTE: the message may differ from the suggestion of the related suggestion, if the user has edited the selected suggestion message before sending it! This is null if the message is not based on any chat reply suggestion.
selected_reply_suggestion object read-only The selected chat reply suggestion as a nested object, containing attributes id, suggestion, and relevancy_score. This is nullif the message is not based on any chat reply suggestion.
attachments list of objects optional List of chat message attachments for this chat message. These represent rich or interactive content provided in this message. These are explained in next section. Note that only one attachment can be specified in this list if attachment_template is set to interaction.
attachment_template string optional Type of chat message attachment template, either null, "generic", "interaction" or "external". These are explained in next section.
response_to_message_id UUID read-only Unique identifier of the message this was a response to. null if it wasn't a response.
response_to_attachment_id UUID 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 UUID 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.
response_text string read-only Response text of the attachment response. This field may be null if response was to generic attachment or free form text if this message was response to interaction attachment. This field is required for interaction attachment response.

List chat messages

1
GET /api/v5/orgs/54de4830-a16e-417a-802b-4bf4bcb59ed8/owned_chats/450fc49e-277e-4dd6-af0f-6e9dcb885b09/messages

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
{
  "next": "https://service.giosg.com/api/v5/orgs/54de4830-a16e-417a-802b-4bf4bcb59ed8/owned_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",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:30:03.045",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "sender_name": "John Smith",
      "message": "How may I help you?",
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "attachment_template": null,
      "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,
      "response_text": null
    },
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "type": "msg",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:31:36.042",
      "sender_type": "visitor",
      "sender_id": "f7a5a3b83d2e40dfb0dedd6c0e284214",
      "sender_public_name": null,
      "sender_name": null,
      "message": "Yes, actually you could.",
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "attachment_template": null,
      "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,
      "response_text": null
    },
    {
      "id": "a3a3b8ed-7336-431a-8350-8f5be471a09e",
      "type": "join",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:31:38.123",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "sender_name": "John Smith",
      "message": null,
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "attachment_template": null,
      "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,
      "response_text": null
    },
    {
      "id": "487a4dce-503a-43d0-bd62-1e1a7582c93b",
      "type": "msg",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:32:01.654",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "sender_name": "John Smith",
      "message": "OK, what do you want to know?",
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "attachment_template": null,
      "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,
      "response_text": null
    }
  ]
}

Get the collection of all chat messages in the given chat if it's organization's owned chat.

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

This endpoint takes the following GET-parameters:

Parameter Type Default Description
type__in list (none) Filter messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)
type__not_in list (none) Exclude messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Or if the organization is involved in the chat:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/messages

This endpoint takes the following GET-parameters:

Parameter Type Default Description
type__in list (none) Filter messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)
type__not_in list (none) Exclude messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Or you can get messages of a routed chat:

GET /api/v5/orgs/<organization_id>/routed_chats/<chat_id>/messages

This endpoint takes the following GET-parameters:

Parameter Type Default Description
type__in list (none) Filter messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)
type__not_in list (none) Exclude messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Or alternatively:

GET /api/v5/users/<user_id>/chats/<chat_id>/messages

This endpoint takes the following GET-parameters:

Parameter Type Default Description
type__in list (none) Filter messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)
type__not_in list (none) Exclude messages with a type found in the list provided. List should be comma separated (msg,leave,join,etc)

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found

Or alternatively list messages of user's routed chat:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>/messages

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

The response is a paginated collection, ordered by the creation date in descending order.

Send a chat message

1
POST /api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

1
2
3
{
  "message": "OK, I've found out the issue!"
}

Send a new chat message to a user's chat with type msg to a chat:

POST /api/v5/users/<user_id>/chats/<chat_id>/messages

The <user_id> will be set as the sender of the message.

Warning

The user must be a member of the chat in order to send a message. Otherwise a 404 response is returned, as the chat was not found in the chats of the user.

If the chat was previously in waiting state, then is_waiting of the chat is automatically changed to false.

You may also include the chat_reply_suggestion_id attribute with an ID of any chat reply suggestion in the same chat.

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 409 if the chat is ended

Chat message attachments

Chat message attachments represent rich or interactive content for chat message. You may provide images, buttons etc. as attachment with actions for different scenarios. You might want to consider reading the chat message attachment guide before using these. An attachment object consists:

Attribute Format Editable Description
id UUID read-only ID of the attachment.
title string optional The title of this attachment. When attachment_template is set to generic, this is shown to the visitor. When attachment_template is interaction or external, this is only shown to the operator.
title_link_url string optional The URL of the title. If provided, then title will show as clickable link which will open in the given URL. This field can be used when attachment_template field of message was set to generic.
text string optional The text part of this attachment. This may serve as description. This can also be Markdown (bold, cursive or link). When attachment_template is set to generic, this is shown to the visitor. When attachment_template is interaction or external, this is only shown to the operator.
image_url string optional The URL of image. This field can be used when attachment_template field of message was set to generic.
image_link_url string optional The URL of image link. If provided, then the image will show as clickable image which will open in the given URL. This field can be used when attachment_template field of message was set to generic.
link_target string optional The target window of the image_link_url and title_link_url. This value is omitted if no links are provided, otherwise this defines whether the link is opened in a new tab or redirects current tab to a new URL. Valid choices for this are _blank (open new tab) and _parent (redirect in current tab). Defaults to _blank. This field can be used when attachment_template field of message was set to generic.
actions list of objects optional List of possible actions for this attachment. These are explained in next section. This field can be used when attachment_template field of message was set to generic.
interaction_id UUID optional ID of interaction to attach. If provided, then the interaction will be attached to chat conversation. This field can be used when attachment_template field of message was set to interaction.
attachment_url string optional Url of an external page to attach. If provided, then the page will be iframed to chat conversation. This field can be used when attachment_template field of message was set to external.
parameters object optional Free form JSON to be used as parameters for interaction attachment. This field can be used when attachment_template field of message was set to interaction or external. For external attachments, these values are appended to the attachment_url as get parameters.

NOTE: Validation of fields depend on the type of attachment_template selected for message. For generic attachments if none of the fields; title, text, image_url or actions is provided, then 400 is returned. For interaction attachments interaction_id is required. For external attachments attachment_url is required. With interaction or external templates, you can optionally also provide title, text and parameters fields.

A generic attachment may have multiple actions. For example you might want to provide feedback survey as an attachment and have multiple different buttons as answer options. For now actions are always buttons with different kind of outcomes. An attachment action object consists:

Attribute Format Editable Description
id UUID read-only ID of the action.
text string required The text of this action. The text will be shown inside the button when rendered to the user interface.
type string required The type of this action. This can be button or link_button.
link_target string optional The target window of the link_button. This value is omitted if the type of this action is not link_button, otherwise this defines whether the link is opened in a new tab or redirects current tab to a new URL. Valid choices for this are _blank (open new tab) and _parent (redirect in current tab). Defaults to _blank.
value string required The value for this action. For action with type of link_button this should be either a valid URL (For example: https://giosg.com/contact-us) where the button should redirect or an anchor link (For example: #contact-us) that navigates to an anchor inside the current page. Otherwise, the value can be any string.
style string optional Style of the action. This can be primary, secondary, info, success, warning, danger, link, brand_primary or brand_secondary. This defines color of the button. If omitted, defaults to secondary. Brand colors defined for a Room can be used aswell.
is_disabled_on_selection boolean required Defines whether the actions are disabled after selection. If true then all of the attachment's actions with true for is_disabled_on_selection are disabled after selection of one. If false then the action remains enabled after selection.
is_disabled_on_visitor_message boolean required Defines whether the actions are disabled after visitor sends a new message to chat conversation. This message's type has to be msg (a real message). If true then all of the attachment's actions with true for is_disabled_on_visitor_message are disabled after the visitor's message. If false then the action remains enabled after visitor message.

Send a chat message with generic attachments

1
POST /api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "message": "Do you want help?",
  "attachment_template": "generic",
  "attachments": [
    {
      "text": "Was this conversation helpful?",
      "actions": [
        {
          "text": "Yes",
          "type": "button",
          "value": "yes",
          "style": "success",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "text": "Maybe",
          "type": "button",
          "value": "maybe",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "text": "No",
          "type": "button",
          "value": "no",
          "style": "danger",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        }
      ]
    }
  ]
}

Sending a chat message with attachments is not much different than sending chat message normally. You can provide additional attachments list (optionally with desired actions too) along the message in the payload.

Send a chat message with interaction attachment

1
POST /api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "message": "Do you want help?",
  "attachment_template": "interaction",
  "attachments": [
    {
      "text": "Was this conversation helpful?",
      "interaction_id": "d75feb7a-1584-495a-b77f-9dac6a8d7fbf",
      "parameters": {
        "initial_height": 250,
        "custom_param": true
      }
    }
  ]
}

  • Sending a chat message with interaction attachments is not much different than sending chat message normally. You need to provide additional attachments list along the message in the payload. Also attachment_template field of message needs to be set to interaction. The attachment itself has to have the interaction_id defined. Note that with interaction attachment there can only one attachment in attachments list per message.

  • The parameters field contains information that is passed down to the interaction. Note that you can send any amount of key value pairs in the parameters. These values are passed to the interaction. There are two special parameters that the chat window reacts to:

  • initial_height is used to set the iframe height before the interaction has loaded. Once the interaction has loaded, it sends its current height. If initial_height is not specified, the default value is 150px. If your interaction has very different actual height than the initial_height or the 150px default value, the iframe changes its size a lot after loading and it might look weird for the visitor. So setting initial_height correctly will prevent those big size changes.

  • mode can be used by giosg staff to change what url is used in the iframe. Setting mode to staging, the iframe tries to load the interaction from the staging environment. Setting it to localhost, the iframe tries to load the interaction from the interaction designer server that is running locally on your computer.

Send a chat message with external attachment

1
POST /api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "message": "Do you want help?",
  "attachment_template": "external",
  "attachments": [
    {
      "attachment_url": "https://somewhere.com/my-interaction",
      "parameters": {
        "initial_height": 200,
        "custom_param": true
      },
      "text": "Help",
      "title": "Help interaction"
    }
  ]
}

Sending a chat message with external attachment is not much different than sending chat message normally. You need to provide additional attachments list along the message in the payload. Also attachment_template field of message needs to be set to external. The attachment itself has to have the attachment_url defined. Note that with external attachment there can only one attachment in attachments per message.

The parameters field contains information that is passed down to the external attachment by appending them to the attachment_url as get parameters. Note that you can send any amount of key value pairs in the parameters. There is one special parameter that the chat window reacts to:

  • initial_height is used to set the iframe height. This height can then be changed by sending messages from the embedded site to the chat window.

Chat message response actions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "id": "899042d4-4aaf-11e7-899c-f45c89c72de3",
  "type": "action",
  "chat_id": "9d25ef9d-26ed-40e8-8d74-a6a17039195d",
  "room_id": "322ca9c0-bfe0-11e8-8ff3-8c8590c2eeca",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "visitor",
  "sender_id": "a3fedae14aaf11e7a05ef45c89c72de3",
  "sender_public_name": null,
  "sender_name": null,
  "message": "Yes",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "selected_reply_suggestion_id": null,
  "selected_reply_suggestion": null,
  "attachments": [],
  "attachment_template": null,
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "4ee16b6b-4b4d-11e7-9eaa-f45c89c72de3",
  "response_to_action_id": "605dc7c0-4ab3-11e7-94ab-f45c89c72de3",
  "response_to_action": {
    "id": "605dc7c0-4ab3-11e7-94ab-f45c89c72de3",
    "text": "Yes",
    "type": "button",
    "value": "yes",
    "style": "success",
    "is_disabled_on_selection": true
  },
  "response_value": "yes",
  "response_text": null
}

In most cases you might want to know which attachment the visitor selected. These responses can be done by using public API for sending chat message. For now these responses can be requested by using the list API of chat messages. The message type of these are action and they contain additional info about the selected attachment/action.

Chat invitations

User may invite users, their own teams, teams shared by partner organizations or partner organizations to an ongoing chat. This is done with invitation objects. When sending and managing chat invitations, we use chat invitations.

An chat invitation object has the following attributes::

Attribute Type Editable Description
id UUID read-only Unique identifier of this invitation
is_accepted boolean optional Whether or not the chat invitation has been accepted.
is_expired boolean optional Whether or not the chat invitation has been expired. Chat invitation will expire if it's not accepted before chat ends.
invited_by_user_id UUID read-only ID of the user who invited.
invited_by_user object read-only The user(s) who invited.
chat_id UUID read-only ID of the Chat.
room_id UUID read-only ID of the room in which the chat occurred.
invited_user_id UUID required ID of the user who was invited to the chat.
invited_team_id UUID required ID of your own team or a team shared by a partner organization which was invited.
invited_organization_id UUID required ID of the organization that was invited for this chat.
invitee_name string read-only Name of the invitee. This is either full name of the user, name of the team, or name of the organization depending on which party was invited.
accepted_by_user_id UUID read-only ID of the user who accepted invite.
accepted_by_user object read-only The user(s) who accepted invite.
user_member_count integer read-only How many user(s) are in this chat.
visitor_member_count integer read-only How many visitors are in this chat.
created_at datetime read-only When the chat invitation was sent.
updated_at datetime read-only When the chat invitation was last time updated.
accepted_at datetime read-only When the chat invitation was accepted (or null if not accepted).
expired_at datetime read-only When the chat invitation was expired (or null if it has been accepted).

NOTE: Only one of the invited_user_id, invited_team_id or invited_organization_id can be defined per chat invitation object. Other two attributes should be either null or omitted. When accepting chat invitation, is_accepted is required field. Also, is_expired field can only be defined when using the update API for outgoing chat invitations.

List outgoing chat invitations for user

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/outgoing_chat_invitations

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/outgoing_chat_invitations",
  "previous": null,
  "results": [
    {
      "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
      "is_accepted": true,
      "is_expired": false,
      "invited_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "invited_by_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
      "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
      "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "invited_team_id": null,
      "invited_organization_id": null,
      "invitee_name": "Bob von Helper",
      "accepted_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "accepted_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Bob von Helper",
        "first_name": "Bob",
        "last_name": "von Helper",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "user_member_count": 1,
      "visitor_member_count": 1,
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "accepted_at": "2016-09-01T16:31:36.042Z",
      "expired_at": null
    }
  ]
}

You can get a paginated collection of all the outgoing chat invitations for the user in current chat. They are sorted by the creation time of the invitation, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
is_accepted boolean (none) If true, then return only accepted chat invitations. If false, return only chat invitations which are pending but are not expired.
is_expired boolean (none)  If true, then return only expired chat invitations. If false, return only chat invitations which has not expire.

GET /api/v5/users/<user_id>/chats/<chat_id>/outgoing_chat_invitations

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found

List chat invitations for organization

1
GET https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/chat_invitations

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "next": "https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/chat_invitations",
  "previous": null,
  "results": [
    {
      "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
      "is_accepted": true,
      "is_expired": false,
      "invited_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "invited_by_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
      "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
      "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "invited_team_id": null,
      "invited_organization_id": null,
      "invitee_name": "Bob von Helper",
      "accepted_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "accepted_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Bob von Helper",
        "first_name": "Bob",
        "last_name": "von Helper",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "user_member_count": 1,
      "visitor_member_count": 1,
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "accepted_at": "2016-09-01T16:31:36.042Z",
      "expired_at": null
    }
  ]
}

You can get a paginated collection of all the chat invitations for the organization. They are sorted by the creation time of the invitation, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
is_accepted boolean (none) If true, then return only accepted chat invitations. If false, return only chat invitations which are pending but are not expired.
is_expired boolean (none)  If true, then return only expired chat invitations. If false, return only chat invitations which has not expire.

GET /api/v5/orgs/<org_id>/chat_invitations

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 404 if organization was not found

Send a chat invitation

Example request that send a chat invitation for a user from own organization

1
POST https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/outgoing_chat_invitations

1
2
3
{
  "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3"
}

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
  "is_accepted": false,
  "is_expired": false,
  "invited_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
  "invited_by_user": {
    "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
    "full_name": "Bill Giosg",
    "first_name": "Bill",
    "last_name": "Giosg",
    "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
  },
  "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
  "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
  "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
  "invited_team_id": null,
  "invited_organization_id": null,
  "invitee_name": "Bob von Helper",
  "accepted_by_user_id": null,
  "accepted_by_user": null,
  "user_member_count": 1,
  "visitor_member_count": 1,
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T11:31:36.042Z",
  "accepted_at": null,
  "expired_at": null
}

You may send a chat invitation to your organization's users, teams, teams shared by partner organizations or partner organizations by creating a new chat invitation object.

POST /api/v5/users/<user_id>/chats/<chat_id>/outgoing_chat_invitations

You need to define only one of the invited_user_id, invited_team_id or invited_organization_id attributes as a payload.

This endpoint returns:

  • 200 if invited party already has a pending chat invitation to this chat
  • 201 if a chat invitation was successfully sent
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if the invited user, team, or organization is not found

Expire a chat invitation

Example request that expires an outgoing chat invitation

1
PATCH https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/outgoing_chat_invitations/4d0648b8-9074-11e6-963e-f45c89c72de3

1
2
3
{
  "is_expired": true
}

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
  "is_accepted": false,
  "is_expired": true,
  "invited_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
  "invited_by_user": {
    "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
    "full_name": "Bill Giosg",
    "first_name": "Bill",
    "last_name": "Giosg",
    "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
  },
  "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
  "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
  "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
  "invited_team_id": null,
  "invited_organization_id": null,
  "invitee_name": "Bob von Helper",
  "accepted_by_user_id": null,
  "accepted_by_user": null,
  "user_member_count": 1,
  "visitor_member_count": 1,
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T11:31:36.042Z",
  "accepted_at": null,
  "expired_at": "2016-09-01T11:31:36.042Z"
}

You may expire a chat invitation by updating your existing invitation.

PUT /api/v5/users/<user_id>/chats/<chat_id>/outgoing_chat_invitations/<invitation_id>

Or

PATCH /api/v5/users/<user_id>/chats/<chat_id>/outgoing_chat_invitations/<invitation_id>

You need to define is_expired attribute as a payload. The value has to be true. All other attributes in payload are omitted.

This endpoint returns:

  • 200 if the invitation was expired successfully
  • 400 if required attribute is missing from the request
  • 400 if the request payload is in wrong format
  • 400 if the invitation has already expired
  • 400 if the invitation has already been accepted by some party
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if the invitation is not found

List incoming chat invitations for the user

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/incoming_chat_invitations

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/incoming_chat_invitations",
  "previous": null,
  "results": [
    {
      "id": "6d348a30-9076-11e6-8756-f45c89c72de3",
      "is_accepted": false,
      "is_expired": false,
      "invited_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "invited_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Bob von Helper",
        "first_name": "Bob",
        "last_name": "von Helper",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
      "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
      "invited_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "invited_team_id": null,
      "invited_organization_id": null,
      "invitee_name": "Bill Giosg",
      "accepted_by_user_id": null,
      "accepted_by_user": null,
      "user_member_count": 1,
      "visitor_member_count": 1,
      "created_at": "2016-09-01T15:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "accepted_at": null,
      "is_expired": null
    }
  ]
}

You can get a paginated collection of all the incoming chat invitations for the user. They are sorted by the creation time of the invitation, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
is_accepted boolean (none) If true, then return only accepted chat invitations. If false, return only chat invitations which are pending but are not expired.
is_expired boolean (none)  If true, then return only expired chat invitations. If false, return only chat invitations which has not expire.

GET /api/v5/users/<user_id>/incoming_chat_invitations

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

Accept incoming chat invitation

Example request that accepts the chat invitation for user

1
PATCH https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/incoming_chat_invitations/6d348a30-9076-11e6-8756-f45c89c72de3

1
2
3
{
  "is_accepted": true
}

You may accept your user's incoming chat invitations.

PUT /api/v5/users/<user_id>/incoming_chat_invitations/<invitation_id>

PATCH /api/v5/users/<user_id>/incoming_chat_invitations/<invitation_id>

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 400 if the chat was not in "pending state" i.e. the invitation has expired, other user from team or organization already responded to invitation.
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat invitation was not found

Chat tags

Chats may be tagged with any number of keywords, or simply put "tags".

A chat tag has the following attributes:

Attribute Type Editable Description
name string required The name of the tag.
created_at datetime read-only When the chat was tagged with this tag.
hashed_name string read-only Sha1 hash of this tag. This is the only information that the visitor and goals generated have about the tag.
room_id UUID read-only ID of the room to which this tag belongs to.

List tags of a chat

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/tags

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/tags?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "name": "Lead",
      "created_at": "2016-09-01T11:31:36.042Z"
    },
    {
      "name": "Premium customer",
      "created_at": "2016-09-01T12:20:12.206Z"
    }
  ]
}

You can get a paginated collection of all the tags for one of a user's chats:

GET /api/v5/users/<user_id>/chats/<chat_id>/tags

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Alternatively you may want to retrieve tags by using the organization:

You can get all the tags for a organization's owned chat:

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

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's involved chat:

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

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's routed chat:

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

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

List allowed tags for a chat

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/allowed_tags

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/allowed_tags?cursor=c42126a86cf547b1a9742d480950a981",
  "previous": null,
  "results": [
    {
      "name": "Lead",
      "created_at": "2016-09-01T11:31:36.042Z",
      "hashed_name": "cf23df2207d99a74fbe169e3eba035e633b65d94",
      "room_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b8"
    },
    {
      "name": "Premium customer",
      "created_at": "2016-09-01T12:20:12.206Z",
      "hashed_name": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
      "room_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b8"
    },
    {
      "name": "Support",
      "created_at": "2016-09-01T13:14:01.030Z",
      "hashed_name": "85136c79cbf9fe36bb9d05d0639c70c265c18d37",
      "room_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b8"
    }
  ]
}

You can get a paginated collection of all the tags that are allowed for one of a user's chats. The allowed tags are defined by the room to which the chat belongs.

GET /api/v5/users/<user_id>/chats/<chat_id>/allowed_tags

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Alternatively you may want to retrieve allowed tags by using the organization:

You can get all the allowed tags for a organization's owned chat:

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

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's involved chat:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/allowed_tags

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's routed chat:

GET /api/v5/orgs/<organization_id>/routed_chats/<chat_id>/allowed_tags

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Add a tag to a chat

Example request that adds a tag to a chat

1
POST https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/1d3885ef-a151-4cb1-b289-69123f142a8a/tags

1
2
3
{
  "name": "Lead"
}

Example response

1
2
3
4
5
{
  "name": "Lead",
  "hashed_name": "85136c79cbf9fe36bb9d05d0639c70c265c18d37",
  "created_at": "2016-09-01T11:31:36.042Z"
}

You can add a tag to one of the user's chats:

POST /api/v5/users/<user_id>/chats/<chat_id>/tags

This endpoint returns:

  • 200 if an existing tag was found with given name
  • 201 a new tag was successfully created for the chat
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Alternatively you may want to add tags by using the organization:

You can add a tag for a organization's owned chat:

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

This endpoint returns:

  • 200 if an existing tag was found with given name
  • 201 a new tag was successfully created for the chat
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's involved chat:

POST /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/tags

This endpoint returns:

  • 200 if an existing tag was found with given name
  • 201 a new tag was successfully created for the chat
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's routed chat:

POST /api/v5/orgs/<organization_id>/routed_chats/<chat_id>/tags

This endpoint returns:

  • 200 if an existing tag was found with given name
  • 201 a new tag was successfully created for the chat
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Also, you need to define the name attribute as a payload.

Remove a tag from a chat

1
DELETE https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/tags/Premium%20customer

You can remove a tag from one of the user's chats:

DELETE /api/v5/users/<user_id>/chats/<chat_id>/tags/<tag_name>

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Alternatively you may want to remove tags by using the organization:

You can remove a tag for a organization's owned chat:

DELETE /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/tags/<tag_name>

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's involved chat:

DELETE /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/tags/<tag_name>

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

And for the organization's routed chat:

DELETE /api/v5/orgs/<organization_id>/routed_chats/<chat_id>/tags/<tag_name>

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have reports permission and the organization has private history enabled
  • 404 if chat was not found

Also, the <tag_name> must be a URL-encoded name of the tag to be removed.

Chat conversation starters

user(s) may have none or multiple chat conversation starters with limitation of one per language.

A chat conversation starter has the following attributes:

Attribute Type Editable Description
language_code string required Language of this message as a RFC 3066 code. It must be one of the supported languages.
message string required The conversation starter message.
created_at datetime read-only When the chat conversation starter was created.
updated_at datetime read-only When the chat conversation starter was last time updated.

List chat conversation starters for user

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters",
  "previous": null,
  "results": [
    {
      "language_code": "en",
      "message": "How can I help you?",
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z"
    },
    {
      "language_code": "fi",
      "message": "Kuinka voin auttaa?",
      "created_at": "2016-09-01T12:20:12.206Z",
      "updated_at": "2016-09-01T16:31:36.042Z"
    },
    {
      "language_code": "sv",
      "message": "Hur kan jag hjälpa dig?",
      "created_at": "2016-09-01T13:14:01.030Z",
      "updated_at": "2016-09-01T17:31:36.042Z"
    }
  ]
}

You can get a paginated collection of all the chat conversation starters for the user. They are sorted by the creation time of the conversation starters, in ascending order.

GET /api/v5/users/<user_id>/chat_conversation_starters

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

Add a chat conversation starter for user

Example request that adds a chat conversation starter for the user

1
POST https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters

1
2
3
4
{
  "message": "Can I help you?",
  "language_code": "en"
}

Example response

1
2
3
4
5
6
{
  "language_code": "en",
  "message": "Can I help you?",
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T11:31:36.042Z"
}

You can add a chat conversation starter for the user:

POST /api/v5/users/<user_id>/chat_conversation_starters

You need to define the message and language_code attributes as a payload.

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 400 if the user already has a conversation starter with given language_code
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user

Update a chat conversation starter

Example request that updates the chat conversation starter for user

1
PATCH https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters/fi

1
2
3
{
  "message": "Kuinka voin auttaa sinua?"
}

You may update the editable attributes of your user's chat conversation starters.

PUT /api/v5/users/<user_id>/chat_conversation_starters/<language_code>

PATCH /api/v5/users/<user_id>/chat_conversation_starters/<language_code>

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if conversation starter was not found

Remove a chat conversation starter from user

1
DELETE https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters/en

You can remove a chat conversation starter from user:

DELETE /api/v5/users/<user_id>/chat_conversation_starters/<language_code>

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if conversation starter was not found

Chat reply suggestions

Chat messages may have reply suggestions tied to them. These are handy e.g. when creating a Bot user which only suggests replies for user by analyzing the corresponding message. Chat reply suggestions are shown to chat agents in real time in the giosg Console user interface. A chat reply suggestion object consists:

Attribute Format Editable Description
id UUID/string read-only ID of the reply suggestion
suggestion string required The message of this suggestion.
relevancy_score float optional How "good" reply suggestion is this for the message. The value should be a float between 0 and 1 or null.
created_by_user_id UUID/string read-only ID of the user which added this reply suggestion.
created_by_user object read-only User which added this reply suggestion.
updated_by_user_id UUID/string read-only ID of the user which updated this reply suggestion.
updated_by_user object read-only Last user which updated this reply suggestion.
room_id UUID read-only ID of the room where the chat takes place.
chat_id UUID read-only ID of the chat.
message_id UUID read-only ID of the chat message which this suggestion is tied to.
organization_id UUID read-only ID of the user's organization.
created_at datetime read-only When the reply suggestion was created.
updated_at datetime read-only When the this reply suggestion was updated.

List reply suggestions of a chat

You can get a paginated collection of all the reply suggestions for the chat:

GET /api/v5/users/<user_id>/chats/<chat_id>/reply_suggestions

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Or alternatively you may list user's chat reply suggestions for a routed chat, to which the use may not have joined yet:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>/reply_suggestions

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if the related chat does not exist or it is not routed to the user

These endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

List reply suggestions of a message

1
GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/messages/cb2f4b33-cc1c-11e6-97e1-f45c89c72de3/reply_suggestions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/messages/cb2f4b33-cc1c-11e6-97e1-f45c89c72de3/reply_suggestions?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "11d9bd6b-cc1d-11e6-8000-f45c89c72de3",
      "suggestion": "Yes we do have those products.",
      "relevancy_score": 0.6,
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "is_bot": false
      },
      "room_id": "babff2ca-cc1d-11e6-962b-f45c89c72de3",
      "chat_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b7",
      "message_id": "cb2f4b33-cc1c-11e6-97e1-f45c89c72de3",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T11:31:36.042Z"
    }
  ]
}

You can get a paginated collection of all the reply suggestions for the corresponding message:

GET /api/v5/users/<user_id>/chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if the user was not a member of the chat

Or alternatively you may list user's chat reply suggestions for a routed chat, to which the use may not have joined yet:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if the related chat does not exist or it is not routed to the user

These endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

Update a chat reply suggestion

You may update the editable attributes of your reply suggestions:

PUT/PATCH /api/v5/users/<user_id>/chats/<chat_id>/messages/<message_id>/reply_suggestions/<reply_suggestion_id>

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if message was not found
  • 404 if reply suggestion was not found
  • 404 if the user was not a member of the chat

Or alternatively you may list user's chat reply suggestions for a routed chat, to which the use may not have joined yet:

PUT/PATCH /api/v5/users/<user_id>/routed_chats/<chat_id>/messages/<message_id>/reply_suggestions/<reply_suggestion_id>

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if message was not found
  • 404 if reply suggestion was not found
  • 404 if the related chat does not exist or it is not routed to the user

Add a chat reply suggestion for a message

You can add a chat reply suggestion for the message:

POST /api/v5/users/<user_id>/chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if chat was not found
  • 404 if message was not found
  • 404 if the user was not a member of the chat

Or alternatively you may list user's chat reply suggestions for a routed chat, to which the use may not have joined yet:

POST /api/v5/users/<user_id>/routed_chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the user
  • 404 if message was not found
  • 404 if the related chat does not exist or it is not routed to the user

You need to define the suggestion attribute as a payload. If you pass relevancy_score with float value, then it will be shown in console.