Skip to content

Listing chat message events

Fetch chat message rows by message_type. This is a different dataset from generic events (/events + events[]).

Base URL: https://api.giosg.com/api/objectives/v1/orgs/<organization_id>

Authentication

For server-to-server calls, authenticate with a user API token: Authorization: Token <api token>. OAuth2 access tokens use Authorization: Bearer <access token> instead. How to obtain and use each: Get API token. The URL organization_id must match the authenticated organization.

Two-day window

Each request covers at most 2 days. Pages are 250 rows. To cover a longer range, walk adjacent windows and paginate each one. If cursor is sent, every other body field is ignored. Windows use collector_created_at; that field and timestamp are functionally the same (they may differ by milliseconds). Both exist for legacy reasons — a later API will use timestamp only.

Basic request

For typical chat reporting, filter with "msg" only — that is normal visitor/agent chat text. File attachments are still "msg".

1
2
3
4
5
6
7
8
9
POST /message-events
Authorization: Token <api token>
Content-Type: application/json

{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T23:59:59Z",
  "message_types": ["msg"]
}

The other two types you might add are "join" and "leave" (someone entered or left the chat):

1
2
3
4
5
{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T23:59:59Z",
  "message_types": ["msg", "join", "leave"]
}

The rest of the types are rarely needed. Full list: Message types.

Pagination

Same pattern as generic events — send only the cursor. Every other body field is ignored (window, message_types, order, and case flags included):

1
{ "cursor": "<next_cursor>" }

Full request/response tables: Message events reference. Columns on each row: Result object.

Case management integration

Special-case flags

Listing chat messages does not require a case. The two flags below are optional case management integration support (default false). Use them only when you need to join messages to a giosg case. The usual listing request above is enough for chat reporting.

Flag Effect
attach_case_data Add case_number and case_id on each row (null if none).
show_only_messages_with_case Keep only messages that can be linked to a case (applied before the page is filled). 
1
2
3
4
5
6
{
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-01-02T23:59:59Z",
  "message_types": ["msg"],
  "attach_case_data": true
}

Join uses a case-management activity_created event for the chat (not funnel step_started / step_ended). Matching looks from 30 days before your query start through end. The newest match for a chat wins. Field tables for the extra keys: Case management integration.