Message events

Returns chat message events filtered by message_types (OR). Unlike generic events, there is no events[] filter and no value sets.

category / action are fixed for this dataset and omitted from each row.

How-to: Listing chat message events.

Same collector_created_at window, sort (collector_created_at, then event_id), and cursor rules as list events.

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. Page size is 250. Walk adjacent windows and paginate each one for a longer range. 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.

Endpoint

POST	https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/message-events

Payload (first page)

Attribute	Type	Description
start	datetime	Inclusive start of collector_created_at. Required.
end	datetime	Inclusive end of collector_created_at. Required. Max window: 2 days.
message_types	array	At least one non-empty string (OR match on message_type). Almost always ["msg"]; add join / leave if you need presence events. See Message types.
order	string	"desc" (default) or "asc". Sort is collector_created_at, then event_id.

Optional case management integration flags are off by default and are not required to list messages.

Payload (next page)

Attribute	Type	Description
cursor	string	next_cursor from the previous response. When set, every other body field is ignored (window, message_types, order, and case flags included).

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

Response

Attribute	Type	Description
results	array	Message objects. Columns: Result object.
next_cursor	string | null	Next page token, or null.

Errors: 400 for invalid window/message_types/cursor; 401/403 for auth; 503 when the analytics backend is unavailable.

---

Result object

Every matching row includes these fields. category and action are always chat_message / added on this dataset and are omitted from the response.

Field	Type	Description
collector_created_at	datetime	Event time. Used for windows, sort, and pagination. Functionally the same as timestamp (possibly a few ms apart).
timestamp	datetime	Event time. Functionally the same as collector_created_at. Both exist for legacy reasons; a later API will use timestamp only.
event_version	integer	Event schema version.
event	string	Event name.
event_id	uuid	Unique event id.
organization_id	uuid	Owner organization.
organization_timezone	string	Organization timezone.
organization_name	string	Organization name.
vendor	string	Event vendor.
label	string	Event label.
rooms	array of uuid	Room ids.
teams	array of uuid	Team ids.
visitor_id	string | null	Visitor id.
user_id	uuid | null	User id.
session_id	uuid | null	Visitor session id.
message_id	string | null	Chat message id.
message_type	string | null	Message type. See Message types.
sender_id	string | null	Sender id.
sender_type	string | null	Sender type.
chat_session_id	string | null	Chat session id.
chat_session_type	string | null	Chat session type.

case_number and case_id are not on the default listing. They appear only with the case management integration flag attach_case_data.

---

Message types

Almost always use "msg" only — normal visitor/agent chat text (including messages with file attachments). The other two types you might add are join and leave (someone entered or left the chat). Everything else is rarely needed for reporting.

message_types matches the stored message_type column. Those values are the same serialized type strings the Chat API uses. There is no "file" type — attachments stay on "msg".

message_type	Meaning
msg	Normal visitor/agent chat text (including messages with file attachments)
join	Someone joined the chat
leave	Someone left the chat
autosuggest	Autosuggest
shoppingcart_locked	Shopping cart locked
action	Attachment action
system	System
interaction_submit	Interaction submitted
call_request	Call request
call_ended	Call ended
deleted	Message deleted
tag_created	Tag created
tag_deleted	Tag deleted
shoppingcart_item_added	Shopping cart item added
shoppingcart_item_removed	Shopping cart item removed
visitor_data_deleted	Visitor data deleted
queue_overflow	Queue overflow
queue_allowed_overflow	Queue allowed overflow
telephony_request	Telephony request
click2call_request	Click2call request
internal_note	Internal note (agent-only)
internal_email	Internal email

---

Case management integration

Special-case flags

attach_case_data and show_only_messages_with_case exist for case management integrations. They are optional, default false, and are not part of the default listing contract. Leave them unset unless you need to join chat messages to a giosg case.

How-to: Listing chat message events — Case management integration. Case event fields: Case management events.

Attribute	Type	Description
attach_case_data	boolean	If true, each row includes case_number and case_id (null if none). Default false.
show_only_messages_with_case	boolean	If true, return only messages that can be linked to a case. Default false. Applied before pagination.

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

The 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.

When attach_case_data is true, each row also includes:

Field	Type	Description
case_number	string | null	Linked case number, or null if none.
case_id	string | null	Linked case UUID, or null if none.