diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 605b1b06..876bc268 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -18571,6 +18571,8 @@ paths: {% admonition type="warning" name="Conversation attributes removed" %} Conversation attributes are no longer returned by this endpoint. Calling without a `model` parameter no longer includes them in the response, and `model=conversation` returns a `422` error. Use [GET /conversations/attributes](/docs/references/preview/rest-api/api.intercom.io/conversations-attributes/listconversationattributes) instead. {% /admonition %} + + Requires the `read_users_companies` or `read_write_users` OAuth scope. responses: '200': description: Successful response @@ -18810,6 +18812,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 2f0c1e7a-5a3d-43a1-9f61-6b2d1c4e8a90 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" '422': @@ -18836,7 +18845,10 @@ paths: tags: - Data Attributes operationId: createDataAttribute - description: You can create a data attributes for a `contact` or a `company`. + description: | + You can create a data attributes for a `contact` or a `company`. + + Requires the `write_attributes` OAuth scope. responses: '200': description: Successful @@ -18863,7 +18875,7 @@ paths: schema: "$ref": "#/components/schemas/data_attribute" '400': - description: Too few options for list + description: Bad Request content: application/json: examples: @@ -18920,6 +18932,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8d0a4f23-0b7e-4c2e-9a68-1d5f3c7b2e41 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Relationship data type: + value: + type: error.list + request_id: 3a6b9c14-7e52-4d08-b1f3-c8a0e5d27b36 + errors: + - code: parameter_invalid + message: Data Type isn't an option schema: "$ref": "#/components/schemas/error" requestBody: @@ -18983,10 +19016,17 @@ paths: tags: - Data Attributes operationId: updateDataAttribute - description: "\nYou can update a data attribute.\n\n> \U0001F6A7 Updating the - data type is not possible\n>\n> It is currently a dangerous action to execute - changing a data attribute's type via the API. You will need to update the - type via the UI instead.\n" + description: | + + You can update a data attribute. + + > 🚧 Updating the data type is not possible + > + > It is currently a dangerous action to execute changing a data attribute's type via the API. You will need to update the type via the UI instead. + + You can also send this request with `PATCH`; it behaves the same as `PUT`. + + Requires the `write_attributes` OAuth scope. responses: '200': description: Successful @@ -19071,6 +19111,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 5c71e2d8-9a04-4b36-8e57-f2b6c3a91d4e + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: @@ -21474,7 +21521,7 @@ paths: **Metadata behaviour** - - We currently limit the number of tracked metadata keys to 10 per event. Once the quota is reached, we ignore any further keys we receive. The first 10 metadata keys are determined by the order in which they are sent in with the event. + - We currently limit the number of tracked metadata keys to 20 per event name. The limit counts every key ever recorded for that event name, not the keys in a single request, so it is reached cumulatively as you send more events with the same name. Once the quota is reached, we ignore any further keys we receive. The keys that count towards the quota are determined by the order in which they are sent in with the event. - It is not possible to change the metadata keys once the event has been sent. A new event will need to be created with the new keys and you can archive the old one. - There might be up to 24 hrs delay when you send a new metadata for an existing event. @@ -21492,9 +21539,46 @@ paths: - Event lists containing duplicate events will have those duplicates ignored. - Server errors will return a `500` response code and may contain an error message in the body. + Requires the `write_events` OAuth scope. + responses: '202': description: successful + '400': + description: Bad Request + content: + application/json: + examples: + Missing a required field: + value: + type: error.list + request_id: 5d0c8e27-3a91-4f6b-b2d4-7e18c9a06f53 + errors: + - code: parameter_not_found + message: missing data parameter + Null event name: + value: + type: error.list + request_id: 9b1f3c40-5d2a-4e7b-8c16-a3d9e0f51b24 + errors: + - code: parameter_not_found + message: missing event_name parameter + Metadata is not an object: + value: + type: error.list + request_id: c4e07a19-62b8-4d35-91fa-70e2b6c38d5f + errors: + - code: type_mismatch + message: event metadata must be an object + Bad type parameter: + value: + type: error.list + request_id: 71d3b8e5-0c46-4a92-bf27-5e8a1d60c93b + errors: + - code: parameter_invalid + message: bad type parameter + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -21507,6 +21591,62 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 0e5a9c62-3b71-4f84-ad19-6c7e2b05f4a8 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + User not found: + value: + type: error.list + request_id: 2b8f6d13-47ca-4e09-9d52-f1a63c0e78b5 + errors: + - code: not_found + message: User Not Found + Lead not found: + value: + type: error.list + request_id: 6a2c91e7-8d40-4b15-a3f6-9e0b72d5c814 + errors: + - code: not_found + message: Lead Not Found + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Event name too long: + value: + type: error.list + request_id: 4f1e7b03-9c25-4d6a-82be-13a0c5d9e672 + errors: + - code: parameter_invalid + message: invalid event name length; use up to 100 characters + Metadata too long: + value: + type: error.list + request_id: 8c40a5f2-1e69-4730-b8d4-27f5e1c06a93 + errors: + - code: parameter_invalid + message: invalid event metadata length; use up to 65535 characters + Invalid timestamp: + value: + type: error.list + request_id: d57b2e91-6043-4c8f-a12d-3b9e07f45c68 + errors: + - code: parameter_invalid + message: invalid timestamp format; please use seconds since epoch schema: "$ref": "#/components/schemas/error" requestBody: @@ -21550,12 +21690,46 @@ paths: required: - email additionalProperties: false + - title: anonymous_id query parameter + properties: + anonymous_id: + type: string + required: + - anonymous_id + additionalProperties: false - name: type in: query required: true - description: The value must be user + description: The value must be `user` or `lead`. schema: type: string + enum: + - user + - lead + - name: per_page + in: query + required: false + description: The number of events to return per page. + schema: + type: integer + - name: since + in: query + required: false + description: Only return events created after this time, as a Unix timestamp + in milliseconds. Take the value from the `since` link in the `pages` object + of a previous response. + schema: + type: integer + format: int64 + - name: before + in: query + required: false + description: Only return events created before this time, as a Unix timestamp + in milliseconds. Take the value from the `next` link in the `pages` object + of a previous response. + schema: + type: integer + format: int64 - name: summary in: query required: false @@ -21565,18 +21739,25 @@ paths: tags: - Data Events operationId: lisDataEvents - description: "\n> \U0001F6A7\n>\n> Please note that you can only 'list' events - that are less than 90 days old. Event counts and summaries will still include - your events older than 90 days but you cannot 'list' these events individually - if they are older than 90 days\n\nThe events belonging to a customer can be - listed by sending a GET request to `https://api.intercom.io/events` with a - user or lead identifier along with a `type` parameter. The identifier parameter - can be one of `user_id`, `email` or `intercom_user_id`. The `type` parameter - value must be `user`.\n\n- `https://api.intercom.io/events?type=user&user_id={user_id}`\n- - `https://api.intercom.io/events?type=user&email={email}`\n- `https://api.intercom.io/events?type=user&intercom_user_id={id}` - (this call can be used to list leads)\n\nThe `email` parameter value should - be [url encoded](http://en.wikipedia.org/wiki/Percent-encoding) when sending.\n\nYou - can optionally define the result page size as well with the `per_page` parameter.\n" + description: | + + > 🚧 + > + > Please note that you can only 'list' events that are less than 90 days old. Event counts and summaries will still include your events older than 90 days but you cannot 'list' these events individually if they are older than 90 days + + The events belonging to a customer can be listed by sending a GET request to `https://api.intercom.io/events` with a user or lead identifier along with a `type` parameter. The identifier parameter can be one of `user_id`, `email`, `intercom_user_id` or `anonymous_id`. The `type` parameter value must be `user` or `lead`. + + - `https://api.intercom.io/events?type=user&user_id={user_id}` + - `https://api.intercom.io/events?type=user&email={email}` + - `https://api.intercom.io/events?type=user&intercom_user_id={id}` (this call can be used to list leads) + + When `type` is `lead`, a `user_id` you send is matched against the lead's anonymous id instead. + + The `email` parameter value should be [url encoded](http://en.wikipedia.org/wiki/Percent-encoding) when sending. + + You can optionally define the result page size as well with the `per_page` parameter. + + Requires the `read_events` or `write_events` OAuth scope. responses: '200': description: Successful response @@ -21621,6 +21802,48 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: b3a71f58-2c09-4e6d-91b7-4f8c5e2a0d63 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + User not found: + value: + type: error.list + request_id: 5e9c0b24-71f3-4a86-bd50-2c7a1e638f49 + errors: + - code: not_found + message: User Not Found + Lead not found: + value: + type: error.list + request_id: 93f6d205-4b18-47ea-8c31-6d0b5a7e2f14 + errors: + - code: not_found + message: Lead Not Found + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Unsupported type: + value: + type: error.list + request_id: 1d4e8a07-5f62-4390-b7c8-0a2e9b16d35f + errors: + - code: parameter_invalid + message: unsupported type [company] schema: "$ref": "#/components/schemas/error" "/events/summaries": @@ -21634,12 +21857,43 @@ paths: tags: - Data Events operationId: dataEventSummaries - description: "Create event summaries for a user. Event summaries are used to - track the number of times an event has occurred, the first time it occurred - and the last time it occurred.\n\n" + description: | + Create event summaries for a user. Event summaries are used to track the number of times an event has occurred, the first time it occurred and the last time it occurred. + + Identify the user with one of `id`, `user_id` or `email`. If more than one is sent, `id` is used first, then `user_id`, then `email`. + + Requires the `write_events` OAuth scope. responses: '200': description: successful + '400': + description: Bad Request + content: + application/json: + examples: + No user identifier: + value: + type: error.list + request_id: 7c1b93a6-0d52-4e87-96f4-2a8e5c0b7d31 + errors: + - code: missing_parameter + message: No user identifier found + No summaries: + value: + type: error.list + request_id: a04f6e82-3c97-4b15-8d26-f1b7093c5e48 + errors: + - code: missing_parameter + message: No summaries found + Summary field has the wrong type: + value: + type: error.list + request_id: e82d47b1-6a09-4c35-b7f1-305c9e2a6d70 + errors: + - code: parameter_invalid + message: 'Value: many not of type Integer' + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -21652,6 +21906,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 36b0e95c-7d41-4a28-83ef-9c5a1b204e76 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + User not found: + value: + type: error.list + request_id: 58c7a230-9e16-4b74-a0d3-7f2e6c1b9d45 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -21670,25 +21945,26 @@ paths: tags: - Data Export operationId: createDataExport - description: "To create your export job, you need to send a `POST` request to - the export endpoint `https://api.intercom.io/export/content/data`.\n\nThis - endpoint exports **message delivery and engagement data** for outbound content - (Emails, Posts, Custom Bots, Surveys, Tours, Series, and more). The exported - data includes who received each message, when they received it, and how they - engaged with it (opens, clicks, replies, completions, dismissals, unsubscribes, - and bounces). It does not export raw message or conversation content.\n\nThe - only parameters you need to provide are the range of dates that you want exported.\n\n>\U0001F6A7 - Limit of one active job\n>\n> You can only have one active job per workspace. - You will receive a HTTP status code of 429 with the message Exceeded rate - limit of 1 pending message data export jobs if you attempt to create a second - concurrent job.\n\n>❗️ Updated_at not included\n>\n> It should be noted that - the timeframe only includes messages sent during the time period and not messages - that were only updated during this period. For example, if a message was updated - yesterday but sent two days ago, you would need to set the created_at_after - date before the message was sent to include that in your retrieval job.\n\n>\U0001F4D8 - Date ranges are inclusive\n>\n> Requesting data for 2018-06-01 until 2018-06-30 - will get all data for those days including those specified - e.g. 2018-06-01 - 00:00:00 until 2018-06-30 23:59:99.\n" + description: | + To create your export job, you need to send a `POST` request to the export endpoint `https://api.intercom.io/export/content/data`. + + This endpoint exports **message delivery and engagement data** for outbound content (Emails, Posts, Custom Bots, Surveys, Tours, Series, and more). The exported data includes who received each message, when they received it, and how they engaged with it (opens, clicks, replies, completions, dismissals, unsubscribes, and bounces). It does not export raw message or conversation content. + + The only parameters you need to provide are the range of dates that you want exported. The range cannot be longer than 90 days. + + >🚧 Limit of two active jobs + > + > You can only have two active jobs per workspace. You will receive a HTTP status code of 429 with the message Exceeded rate limit of 2 pending content data export jobs if you attempt to create a third concurrent job. + + >❗️ Updated_at not included + > + > It should be noted that the timeframe only includes messages sent during the time period and not messages that were only updated during this period. For example, if a message was updated yesterday but sent two days ago, you would need to set the created_at_after date before the message was sent to include that in your retrieval job. + + >📘 Date ranges are inclusive + > + > Requesting data for 2018-06-01 until 2018-06-30 will get all data for those days including those specified - e.g. 2018-06-01 00:00:00 until 2018-06-30 23:59:99. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful @@ -21703,6 +21979,105 @@ paths: download_expires_at: '' schema: "$ref": "#/components/schemas/data_export" + '400': + description: Bad Request + content: + application/json: + examples: + Missing date: + value: + type: error.list + request_id: 1a7c0e36-b249-4d85-96f1-5c03e7a2b48d + errors: + - code: bad_request + message: "'created_at_after' is a required parameter" + Date is not an integer: + value: + type: error.list + request_id: 62e9b0a4-38c7-4f51-bd96-07a1c4e5f283 + errors: + - code: bad_request + message: "'created_at_before: yesterday' must be of type Integer" + Dates out of order: + value: + type: error.list + request_id: f3081b57-4c2a-49e6-85d0-2b7a6e91c340 + errors: + - code: bad_request + message: created_at_after is greater than created_at_before + Unknown parameter: + value: + type: error.list + request_id: 9d2f4c81-706b-4e39-a5c7-13e08b6d2f95 + errors: + - code: bad_request + message: "bad 'created_at' parameter" + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 4b6e1d09-85f2-4a37-9c60-d1a37e204b58 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 0c93a7e5-1f48-4b62-83da-6e5c702f194b + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Range too long: + value: + type: error.list + request_id: 7e50c938-2a61-4df7-b084-c9f2e63a51d7 + errors: + - code: parameter_invalid + message: The export period is longer than 90 days + schema: + "$ref": "#/components/schemas/error" + '429': + description: Too many concurrent jobs + content: + application/json: + examples: + Concurrent job limit reached: + value: + type: error.list + request_id: 83b4f027-5d19-4ce6-a27f-b05e19c63d4a + errors: + - code: rate_limit_exceeded + message: Exceeded rate limit of 2 pending content data export + jobs + schema: + "$ref": "#/components/schemas/error" + '500': + description: Content data export disabled + content: + application/json: + examples: + Export disabled: + value: + type: error.list + request_id: a5c6e239-0b74-41f8-9d13-7e2b840c5f61 + errors: + - code: server_error + message: Content data export is currently disabled + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -21731,24 +22106,74 @@ paths: tags: - Data Export operationId: getDataExport - description: "You can view the status of your job by sending a `GET` request - to the URL\n`https://api.intercom.io/export/content/data/{job_identifier}` - - the `{job_identifier}` is the value returned in the response when you first - created the export job. More on it can be seen in the Export Job Model.\n\n> - \U0001F6A7 Jobs expire after two days\n> All jobs that have completed processing - (and are thus available to download from the provided URL) will have an expiry - limit of two days from when the export ob completed. After this, the data - will no longer be available.\n" + description: | + You can view the status of your job by sending a `GET` request to the URL + `https://api.intercom.io/export/content/data/{job_identifier}` - the `{job_identifier}` is the value returned in the response when you first created the export job. More on it can be seen in the Export Job Model. + + > 🚧 Jobs expire after one week + > All jobs that have completed processing (and are thus available to download from the provided URL) will have an expiry limit of one week from when the export job was created. After this, the data will no longer be available. + + A job that failed is returned with a `504` status code and a `status` of `failed`. A job left in progress for more than a day is marked failed when you poll it. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful content: application/json: examples: - successful: + successful: + value: + job_identifier: braxwk3j039t6txy + status: pending + download_url: '' + download_expires_at: '' + schema: + "$ref": "#/components/schemas/data_export" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 6ea2c705-84b3-4f19-bd68-013c7e5a2f84 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 1f73b08e-5a26-4c93-87d1-902e4b6c35fa + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Export job not found + content: + application/json: + examples: + Job not found: + value: + type: error.list + request_id: 50a9e14c-6d82-4b37-9f05-c83e712a6d49 + errors: + - code: not_found + message: 'Export job not found for identifier: braxwk3j039t6txy' + schema: + "$ref": "#/components/schemas/error" + '504': + description: The job failed + content: + application/json: + examples: + Failed job: value: job_identifier: braxwk3j039t6txy - status: pending + status: failed download_url: '' download_expires_at: '' schema: @@ -21770,7 +22195,10 @@ paths: tags: - Data Export operationId: cancelDataExport - description: You can cancel your job + description: | + You can cancel your job. A job that has already reached a terminal state is returned unchanged. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful @@ -21785,6 +22213,55 @@ paths: download_expires_at: '' schema: "$ref": "#/components/schemas/data_export" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 7d41c093-2eb6-4a58-8f27-c590b31e6472 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 3e8b5f27-91c4-40da-b163-8f0c27a4e95d + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Export job not found + content: + application/json: + examples: + Job not found: + value: + type: error.list + request_id: b24f7e51-0a93-4c86-95d7-1e6038b2c74f + errors: + - code: not_found + message: 'Export job not found for identifier: v134nyc2bku9hj91' + schema: + "$ref": "#/components/schemas/error" + '500': + description: Content data export disabled + content: + application/json: + examples: + Export disabled: + value: + type: error.list + request_id: c6017af3-4958-42be-a0d1-72f3e8b5c096 + errors: + - code: server_error + message: Content data export is currently disabled + schema: + "$ref": "#/components/schemas/error" "/export/workflows/{id}": get: summary: Export a workflow @@ -21883,15 +22360,76 @@ paths: tags: - Data Export operationId: downloadDataExport - description: "When a job has a status of complete, and thus a filled download_url, - you can download your data by hitting that provided URL, formatted like so: - https://api.intercom.io/download/content/data/xyz1234.\n\nYour exported message - data will be streamed continuously back down to you in a gzipped CSV format.\n\n> - \U0001F4D8 Octet header required\n>\n> You will have to specify the header - Accept: `application/octet-stream` when hitting this endpoint.\n" + description: | + When a job has a status of complete, and thus a filled download_url, you can download your data by hitting that provided URL, formatted like so: https://api.intercom.io/download/content/data/xyz1234. + + Your exported message data is returned as a ZIP archive containing one CSV file per data group. The response is sent with the header `Content-Encoding: zip`. + + > 📘 Octet header required + > + > You will have to specify the header Accept: `application/octet-stream` when hitting this endpoint. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 9a3c6d08-f714-4b25-8e60-37bc1f9a2e58 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 4812fa6b-7d05-49c3-96e1-5a0b3c7d84f2 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Export job not found or not complete + content: + application/json: + examples: + Job not found: + value: + type: error.list + request_id: d709e38a-1c64-4257-bf90-6e23a85c107b + errors: + - code: not_found + message: 'Export job not found for identifier: xyz1234' + schema: + "$ref": "#/components/schemas/error" + '500': + description: Server error + content: + application/json: + examples: + Download failed: + value: + type: error.list + request_id: 5b96c021-83e7-4d4a-a715-0f26e3b8d94c + errors: + - code: server_error + message: Request failed due to an internal error. Please reach + out to support with the job_identifier of this job + Export disabled: + value: + type: error.list + request_id: e13a7c59-204b-468f-82d6-71c5b09e3a47 + errors: + - code: server_error + message: Content data export is currently disabled + schema: + "$ref": "#/components/schemas/error" "/jobs/status/{id}": get: summary: Retrieve job status @@ -28182,6 +28720,10 @@ paths: **Option 1.** You can update a visitor by passing in the `user_id` of the visitor in the Request body. **Option 2.** You can update a visitor by passing in the `id` of the visitor in the Request body. + + Sending an `email` promotes the visitor to a lead. When that happens the response is a contact object with a `role` of `lead`, not a visitor object. + + Requires the `read_write_users` or `write_users_companies` OAuth scope. responses: '200': description: successful @@ -28235,6 +28777,20 @@ paths: do_not_track: schema: "$ref": "#/components/schemas/visitor" + '400': + description: Bad Request + content: + application/json: + examples: + No identifier supplied: + value: + type: error.list + request_id: 2a71c4e6-85d0-4b93-9f18-6c0e3b7a52d4 + errors: + - code: '400' + message: Visitor id or user_id must be supplied + schema: + "$ref": "#/components/schemas/error" '404': description: visitor Not Found content: @@ -28261,6 +28817,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8f25b071-3ca9-4d68-b4e0-5719c2a6f30e + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: @@ -28295,7 +28858,10 @@ paths: tags: - Visitors operationId: retrieveVisitorWithUserId - description: You can fetch the details of a single visitor. + description: | + You can fetch the details of a single visitor. + + Requires the `read_single_user`, `read_users_companies` or `read_write_users` OAuth scope. responses: '200': description: successful @@ -28375,6 +28941,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 7b09e4d2-61c8-4530-9a7f-284c60b5e1d3 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/visitors/convert": @@ -28388,11 +28961,16 @@ paths: tags: - Visitors operationId: convertVisitor - description: "You can merge a Visitor to a Contact of role type `lead` or `user`.\n\n> - \U0001F4D8 What happens upon a visitor being converted?\n>\n> If the User - exists, then the Visitor will be merged into it, the Visitor deleted and the - User returned. If the User does not exist, the Visitor will be converted to - a User, with the User identifiers replacing it's Visitor identifiers.\n" + description: | + You can merge a Visitor to a Contact of role type `lead` or `user`. + + > 📘 What happens upon a visitor being converted? + > + > If the User exists, then the Visitor will be merged into it, the Visitor deleted and the User returned. If the User does not exist, the Visitor will be converted to a User, with the User identifiers replacing it's Visitor identifiers. + + Identify the visitor with `visitor.id` or `visitor.user_id`. The `user` object is required when `type` is `user`, and is not read when `type` is `lead`. + + Requires the `read_write_users` or `write_users_companies` OAuth scope. responses: '200': description: successful @@ -28492,6 +29070,28 @@ paths: enabled_push_messaging: schema: "$ref": "#/components/schemas/contact" + '400': + description: Bad Request + content: + application/json: + examples: + No visitor identifier supplied: + value: + type: error.list + request_id: 9e4b2c07-61da-4f85-93b0-c7a1e568d234 + errors: + - code: '400' + message: Visitor id or user_id must be supplied + Missing or unknown type: + value: + type: error.list + request_id: 41c70e93-8b26-4d5a-a9f7-02e6b1c38045 + errors: + - code: type_mismatch + message: The type attribute provided should be either 'user' + or 'lead' + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -28504,6 +29104,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 6b58d204-3f91-4e7c-85a0-d2f71e634b09 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Visitor not found + content: + application/json: + examples: + Visitor not found: + value: + type: error.list + request_id: 0a7e53c1-9268-4bd4-83f6-1c5027e9a4b8 + errors: + - code: not_found + message: Visitor Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -37348,6 +37969,7 @@ components: user: type: object description: The unique identifiers retained after converting or merging. + Required when `type` is `user`; not read when `type` is `lead`. properties: id: type: string @@ -37368,9 +37990,13 @@ components: - id - required: - user_id + - required: + - email visitor: type: object - description: The unique identifiers to convert a single Visitor. + description: The unique identifiers to convert a single Visitor. One of + `id` or `user_id` is required; an `email` on its own does not identify + a visitor. properties: id: type: string @@ -37390,11 +38016,8 @@ components: - id - required: - user_id - - required: - - email required: - type - - user - visitor create_audience_request: title: Create Audience Request @@ -37902,7 +38525,6 @@ components: - integer - float - boolean - - datetime - date title: 'other type' create_data_event_request: @@ -37938,8 +38560,16 @@ components: example: frodo.baggins@example.com metadata: type: object - description: Optional metadata about the event. - additionalProperties: true + description: Optional metadata about the event. Values can be a string, + a number, a boolean, or an object holding a rich link (`url` and `value`) + or a monetary amount (`amount` and `currency`). + additionalProperties: + anyOf: + - type: string + - type: integer + - type: number + - type: boolean + - type: object example: invite_code: ADDAFRIEND anyOf: @@ -37965,6 +38595,16 @@ components: combination, to improve readability, for example `updated-plan`. type: object title: Create Data Event Summaries Request + anyOf: + - title: id required + required: + - id + - title: user_id required + required: + - user_id + - title: email required + required: + - email properties: user_id: type: string @@ -39225,7 +39865,9 @@ components: example: Whether the user is a paid subscriber. data_type: type: string - description: The data type of the attribute. + description: The data type of the attribute. A list attribute created with + the `options` data type is returned as `string`, with its choices in + `options`. `relationship` is a reference to a custom object. enum: - string - integer @@ -39233,6 +39875,7 @@ components: - boolean - date - datetime + - relationship example: boolean options: type: array @@ -41025,7 +41668,7 @@ components: received each message, when they received it, and how they engaged with it (opens, clicks, replies, completions, dismissals, unsubscribes, and bounces). properties: - job_identfier: + job_identifier: type: string description: The identifier for your job. example: orzzsbd7hk67xyu @@ -41042,12 +41685,15 @@ components: example: pending download_expires_at: type: string - description: The time after which you will not be able to access the data. + description: The time after which you will not be able to access the data, + as a Unix timestamp. It is one week from the time the job was created. + Empty until the job completes. example: '1674917488' download_url: type: string - description: The location where you can download your data. - example: https://api.intercom.test/download/messages/data/example + description: The location where you can download your data. Empty until + the job completes. + example: https://api.intercom.io/download/content/data/orzzsbd7hk67xyu data_export_csv: title: Data Export CSV type: object @@ -47391,20 +48037,91 @@ components: id: type: string description: A unique identified for the visitor which is given by Intercom. + Used to look the visitor up; it is not changed by this request. example: 8a88a590-e user_id: type: string description: A unique identified for the visitor which is given by you. + Used to look the visitor up; it is not changed by this request. example: '123' name: type: string description: The visitor's name. example: Christian Bale + email: + type: string + description: The visitor's email address. Sending this promotes the visitor + to a lead and the response becomes a contact object. + example: winstonsmith@truth.org + phone: + type: string + description: The visitor's phone number. + example: "+353871234567" + owner_id: + type: integer + description: The id of the teammate who owns the visitor. + example: 991267734 + last_request_at: + type: integer + description: The time the visitor was last seen, as a Unix timestamp. + example: 1663597223 + last_seen_ip: + type: string + description: The IP address the visitor was last seen from. + example: 1.2.3.4 + last_seen_user_agent: + type: string + description: The user agent the visitor was last seen with. + example: Mozilla/5.0 + unsubscribed_from_emails: + type: boolean + description: Whether the visitor is unsubscribed from emails. + example: false + language_override: + type: string + description: The language to send the visitor messages in, overriding the + language we detect. + example: fr + avatar: + type: string + description: An image URL for the visitor's avatar. + example: https://example.org/128Wu8Q.jpg + companies: + type: array + description: The companies to associate the visitor with. Only applied + when the same request sends `email`, which promotes the visitor to a lead. + items: + type: object + utm_campaign: + type: string + description: The campaign the visitor arrived from. + example: intercom-link + utm_content: + type: string + description: The content the visitor arrived from. + example: banner + utm_medium: + type: string + description: The medium the visitor arrived from. + example: email + utm_source: + type: string + description: The source the visitor arrived from. + example: Intercom + utm_term: + type: string + description: The search term the visitor arrived from. + example: messenger custom_attributes: type: object description: The custom attributes which are set for the visitor. additionalProperties: - type: string + anyOf: + - type: string + nullable: true + - type: integer + - type: number + - type: boolean example: paid_subscriber: true monthly_spend: 155.5 @@ -47489,8 +48206,30 @@ components: example: company.list companies: type: array + description: Companies are returned in a reduced form here, with only + these four keys. items: - "$ref": "#/components/schemas/company" + type: object + properties: + type: + type: string + description: The type of the object + enum: + - company + example: company + company_id: + type: string + nullable: true + description: The company id you have defined for the company. + example: '625' + id: + type: string + description: The Intercom defined id representing the company. + example: 531ee472cce572a6ec000006 + name: + type: string + description: The name of the company. + example: Blue Sun location_data: type: object properties: @@ -47620,12 +48359,28 @@ components: segments: type: array items: - type: string + type: object + properties: + type: + type: string + description: The type of the object + enum: + - segment + example: segment + id: + type: string + description: The Intercom defined id representing the segment. + example: 56203d455f71e8285f000020 custom_attributes: type: object description: The custom attributes you have set on the Visitor. additionalProperties: - type: string + anyOf: + - type: string + nullable: true + - type: integer + - type: number + - type: boolean referrer: type: string nullable: true diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index c87a7a84..5ff3d40a 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -18039,6 +18039,8 @@ paths: {% admonition type="warning" %} Conversation attributes are no longer returned by this endpoint. Calling without a `model` parameter no longer includes them, and `model=conversation` returns a `422` error. Use `GET /conversations/attributes` instead. {% /admonition %} + + Requires the `read_users_companies` or `read_write_users` OAuth scope. responses: '200': description: Successful response @@ -18278,6 +18280,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 2f0c1e7a-5a3d-43a1-9f61-6b2d1c4e8a90 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" '422': @@ -18304,7 +18313,10 @@ paths: tags: - Data Attributes operationId: createDataAttribute - description: You can create a data attributes for a `contact` or a `company`. + description: | + You can create a data attributes for a `contact` or a `company`. + + Requires the `write_attributes` OAuth scope. responses: '200': description: Successful @@ -18331,7 +18343,7 @@ paths: schema: "$ref": "#/components/schemas/data_attribute" '400': - description: Too few options for list + description: Bad Request content: application/json: examples: @@ -18388,6 +18400,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8d0a4f23-0b7e-4c2e-9a68-1d5f3c7b2e41 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Relationship data type: + value: + type: error.list + request_id: 3a6b9c14-7e52-4d08-b1f3-c8a0e5d27b36 + errors: + - code: parameter_invalid + message: Data Type isn't an option schema: "$ref": "#/components/schemas/error" requestBody: @@ -18451,10 +18484,17 @@ paths: tags: - Data Attributes operationId: updateDataAttribute - description: "\nYou can update a data attribute.\n\n> \U0001F6A7 Updating the - data type is not possible\n>\n> It is currently a dangerous action to execute - changing a data attribute's type via the API. You will need to update the - type via the UI instead.\n" + description: | + + You can update a data attribute. + + > 🚧 Updating the data type is not possible + > + > It is currently a dangerous action to execute changing a data attribute's type via the API. You will need to update the type via the UI instead. + + You can also send this request with `PATCH`; it behaves the same as `PUT`. + + Requires the `write_attributes` OAuth scope. responses: '200': description: Successful @@ -18539,6 +18579,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 5c71e2d8-9a04-4b36-8e57-f2b6c3a91d4e + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: @@ -19886,7 +19933,7 @@ paths: **Metadata behaviour** - - We currently limit the number of tracked metadata keys to 10 per event. Once the quota is reached, we ignore any further keys we receive. The first 10 metadata keys are determined by the order in which they are sent in with the event. + - We currently limit the number of tracked metadata keys to 20 per event name. The limit counts every key ever recorded for that event name, not the keys in a single request, so it is reached cumulatively as you send more events with the same name. Once the quota is reached, we ignore any further keys we receive. The keys that count towards the quota are determined by the order in which they are sent in with the event. - It is not possible to change the metadata keys once the event has been sent. A new event will need to be created with the new keys and you can archive the old one. - There might be up to 24 hrs delay when you send a new metadata for an existing event. @@ -19904,9 +19951,46 @@ paths: - Event lists containing duplicate events will have those duplicates ignored. - Server errors will return a `500` response code and may contain an error message in the body. + Requires the `write_events` OAuth scope. + responses: '202': description: successful + '400': + description: Bad Request + content: + application/json: + examples: + Missing a required field: + value: + type: error.list + request_id: 5d0c8e27-3a91-4f6b-b2d4-7e18c9a06f53 + errors: + - code: parameter_not_found + message: missing data parameter + Null event name: + value: + type: error.list + request_id: 9b1f3c40-5d2a-4e7b-8c16-a3d9e0f51b24 + errors: + - code: parameter_not_found + message: missing event_name parameter + Metadata is not an object: + value: + type: error.list + request_id: c4e07a19-62b8-4d35-91fa-70e2b6c38d5f + errors: + - code: type_mismatch + message: event metadata must be an object + Bad type parameter: + value: + type: error.list + request_id: 71d3b8e5-0c46-4a92-bf27-5e8a1d60c93b + errors: + - code: parameter_invalid + message: bad type parameter + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -19919,6 +20003,62 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 0e5a9c62-3b71-4f84-ad19-6c7e2b05f4a8 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + User not found: + value: + type: error.list + request_id: 2b8f6d13-47ca-4e09-9d52-f1a63c0e78b5 + errors: + - code: not_found + message: User Not Found + Lead not found: + value: + type: error.list + request_id: 6a2c91e7-8d40-4b15-a3f6-9e0b72d5c814 + errors: + - code: not_found + message: Lead Not Found + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Event name too long: + value: + type: error.list + request_id: 4f1e7b03-9c25-4d6a-82be-13a0c5d9e672 + errors: + - code: parameter_invalid + message: invalid event name length; use up to 100 characters + Metadata too long: + value: + type: error.list + request_id: 8c40a5f2-1e69-4730-b8d4-27f5e1c06a93 + errors: + - code: parameter_invalid + message: invalid event metadata length; use up to 65535 characters + Invalid timestamp: + value: + type: error.list + request_id: d57b2e91-6043-4c8f-a12d-3b9e07f45c68 + errors: + - code: parameter_invalid + message: invalid timestamp format; please use seconds since epoch schema: "$ref": "#/components/schemas/error" requestBody: @@ -19962,12 +20102,46 @@ paths: required: - email additionalProperties: false + - title: anonymous_id query parameter + properties: + anonymous_id: + type: string + required: + - anonymous_id + additionalProperties: false - name: type in: query required: true - description: The value must be user + description: The value must be `user` or `lead`. schema: type: string + enum: + - user + - lead + - name: per_page + in: query + required: false + description: The number of events to return per page. + schema: + type: integer + - name: since + in: query + required: false + description: Only return events created after this time, as a Unix timestamp + in milliseconds. Take the value from the `since` link in the `pages` object + of a previous response. + schema: + type: integer + format: int64 + - name: before + in: query + required: false + description: Only return events created before this time, as a Unix timestamp + in milliseconds. Take the value from the `next` link in the `pages` object + of a previous response. + schema: + type: integer + format: int64 - name: summary in: query required: false @@ -19977,18 +20151,25 @@ paths: tags: - Data Events operationId: lisDataEvents - description: "\n> \U0001F6A7\n>\n> Please note that you can only 'list' events - that are less than 90 days old. Event counts and summaries will still include - your events older than 90 days but you cannot 'list' these events individually - if they are older than 90 days\n\nThe events belonging to a customer can be - listed by sending a GET request to `https://api.intercom.io/events` with a - user or lead identifier along with a `type` parameter. The identifier parameter - can be one of `user_id`, `email` or `intercom_user_id`. The `type` parameter - value must be `user`.\n\n- `https://api.intercom.io/events?type=user&user_id={user_id}`\n- - `https://api.intercom.io/events?type=user&email={email}`\n- `https://api.intercom.io/events?type=user&intercom_user_id={id}` - (this call can be used to list leads)\n\nThe `email` parameter value should - be [url encoded](http://en.wikipedia.org/wiki/Percent-encoding) when sending.\n\nYou - can optionally define the result page size as well with the `per_page` parameter.\n" + description: | + + > 🚧 + > + > Please note that you can only 'list' events that are less than 90 days old. Event counts and summaries will still include your events older than 90 days but you cannot 'list' these events individually if they are older than 90 days + + The events belonging to a customer can be listed by sending a GET request to `https://api.intercom.io/events` with a user or lead identifier along with a `type` parameter. The identifier parameter can be one of `user_id`, `email`, `intercom_user_id` or `anonymous_id`. The `type` parameter value must be `user` or `lead`. + + - `https://api.intercom.io/events?type=user&user_id={user_id}` + - `https://api.intercom.io/events?type=user&email={email}` + - `https://api.intercom.io/events?type=user&intercom_user_id={id}` (this call can be used to list leads) + + When `type` is `lead`, a `user_id` you send is matched against the lead's anonymous id instead. + + The `email` parameter value should be [url encoded](http://en.wikipedia.org/wiki/Percent-encoding) when sending. + + You can optionally define the result page size as well with the `per_page` parameter. + + Requires the `read_events` or `write_events` OAuth scope. responses: '200': description: Successful response @@ -20033,6 +20214,48 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: b3a71f58-2c09-4e6d-91b7-4f8c5e2a0d63 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + User not found: + value: + type: error.list + request_id: 5e9c0b24-71f3-4a86-bd50-2c7a1e638f49 + errors: + - code: not_found + message: User Not Found + Lead not found: + value: + type: error.list + request_id: 93f6d205-4b18-47ea-8c31-6d0b5a7e2f14 + errors: + - code: not_found + message: Lead Not Found + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Unsupported type: + value: + type: error.list + request_id: 1d4e8a07-5f62-4390-b7c8-0a2e9b16d35f + errors: + - code: parameter_invalid + message: unsupported type [company] schema: "$ref": "#/components/schemas/error" "/events/summaries": @@ -20046,12 +20269,43 @@ paths: tags: - Data Events operationId: dataEventSummaries - description: "Create event summaries for a user. Event summaries are used to - track the number of times an event has occurred, the first time it occurred - and the last time it occurred.\n\n" + description: | + Create event summaries for a user. Event summaries are used to track the number of times an event has occurred, the first time it occurred and the last time it occurred. + + Identify the user with one of `id`, `user_id` or `email`. If more than one is sent, `id` is used first, then `user_id`, then `email`. + + Requires the `write_events` OAuth scope. responses: '200': description: successful + '400': + description: Bad Request + content: + application/json: + examples: + No user identifier: + value: + type: error.list + request_id: 7c1b93a6-0d52-4e87-96f4-2a8e5c0b7d31 + errors: + - code: missing_parameter + message: No user identifier found + No summaries: + value: + type: error.list + request_id: a04f6e82-3c97-4b15-8d26-f1b7093c5e48 + errors: + - code: missing_parameter + message: No summaries found + Summary field has the wrong type: + value: + type: error.list + request_id: e82d47b1-6a09-4c35-b7f1-305c9e2a6d70 + errors: + - code: parameter_invalid + message: 'Value: many not of type Integer' + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -20064,6 +20318,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 36b0e95c-7d41-4a28-83ef-9c5a1b204e76 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + User not found: + value: + type: error.list + request_id: 58c7a230-9e16-4b74-a0d3-7f2e6c1b9d45 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -20082,25 +20357,26 @@ paths: tags: - Data Export operationId: createDataExport - description: "To create your export job, you need to send a `POST` request to - the export endpoint `https://api.intercom.io/export/content/data`.\n\nThis - endpoint exports **message delivery and engagement data** for outbound content - (Emails, Posts, Custom Bots, Surveys, Tours, Series, and more). The exported - data includes who received each message, when they received it, and how they - engaged with it (opens, clicks, replies, completions, dismissals, unsubscribes, - and bounces). It does not export raw message or conversation content.\n\nThe - only parameters you need to provide are the range of dates that you want exported.\n\n>\U0001F6A7 - Limit of one active job\n>\n> You can only have one active job per workspace. - You will receive a HTTP status code of 429 with the message Exceeded rate - limit of 1 pending message data export jobs if you attempt to create a second - concurrent job.\n\n>❗️ Updated_at not included\n>\n> It should be noted that - the timeframe only includes messages sent during the time period and not messages - that were only updated during this period. For example, if a message was updated - yesterday but sent two days ago, you would need to set the created_at_after - date before the message was sent to include that in your retrieval job.\n\n>\U0001F4D8 - Date ranges are inclusive\n>\n> Requesting data for 2018-06-01 until 2018-06-30 - will get all data for those days including those specified - e.g. 2018-06-01 - 00:00:00 until 2018-06-30 23:59:99.\n" + description: | + To create your export job, you need to send a `POST` request to the export endpoint `https://api.intercom.io/export/content/data`. + + This endpoint exports **message delivery and engagement data** for outbound content (Emails, Posts, Custom Bots, Surveys, Tours, Series, and more). The exported data includes who received each message, when they received it, and how they engaged with it (opens, clicks, replies, completions, dismissals, unsubscribes, and bounces). It does not export raw message or conversation content. + + The only parameters you need to provide are the range of dates that you want exported. The range cannot be longer than 90 days. + + >🚧 Limit of two active jobs + > + > You can only have two active jobs per workspace. You will receive a HTTP status code of 429 with the message Exceeded rate limit of 2 pending content data export jobs if you attempt to create a third concurrent job. + + >❗️ Updated_at not included + > + > It should be noted that the timeframe only includes messages sent during the time period and not messages that were only updated during this period. For example, if a message was updated yesterday but sent two days ago, you would need to set the created_at_after date before the message was sent to include that in your retrieval job. + + >📘 Date ranges are inclusive + > + > Requesting data for 2018-06-01 until 2018-06-30 will get all data for those days including those specified - e.g. 2018-06-01 00:00:00 until 2018-06-30 23:59:99. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful @@ -20115,6 +20391,105 @@ paths: download_expires_at: '' schema: "$ref": "#/components/schemas/data_export" + '400': + description: Bad Request + content: + application/json: + examples: + Missing date: + value: + type: error.list + request_id: 1a7c0e36-b249-4d85-96f1-5c03e7a2b48d + errors: + - code: bad_request + message: "'created_at_after' is a required parameter" + Date is not an integer: + value: + type: error.list + request_id: 62e9b0a4-38c7-4f51-bd96-07a1c4e5f283 + errors: + - code: bad_request + message: "'created_at_before: yesterday' must be of type Integer" + Dates out of order: + value: + type: error.list + request_id: f3081b57-4c2a-49e6-85d0-2b7a6e91c340 + errors: + - code: bad_request + message: created_at_after is greater than created_at_before + Unknown parameter: + value: + type: error.list + request_id: 9d2f4c81-706b-4e39-a5c7-13e08b6d2f95 + errors: + - code: bad_request + message: "bad 'created_at' parameter" + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 4b6e1d09-85f2-4a37-9c60-d1a37e204b58 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 0c93a7e5-1f48-4b62-83da-6e5c702f194b + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Range too long: + value: + type: error.list + request_id: 7e50c938-2a61-4df7-b084-c9f2e63a51d7 + errors: + - code: parameter_invalid + message: The export period is longer than 90 days + schema: + "$ref": "#/components/schemas/error" + '429': + description: Too many concurrent jobs + content: + application/json: + examples: + Concurrent job limit reached: + value: + type: error.list + request_id: 83b4f027-5d19-4ce6-a27f-b05e19c63d4a + errors: + - code: rate_limit_exceeded + message: Exceeded rate limit of 2 pending content data export + jobs + schema: + "$ref": "#/components/schemas/error" + '500': + description: Content data export disabled + content: + application/json: + examples: + Export disabled: + value: + type: error.list + request_id: a5c6e239-0b74-41f8-9d13-7e2b840c5f61 + errors: + - code: server_error + message: Content data export is currently disabled + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -20143,24 +20518,74 @@ paths: tags: - Data Export operationId: getDataExport - description: "You can view the status of your job by sending a `GET` request - to the URL\n`https://api.intercom.io/export/content/data/{job_identifier}` - - the `{job_identifier}` is the value returned in the response when you first - created the export job. More on it can be seen in the Export Job Model.\n\n> - \U0001F6A7 Jobs expire after two days\n> All jobs that have completed processing - (and are thus available to download from the provided URL) will have an expiry - limit of two days from when the export ob completed. After this, the data - will no longer be available.\n" + description: | + You can view the status of your job by sending a `GET` request to the URL + `https://api.intercom.io/export/content/data/{job_identifier}` - the `{job_identifier}` is the value returned in the response when you first created the export job. More on it can be seen in the Export Job Model. + + > 🚧 Jobs expire after one week + > All jobs that have completed processing (and are thus available to download from the provided URL) will have an expiry limit of one week from when the export job was created. After this, the data will no longer be available. + + A job that failed is returned with a `504` status code and a `status` of `failed`. A job left in progress for more than a day is marked failed when you poll it. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful content: application/json: examples: - successful: + successful: + value: + job_identifier: braxwk3j039t6txy + status: pending + download_url: '' + download_expires_at: '' + schema: + "$ref": "#/components/schemas/data_export" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 6ea2c705-84b3-4f19-bd68-013c7e5a2f84 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 1f73b08e-5a26-4c93-87d1-902e4b6c35fa + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Export job not found + content: + application/json: + examples: + Job not found: + value: + type: error.list + request_id: 50a9e14c-6d82-4b37-9f05-c83e712a6d49 + errors: + - code: not_found + message: 'Export job not found for identifier: braxwk3j039t6txy' + schema: + "$ref": "#/components/schemas/error" + '504': + description: The job failed + content: + application/json: + examples: + Failed job: value: job_identifier: braxwk3j039t6txy - status: pending + status: failed download_url: '' download_expires_at: '' schema: @@ -20182,7 +20607,10 @@ paths: tags: - Data Export operationId: cancelDataExport - description: You can cancel your job + description: | + You can cancel your job. A job that has already reached a terminal state is returned unchanged. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful @@ -20197,6 +20625,55 @@ paths: download_expires_at: '' schema: "$ref": "#/components/schemas/data_export" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 7d41c093-2eb6-4a58-8f27-c590b31e6472 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 3e8b5f27-91c4-40da-b163-8f0c27a4e95d + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Export job not found + content: + application/json: + examples: + Job not found: + value: + type: error.list + request_id: b24f7e51-0a93-4c86-95d7-1e6038b2c74f + errors: + - code: not_found + message: 'Export job not found for identifier: v134nyc2bku9hj91' + schema: + "$ref": "#/components/schemas/error" + '500': + description: Content data export disabled + content: + application/json: + examples: + Export disabled: + value: + type: error.list + request_id: c6017af3-4958-42be-a0d1-72f3e8b5c096 + errors: + - code: server_error + message: Content data export is currently disabled + schema: + "$ref": "#/components/schemas/error" "/download/content/data/{job_identifier}": get: summary: Download content data export @@ -20214,15 +20691,76 @@ paths: tags: - Data Export operationId: downloadDataExport - description: "When a job has a status of complete, and thus a filled download_url, - you can download your data by hitting that provided URL, formatted like so: - https://api.intercom.io/download/content/data/xyz1234.\n\nYour exported message - data will be streamed continuously back down to you in a gzipped CSV format.\n\n> - \U0001F4D8 Octet header required\n>\n> You will have to specify the header - Accept: `application/octet-stream` when hitting this endpoint.\n" + description: | + When a job has a status of complete, and thus a filled download_url, you can download your data by hitting that provided URL, formatted like so: https://api.intercom.io/download/content/data/xyz1234. + + Your exported message data is returned as a ZIP archive containing one CSV file per data group. The response is sent with the header `Content-Encoding: zip`. + + > 📘 Octet header required + > + > You will have to specify the header Accept: `application/octet-stream` when hitting this endpoint. + + Requires the `export_content_data` OAuth scope. responses: '200': description: successful + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 9a3c6d08-f714-4b25-8e60-37bc1f9a2e58 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 4812fa6b-7d05-49c3-96e1-5a0b3c7d84f2 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Export job not found or not complete + content: + application/json: + examples: + Job not found: + value: + type: error.list + request_id: d709e38a-1c64-4257-bf90-6e23a85c107b + errors: + - code: not_found + message: 'Export job not found for identifier: xyz1234' + schema: + "$ref": "#/components/schemas/error" + '500': + description: Server error + content: + application/json: + examples: + Download failed: + value: + type: error.list + request_id: 5b96c021-83e7-4d4a-a715-0f26e3b8d94c + errors: + - code: server_error + message: Request failed due to an internal error. Please reach + out to support with the job_identifier of this job + Export disabled: + value: + type: error.list + request_id: e13a7c59-204b-468f-82d6-71c5b09e3a47 + errors: + - code: server_error + message: Content data export is currently disabled + schema: + "$ref": "#/components/schemas/error" "/jobs/status/{job_id}": get: summary: Retrieve job status @@ -25321,6 +25859,10 @@ paths: **Option 1.** You can update a visitor by passing in the `user_id` of the visitor in the Request body. **Option 2.** You can update a visitor by passing in the `id` of the visitor in the Request body. + + Sending an `email` promotes the visitor to a lead. When that happens the response is a contact object with a `role` of `lead`, not a visitor object. + + Requires the `read_write_users` or `write_users_companies` OAuth scope. responses: '200': description: successful @@ -25374,6 +25916,20 @@ paths: do_not_track: schema: "$ref": "#/components/schemas/visitor" + '400': + description: Bad Request + content: + application/json: + examples: + No identifier supplied: + value: + type: error.list + request_id: 2a71c4e6-85d0-4b93-9f18-6c0e3b7a52d4 + errors: + - code: '400' + message: Visitor id or user_id must be supplied + schema: + "$ref": "#/components/schemas/error" '404': description: visitor Not Found content: @@ -25400,6 +25956,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 8f25b071-3ca9-4d68-b4e0-5719c2a6f30e + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" requestBody: @@ -25434,7 +25997,10 @@ paths: tags: - Visitors operationId: retrieveVisitorWithUserId - description: You can fetch the details of a single visitor. + description: | + You can fetch the details of a single visitor. + + Requires the `read_single_user`, `read_users_companies` or `read_write_users` OAuth scope. responses: '200': description: successful @@ -25514,6 +26080,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 7b09e4d2-61c8-4530-9a7f-284c60b5e1d3 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" "/visitors/convert": @@ -25527,11 +26100,16 @@ paths: tags: - Visitors operationId: convertVisitor - description: "You can merge a Visitor to a Contact of role type `lead` or `user`.\n\n> - \U0001F4D8 What happens upon a visitor being converted?\n>\n> If the User - exists, then the Visitor will be merged into it, the Visitor deleted and the - User returned. If the User does not exist, the Visitor will be converted to - a User, with the User identifiers replacing it's Visitor identifiers.\n" + description: | + You can merge a Visitor to a Contact of role type `lead` or `user`. + + > 📘 What happens upon a visitor being converted? + > + > If the User exists, then the Visitor will be merged into it, the Visitor deleted and the User returned. If the User does not exist, the Visitor will be converted to a User, with the User identifiers replacing it's Visitor identifiers. + + Identify the visitor with `visitor.id` or `visitor.user_id`. The `user` object is required when `type` is `user`, and is not read when `type` is `lead`. + + Requires the `read_write_users` or `write_users_companies` OAuth scope. responses: '200': description: successful @@ -25629,6 +26207,28 @@ paths: enabled_push_messaging: schema: "$ref": "#/components/schemas/contact" + '400': + description: Bad Request + content: + application/json: + examples: + No visitor identifier supplied: + value: + type: error.list + request_id: 9e4b2c07-61da-4f85-93b0-c7a1e568d234 + errors: + - code: '400' + message: Visitor id or user_id must be supplied + Missing or unknown type: + value: + type: error.list + request_id: 41c70e93-8b26-4d5a-a9f7-02e6b1c38045 + errors: + - code: type_mismatch + message: The type attribute provided should be either 'user' + or 'lead' + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -25641,6 +26241,27 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: 6b58d204-3f91-4e7c-85a0-d2f71e634b09 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: Visitor not found + content: + application/json: + examples: + Visitor not found: + value: + type: error.list + request_id: 0a7e53c1-9268-4bd4-83f6-1c5027e9a4b8 + errors: + - code: not_found + message: Visitor Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -32953,6 +33574,7 @@ components: user: type: object description: The unique identifiers retained after converting or merging. + Required when `type` is `user`; not read when `type` is `lead`. properties: id: type: string @@ -32973,9 +33595,13 @@ components: - id - required: - user_id + - required: + - email visitor: type: object - description: The unique identifiers to convert a single Visitor. + description: The unique identifiers to convert a single Visitor. One of + `id` or `user_id` is required; an `email` on its own does not identify + a visitor. properties: id: type: string @@ -32995,11 +33621,8 @@ components: - id - required: - user_id - - required: - - email required: - type - - user - visitor create_audience_request: title: Create Audience Request @@ -33500,7 +34123,6 @@ components: - integer - float - boolean - - datetime - date title: 'other type' create_data_event_request: @@ -33536,9 +34158,16 @@ components: example: frodo.baggins@example.com metadata: type: object - description: Optional metadata about the event. + description: Optional metadata about the event. Values can be a string, + a number, a boolean, or an object holding a rich link (`url` and `value`) + or a monetary amount (`amount` and `currency`). additionalProperties: - type: string + anyOf: + - type: string + - type: integer + - type: number + - type: boolean + - type: object example: invite_code: ADDAFRIEND anyOf: @@ -33564,6 +34193,16 @@ components: combination, to improve readability, for example `updated-plan`. type: object title: Create Data Event Summaries Request + anyOf: + - title: id required + required: + - id + - title: user_id required + required: + - user_id + - title: email required + required: + - email properties: user_id: type: string @@ -34784,7 +35423,9 @@ components: example: Whether the user is a paid subscriber. data_type: type: string - description: The data type of the attribute. + description: The data type of the attribute. A list attribute created with + the `options` data type is returned as `string`, with its choices in + `options`. `relationship` is a reference to a custom object. enum: - string - integer @@ -34792,6 +35433,7 @@ components: - boolean - date - datetime + - relationship example: boolean options: type: array @@ -36500,12 +37142,15 @@ components: example: pending download_expires_at: type: string - description: The time after which you will not be able to access the data. + description: The time after which you will not be able to access the data, + as a Unix timestamp. It is one week from the time the job was created. + Empty until the job completes. example: '1674917488' download_url: type: string - description: The location where you can download your data. - example: https://api.intercom.test/download/messages/data/example + description: The location where you can download your data. Empty until + the job completes. + example: https://api.intercom.io/download/content/data/orzzsbd7hk67xyu data_export_csv: title: Data Export CSV type: object @@ -41589,20 +42234,91 @@ components: id: type: string description: A unique identified for the visitor which is given by Intercom. + Used to look the visitor up; it is not changed by this request. example: 8a88a590-e user_id: type: string description: A unique identified for the visitor which is given by you. + Used to look the visitor up; it is not changed by this request. example: '123' name: type: string description: The visitor's name. example: Christian Bale + email: + type: string + description: The visitor's email address. Sending this promotes the visitor + to a lead and the response becomes a contact object. + example: winstonsmith@truth.org + phone: + type: string + description: The visitor's phone number. + example: "+353871234567" + owner_id: + type: integer + description: The id of the teammate who owns the visitor. + example: 991267734 + last_request_at: + type: integer + description: The time the visitor was last seen, as a Unix timestamp. + example: 1663597223 + last_seen_ip: + type: string + description: The IP address the visitor was last seen from. + example: 1.2.3.4 + last_seen_user_agent: + type: string + description: The user agent the visitor was last seen with. + example: Mozilla/5.0 + unsubscribed_from_emails: + type: boolean + description: Whether the visitor is unsubscribed from emails. + example: false + language_override: + type: string + description: The language to send the visitor messages in, overriding the + language we detect. + example: fr + avatar: + type: string + description: An image URL for the visitor's avatar. + example: https://example.org/128Wu8Q.jpg + companies: + type: array + description: The companies to associate the visitor with. Only applied + when the same request sends `email`, which promotes the visitor to a lead. + items: + type: object + utm_campaign: + type: string + description: The campaign the visitor arrived from. + example: intercom-link + utm_content: + type: string + description: The content the visitor arrived from. + example: banner + utm_medium: + type: string + description: The medium the visitor arrived from. + example: email + utm_source: + type: string + description: The source the visitor arrived from. + example: Intercom + utm_term: + type: string + description: The search term the visitor arrived from. + example: messenger custom_attributes: type: object description: The custom attributes which are set for the visitor. additionalProperties: - type: string + anyOf: + - type: string + nullable: true + - type: integer + - type: number + - type: boolean example: paid_subscriber: true monthly_spend: 155.5 @@ -41687,8 +42403,30 @@ components: example: company.list companies: type: array + description: Companies are returned in a reduced form here, with only + these four keys. items: - "$ref": "#/components/schemas/company" + type: object + properties: + type: + type: string + description: The type of the object + enum: + - company + example: company + company_id: + type: string + nullable: true + description: The company id you have defined for the company. + example: '625' + id: + type: string + description: The Intercom defined id representing the company. + example: 531ee472cce572a6ec000006 + name: + type: string + description: The name of the company. + example: Blue Sun location_data: type: object properties: @@ -41818,12 +42556,28 @@ components: segments: type: array items: - type: string + type: object + properties: + type: + type: string + description: The type of the object + enum: + - segment + example: segment + id: + type: string + description: The Intercom defined id representing the segment. + example: 56203d455f71e8285f000020 custom_attributes: type: object description: The custom attributes you have set on the Visitor. additionalProperties: - type: string + anyOf: + - type: string + nullable: true + - type: integer + - type: number + - type: boolean referrer: type: string nullable: true diff --git a/fern/preview-openapi-overrides.yml b/fern/preview-openapi-overrides.yml index 0f3b5843..431785af 100644 --- a/fern/preview-openapi-overrides.yml +++ b/fern/preview-openapi-overrides.yml @@ -122,6 +122,8 @@ components: properties: metadata: additionalProperties: true + create_data_event_summaries_request: + anyOf: null create_ticket_request: x-fern-type-name: CreateTicketRequestBody properties: