Conversational Reporting HTTP API

Overview¶

With Conversational Reporting, you can create "Conversational reporting cards" that can be monitored through the Giosg System. This system will send out a notification to the selected chhannels and users when the target has been reached or after configured reporting period has passed.

Example report card

Conversational reports¶

The conversational report card is a report that is delivered to you periodically or when configured target treshold is met. It can be sent to the user via email or new Giosg.

List all conversational reports¶

Endpoint:

1	`GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/reports/`

Response¶

The response will be a list with objects like:

Attribute	Type	Description
`id`	uuid	A unique UUID for every object
`organization_id`	uuid	The unique UUID for your company
`workflow`	uuid	The unique UUID for the workflow this report is attached to or `null`
`name`	string	The name of the
`is_target_enabled`	boolean	A flag to set whether the target is enabled or not. If `True` report will be send immediately when the reporting threshold is met.
`reporting_threshold`	float	The threshold which the target should be considered met and the report should be sent. Can be `null` if no `is_target_enabled` is False.
`reporting_metric_id`	string	The metric ID from `/api/objectives/v1/orgs/<organization_id>/available_metrics` endpoint. See "Available metrics" below
`reporting_query_args`	Object	The query arguments to be used in the metric query. This is a object like `{"goal_id": "ff8c94e0-9d89-11e9-a62f-0242ac110003"}` or `null`. Required attributes can be optained from "Available metrics" endpoint in `filters` attribute of the metric.
`reporting_count_field_type`	string	What should be counted, can be `event_id`, `session_id`, `visitor_id` or `null` if the count field is not applicable to this metric, for example "Unique visitors" would always use `visitor_id` automatically.
`reporting_period`	string	The period("P1D", "P1W", "P1M") in ISO 8601 duration format which this reporting should be tracked. Report will include data from this timeperiod.
`notification_period`	string	The period("P1D", "P1W", "P1M") in ISO 8601 duration format which snapshots should be sent.
`reporting_bound`	string	Whether the target should be considered reached when the current value is `ABOVE` or `BELOW`. Can be `null` if no target specified and `is_target_enabled` is False.
`are_notifications_active`	boolean	A flag to set notifications on or off.
`report_active_from`	date/time	(Optional) Timestamp when report will be activated in ISO-8601 format, eg. `2021-04-01T10:10:57.242Z`
`report_active_until`	date/time	(Optional) Timestamp when report will be activated in ISO-8601 format, eg. `2021-04-01T10:10:57.242Z`
`modified_at`	date/time	Last modification time in ISO-8601 format, eg. `2021-04-01T10:10:57.242Z`
`created_at`	date/time	Report creation time in ISO-8601 format, eg. `2021-04-01T10:10:57.242Z`
`query_timezone`	string	The timezone in which the query should be executed, for example "Europe/Helsinki". Defaults to `UTC`
`notification_settings`	List of strings	List of ID's of notifications settings connected to this report. If no notifications are set, this will be an empty list.
`notification_error_log`	List of strings	List of error messages that have occurred when sending notifications for this report. If no errors have occurred, this will be an empty list.

Create a new conversational report¶

With this example payload we create a report that will send a notification to the user when 100 unique visitors have reached a selected goal in a room within a period of 1 week.

Endpoint:

1	`POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/reports/`

Payload:

{
    "name": "Unique visitors whom reached a goal in room",
    "workflow": null,
    "reporting_query": null,
    "reporting_query_version": 2,
    "reporting_field": null,
    "reporting_metric_id": "goals_matched_in_room",
    "reporting_count_field_type": "visitor_id",
    "reporting_query_args": {
        "goal_id": "d0443dda-0577-4846-b0ef-133262fdca97",
        "room_id": "982e8fd1-0173-4f38-8a65-644c2914a369"
    },
    "reporting_period": "P1W",
    "notification_period": "P1W",
    "notification_settings": [
        "6144faa8-7e13-49ac-84e2-4b4d0537777f"
    ],
    "are_notifications_active": true,
    "report_active_from": null,
    "report_active_until": null,
    "query_timezone": "UTC",
    "is_target_enabled": true,
    "reporting_bound": "ABOVE",
    "reporting_threshold": 100
}

Update a conversational report¶

Endpoint:

PATCH/PUT https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/reports/<report_id>

Payload:

{
    "name": "My updated report name",
    "is_target_enabled": false,
}

Remove a conversational report¶

Endpoint:

DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/reports/<report_id>

Execute a conversational report query to get the current value¶

Executes the metric query and returns the current value of the report.

Endpoint:

GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/reports/<report_id>/realtime_query

Response¶

Attribute	Type	Description
`selected_period`	string	Selected period in ISO 8601 format, for example `P1W`.
`timespan_requested`	string	Time span in string format, for example: `"2025-06-04T00:00:00+00:00 - 2025-06-04T11:14:46.423205+00:00"`
`value`	float	Current value, for example: `1233`
`reporting_threshold`	float	Current reporting threshold if set, for example: `3000`
`reporting_bound`	string	Current reporting bound, either `ABOVE` or `BELOW` if set. `null` if not set

