Skip to content

Add docs related to reporting data export #267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
themuhammad2 merged 1 commit into from
Jun 10, 2025
Merged

Add docs related to reporting data export #267

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
286 changes: 284 additions & 2 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1492,6 +1492,288 @@ paths:
$ref: "#/components/schemas/away_status_reason"
'401':
"$ref": "#/components/responses/Unauthorized"
"/export/reporting_data/enqueue":
post:
summary: Enqueue a new reporting data export job
tags: [Export]
Copy link
Contributor

@steve-henry steve-henry Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this tag achieves the grouping rather than needing to nest the resource name.

Copy link
Contributor Author

@themuhammad2 themuhammad2 Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is for grouping.

parameters:
- name: Intercom-Version
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [dataset_id, attribute_ids, start_time, end_time]
properties:
dataset_id:
type: string
example: conversation
attribute_ids:
type: array
items:
type: string
example: [conversation.id, conversation.first_user_conversation_part_created_at]
start_time:
type: integer
format: int64
example: 1717490000
end_time:
type: integer
format: int64
example: 1717510000
responses:
'200':
description: Job enqueued successfully
content:
application/json:
schema:
type: object
properties:
job_identifier:
type: string
example: job1
status:
type: string
example: pending
download_url:
type: string
download_expires_at:
type: string
'400':
description: Bad request (e.g. validation errors)
content:
application/json:
examples:
No dataset_id:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: bad_request
message: "'dataset_id' is a required parameter"
Invalid dataset_id:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: bad_request
message: imaginary is not a valid dataset_id
No attribute_ids:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: bad_request
message: "'attribute_ids' is a required parameter"
Empty attribute_ids:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: bad_request
message: attribute_ids must contain at least one attribute_id
Non array attribute_ids:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: bad_request
message: "'attribute_ids' not an array must be of type Array"
Invalid attribute_ids:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: bad_request
message: "attribute_ids invalid for conversation dataset: non_existent"
schema:
"$ref": "#/components/schemas/error"
'401':
description: Unauthorized
content:
application/json:
examples:
Unauthorized:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: unauthorized
message: Access Token Invalid
schema:
"$ref": "#/components/schemas/error"
'429':
description: Too many jobs in progress
content:
application/json:
examples:
Unauthorized:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: rate_limit_exceeded
message: Exceeded rate limit of 5 pending reporting dataset export jobs
schema:
"$ref": "#/components/schemas/error"
"/export/reporting_data/{job_identifier}":
get:
summary: Get export job status
tags: [Export]
parameters:
- name: Intercom-Version
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
- name: app_id
in: query
description: The Intercom defined code of the workspace the company is associated
to.
required: true
schema:
type: string
- name: client_id
in: query
required: true
schema:
type: string
- name: job_identifier
description: Unique identifier of the job.
in: query
required: true
schema:
type: string
responses:
'200':
description: Job status returned successfully
content:
application/json:
examples:
With complete status:
value:
job_identifier: job1
status: complete
download_url: ''
download_expires_at: ''
With failed status:
value:
job_identifier: job1
status: failed
download_url: ''
download_expires_at: ''
schema:
type: object
properties:
job_identifier:
type: string
status:
type: string
download_url:
type: string
download_expires_at:
type: string
'404':
description: When job not found
content:
application/json:
examples:
Not found:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: not_found
message: "Export job not found for identifier: job1"
schema:
"$ref": "#/components/schemas/error"
"/export/reporting_data/get_datasets":
get:
Comment on lines +1693 to +1694
Copy link
Contributor

@steve-henry steve-henry Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Usually wouldn't have get in the path as well as being the HTTP method.

Copy link
Contributor

@steve-henry steve-henry Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But if it matches the behaviour we can update the docs for now. While it's in Unstable though we could change to align with other API endpoints.

Copy link
Contributor Author

@themuhammad2 themuhammad2 Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@steve-henry yeah that's a good point we shouldn't have get in the name of the resource according to REST conventions. It should have been like

GET /export/reporting_data/datasets

Copy link
Contributor

@steve-henry steve-henry Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I think that would be clearer and more consistent with the rest of the APIs

summary: List available datasets and attributes
parameters:
- name: Intercom-Version
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
tags: [Export]
responses:
'200':
description: List of datasets
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: list
data:
type: array
items:
type: object
properties:
id:
type: string
example: conversation
name:
type: string
example: Conversation
description:
type: string
example: "Conversation-level details: status, channel, assignee."
default_time_attribute_id:
type: string
example: conversation.first_user_conversation_part_created_at
attributes:
type: array
items:
type: object
properties:
id:
type: string
example: conversation.id
name:
type: string
example: Conversation ID
"/download/reporting_data/{job_identifier}":
get:
summary: Download completed export job data
tags: [Export]
parameters:
- name: Intercom-Version
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
- name: app_id
in: query
required: true
schema:
type: string
- name: job_identifier
in: query
required: true
schema:
type: string
responses:
'200':
description: Export file downloaded
'404':
description: When job not found
content:
application/json:
examples:
Not found:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: not_found
message: "Export job not found for identifier: job1"
schema:
"$ref": "#/components/schemas/error"
"/help_center/collections":
get:
summary: List all collections
Expand Down Expand Up @@ -9194,8 +9476,8 @@ paths:
operationId: getWhatsAppMessageStatus
description: |
Retrieves statuses of messages sent from the Outbound module. Currently, this API only supports WhatsApp messages.


This endpoint returns paginated status events for WhatsApp messages sent via the Outbound module, providing
information about delivery state and related message details.
responses:
Expand Down