Test a conversational report¶

Executes the metric query and returns the current value of the report and in addition sends the reports to notification channels if they are set and triggers reports if target threshold is met.

Endpoint:

GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/reports/<report_id>/test_query

Response¶

Attribute	Type	Description
`selected_period`	string	Selected period in ISO 8601 format, for example `P1W`.
`timespan_requested`	string	Time span in string format, for example: `"2025-06-04T00:00:00+00:00 - 2025-06-04T11:14:46.423205+00:00"`
`value`	float	Current value, for example: `1233`
`reporting_threshold`	float	Current reporting threshold if set, for example: `3000`
`reporting_bound`	string	Current reporting bound, either `ABOVE` or `BELOW` if set. `null` if not set

Available metrics¶

This endpoint returns a list of available metrics that can be used in the conversational reports. The metrics are grouped by category and each metric has a unique ID, name, description and available filters. Endpoint:

GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/available_metrics

Response¶

Attribute	Type	Description
`metric_id`	string	ID of the metric.
`name`	string	Human readable name of the metric
`category`	string	Category of the metric
`description`	string	Human readable longer description of the metric.
`filters`	Array of objects	If metric requires some filters to be set, this will be a list of objects with `type`, `name` and `display_name` fields.
`count_fields_available`	List of string	List of available counting methods like `event_id`, `session_id` and `visitor_id`. Can also be empty array if not applicable.

Example response:

[
  {
    "metric_id": "total_goal_matched",
    "name": "Any goal matched",
    "category": "goal",
    "description": "Number of times any goal was matched",
    "filters": [],
    "count_fields_available": [
      "event_id",
      "session_id",
      "visitor_id"
    ]
  },
  {
    "metric_id": "goals_matched",
    "name": "Goal matched",
    "category": "goal",
    "description": "Number of times the goal matched",
    "filters": [
      {
        "type": "goal_id",
        "name": "goal_id",
        "display_name": "Goal"
      }
    ],
    "count_fields_available": [
      "event_id",
      "session_id",
      "visitor_id"
    ]
  }
]

Details of each metric can fetched with GET request to endpoint https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/available_metrics/<metric_id>.

Notification¶

Endpoint:

GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications

Response¶

The response will be a list with objects like:

Attribute	Type	Description
`bar`	list	Shows all settings for the BAR channels set for this business target
`slack`	list	Shows all settings for the Slack channels set for this business target
`email`	list	Shows all settings for the Email notifications set for this business target

Giosg group (BAR)¶

Get all Giosg group settings¶

Endpoint:

GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/bar

Response¶

The response will be a list with objects like:

Attribute	Type	Description
`id`	uuid	A unique UUID for every object
`organization_id`	uuid	The organization UUID for the organization owning this setting
`last_notification_sent`	date/time	When is the last notification sent to the channel in ISO-8601 format, eg. `2021-04-01T10:10:57.242Z`
`name`	string	Name for the notification setting
`is_notification_active`	boolean	Flag to enable or disable these notifications
`channel_id`	uuid	The UUID for the chat within BAR to gather the Reporting Cards

Create a notification to Giosg group¶

Endpoint:

POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/bar

{
    "name": "Reporting channel",
    "target": "<target_uuid>",
    "channel_id": "<channel_uuid>"
}

Update a Giosg group notification setting¶

Endpoint:

PATCH https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/bar/<setting_id>

Payload:

{
    "name": "<altered_name>",
    "target": "<altered_target_uuid>",
    "channel_id": "<altered_channel_uuid>"
}

Remove a Giosg group notification setting¶

Endpoint:

DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/bar/<setting_id>

Email¶

Get all email settings¶

Endpoint:

GET https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/email

Response¶

The response will be a list with objects like:

Attribute	Type	Description
`id`	uuid	A unique UUID for every object
`organization_id`	uuid	The organization UUID for the organization owning this setting
`last_notification_sent`	date/time	When is the last notification sent to the channel in ISO-8601 format, eg. `2021-04-01T10:10:57.242Z`
`name`	string	Name for the notification setting
`is_notification_active`	boolean	Flag to enable or disable these notifications
`email`	string	Gets the email registered in this setting
`is_bundleable`	boolean	Flag to enable or disable bundling of emails

Set a notification to email¶

Endpoint:

POST https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/email

{
    "target": "<target_uuid>",
    "email": "<string>",
    "is_bundleable": "<bool>",
}

Update an email notification setting¶

Notice

Sub-items can be patched independently in subsequent requests.

Endpoint:

PATCH https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/email/<setting_id>

{
    "email": "<altered_string>",
    "is_bundleable": "<altered flag>",
}

Remove an email notification setting¶

Endpoint:

DELETE https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/notifications/email/<setting_id>