Skip to content

Commit 3e567ab

Browse files
adisan19adisan19
committed
Drop the Preview version changes; they ship in a separate PR
1 parent ce1b82d commit 3e567ab

1 file changed

Lines changed: 224 additions & 37 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 224 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -465,6 +465,7 @@ paths:
465465
- help_center_settings_change
466466
- inbound_conversations_change
467467
- inbox_access_change
468+
- inbox_bulk_action
468469
- message_deletion
469470
- message_state_change
470471
- messenger_look_and_feel_change
@@ -9062,15 +9063,10 @@ paths:
90629063

90639064
### Searching for Timestamp Fields
90649065

9065-
Standard timestamp fields and Date custom attributes behave differently.
9066-
9067-
**Standard timestamp fields** (`created_at`, `updated_at`, `last_seen_at` etc.) are filtered on the exact second, in UTC. `=` matches only Contacts whose value is that exact second, and `>`, `<`, `>=` and `<=` compare against the exact instant you pass - the value is not rounded or truncated. These fields report a type of `datetime` on the Data Attributes endpoint. Note that `!=` also matches Contacts with no value set for the field.
9068-
9069-
**Date custom attributes** are matched by calendar day, and the day boundary is always UTC regardless of your workspace's timezone. `=` matches the whole UTC day, `>` matches from the start of the *next* UTC day, and `<` matches everything before the start of that day. The `!=`, `>=`, `<=`, `IN` and `NIN` operators are not supported on these fields and return an error.
9070-
9071-
**Example.** Searching for `created_at` greater than `1577869200` (January 1st, 2020 9:00 AM UTC) returns Contacts created after that exact instant. Passing the same value for a Date custom attribute truncates it to `1577836800` (January 1st, 2020 12:00 AM UTC), so those results begin from January 2nd, 2020 12:00 AM UTC.
9072-
9073-
Only search queries behave this way. Responses always carry the full UNIX timestamp, and sorting uses the full value.
9066+
All timestamp fields (created_at, updated_at etc.) are filtered by UTC calendar day in Contact Search. An equality (=) query on a timestamp matches any contact whose value falls on the same UTC day, so filtering by a value the API returned reliably matches that contact regardless of your workspace's timezone. Comparisons (>, <) are evaluated at UTC day granularity.
9067+
For example, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards.
9068+
If you'd like to get contacts created on January 1st, 2020 (UTC) you should search with a created_at value equal (=) to 1577836800 (January 1st, 2020 12:00 AM UTC).
9069+
This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly.
90749070

90759071
### Accepted Fields
90769072

@@ -9124,26 +9120,24 @@ paths:
91249120

91259121
### Accepted Operators
91269122

9127-
{% admonition type="warning" name="Operators not supported on Date custom attributes" %}
9128-
Date custom attributes do not support the `!=`, `>=`, or `<=` operators. Using them returns an error. Standard timestamp fields (`created_at`, `updated_at` etc.) do support these operators, and are filtered on the exact second.
9123+
{% admonition type="warning" name="Searching based on `created_at`" %}
9124+
You cannot use the `<=` or `>=` operators to search by `created_at`.
91299125
{% /admonition %}
91309126

9131-
The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). Which operators are valid depends on the field's type - see the "Valid Types" column below. Searching by `tag_id` supports only the `=` and `!=` operators.
9132-
9133-
| Operator | Valid Types | Description |
9134-
| :------- | :---------------------------------- | :----------------------------------------------------------------------|
9135-
| = | All | Equals |
9136-
| != | All except Date | Doesn't Equal<br>Also matches Contacts with no value set |
9137-
| IN | All except Date, Datetime and tag_id | In<br>Shortcut for `OR` queries<br>Values must be in Array |
9138-
| NIN | All except Date, Datetime and tag_id | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
9139-
| > | Integer<br>Float<br>Datetime<br>Date | Greater than<br>On Date custom attributes, matches from the start of the next day |
9140-
| < | Integer<br>Float<br>Datetime<br>Date | Lower than<br>On Date custom attributes, matches before the start of the day |
9141-
| >= | Integer<br>Float<br>Datetime | Greater than or equal to<br>Not supported on Date custom attributes |
9142-
| <= | Integer<br>Float<br>Datetime | Lower than or equal to<br>Not supported on Date custom attributes |
9143-
| ~ | String | Contains |
9144-
| !~ | String | Doesn't Contain |
9145-
| ^ | String | Starts With |
9146-
| $ | String | Ends With |
9127+
The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates).
9128+
9129+
| Operator | Valid Types | Description |
9130+
| :------- | :------------------------------- | :--------------------------------------------------------------- |
9131+
| = | All | Equals |
9132+
| != | All | Doesn't Equal |
9133+
| IN | All | In<br>Shortcut for `OR` queries<br>Values must be in Array |
9134+
| NIN | All | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
9135+
| > | Integer<br>Date (UNIX Timestamp) | Greater than |
9136+
| < | Integer<br>Date (UNIX Timestamp) | Lower than |
9137+
| ~ | String | Contains |
9138+
| !~ | String | Doesn't Contain |
9139+
| ^ | String | Starts With |
9140+
| $ | String | Ends With |
91479141
responses:
91489142
'200':
91499143
description: successful
@@ -21288,6 +21282,173 @@ paths:
2128821282
message: Access Token Invalid
2128921283
schema:
2129021284
"$ref": "#/components/schemas/error"
21285+
put:
21286+
summary: Update a team's members
21287+
parameters:
21288+
- name: Intercom-Version
21289+
in: header
21290+
schema:
21291+
"$ref": "#/components/schemas/intercom_version"
21292+
- name: id
21293+
in: path
21294+
required: true
21295+
description: The unique identifier of a given team.
21296+
example: '123'
21297+
schema:
21298+
type: string
21299+
tags:
21300+
- Teams
21301+
operationId: updateTeamMembers
21302+
description: |-
21303+
You can replace the set of teammates who belong to a team. Send the full list of
21304+
teammates the team should end up with — any teammate currently on the team and
21305+
missing from the list is removed. This makes the endpoint safe to call on a
21306+
schedule to keep Intercom in step with an external rota or workforce management
21307+
system, since sending an unchanged list makes no changes at all.
21308+
21309+
A token that acts on behalf of a teammate carries that teammate's permissions:
21310+
they must be able to manage teams, and any team or teammate their access is
21311+
restricted from remains out of reach here.
21312+
requestBody:
21313+
content:
21314+
application/json:
21315+
examples:
21316+
successful:
21317+
value:
21318+
admin_ids:
21319+
- 493881
21320+
- 493882
21321+
schema:
21322+
"$ref": "#/components/schemas/update_team_members_request"
21323+
responses:
21324+
'200':
21325+
description: successful
21326+
content:
21327+
application/json:
21328+
examples:
21329+
successful:
21330+
value:
21331+
type: team
21332+
id: '991267902'
21333+
name: team 1
21334+
admin_ids:
21335+
- 493881
21336+
- 493882
21337+
schema:
21338+
"$ref": "#/components/schemas/team"
21339+
'400':
21340+
description: Bad request
21341+
content:
21342+
application/json:
21343+
examples:
21344+
Invalid admin ids:
21345+
value:
21346+
type: error.list
21347+
request_id: 8ba1e2a4-3d6f-4a1e-9c07-52c8f5b0d1aa
21348+
errors:
21349+
- code: parameter_invalid
21350+
message: admin_ids must contain only numeric admin ids
21351+
Field cannot be updated:
21352+
value:
21353+
type: error.list
21354+
request_id: 1c9d6f0b-7a24-4b8e-9f31-3e5a2c6b8d70
21355+
errors:
21356+
- code: parameter_invalid
21357+
message: Only admin_ids can be updated on a team, but the request
21358+
changed name
21359+
schema:
21360+
"$ref": "#/components/schemas/error"
21361+
'403':
21362+
description: |-
21363+
Two codes are returned here and they mean different things. `api_plan_restricted`
21364+
means the endpoint is not available to this workspace at all, so no request will
21365+
succeed until it is enabled. `forbidden` means the workspace has the endpoint but
21366+
the teammate this token acts for may not make this particular change.
21367+
content:
21368+
application/json:
21369+
examples:
21370+
Not available for this workspace:
21371+
value:
21372+
type: error.list
21373+
request_id: 2f7b9c04-8e15-4a63-b0d7-6c41e9a3f582
21374+
errors:
21375+
- code: api_plan_restricted
21376+
message: Updating team memberships via the API is not available
21377+
for this workspace
21378+
Forbidden:
21379+
value:
21380+
type: error.list
21381+
request_id: 4dd0f4f7-2d4b-4d2f-8b98-cf1e7ba1b2c5
21382+
errors:
21383+
- code: forbidden
21384+
message: You don't have permission to update the members of
21385+
this team
21386+
Cannot manage teams:
21387+
value:
21388+
type: error.list
21389+
request_id: 6b2c8e1d-4f39-4d70-8a52-9c7e1f3b0a44
21390+
errors:
21391+
- code: forbidden
21392+
message: You don't have permission to manage teams in this workspace
21393+
schema:
21394+
"$ref": "#/components/schemas/error"
21395+
'404':
21396+
description: Team not found
21397+
content:
21398+
application/json:
21399+
examples:
21400+
Team not found:
21401+
value:
21402+
type: error.list
21403+
request_id: 9a3e0b1c-6f27-4f5e-8c31-0f2f4a7d9e88
21404+
errors:
21405+
- code: team_not_found
21406+
message: Team not found
21407+
schema:
21408+
"$ref": "#/components/schemas/error"
21409+
'409':
21410+
description: |-
21411+
Another request is already changing this team's members. Two cases are
21412+
distinguished by the message: the request was declined before anything was
21413+
written, so the team is unchanged and the same request can simply be sent
21414+
again; or the members kept changing while the request was being applied, so
21415+
it is partly applied and the team should be read again before retrying.
21416+
content:
21417+
application/json:
21418+
examples:
21419+
Conflict:
21420+
value:
21421+
type: error.list
21422+
request_id: 5e7a0c3f-8b16-4d92-a7c4-2f8b6d0e9137
21423+
errors:
21424+
- code: conflict
21425+
message: The members of this team are being changed by another
21426+
request. Try again.
21427+
Partly applied:
21428+
value:
21429+
type: error.list
21430+
request_id: 5e7a0c3f-8b16-4d92-a7c4-2f8b6d0e9137
21431+
errors:
21432+
- code: conflict
21433+
message: The members of this team kept being changed by other
21434+
requests, so this one is partly applied. Read the team and
21435+
try again.
21436+
schema:
21437+
"$ref": "#/components/schemas/error"
21438+
'401':
21439+
description: Unauthorized
21440+
content:
21441+
application/json:
21442+
examples:
21443+
Unauthorized:
21444+
value:
21445+
type: error.list
21446+
request_id: 6c1e2f83-5b47-4f0e-9d8a-3b2c1e4f7a90
21447+
errors:
21448+
- code: unauthorized
21449+
message: Access Token Invalid
21450+
schema:
21451+
"$ref": "#/components/schemas/error"
2129121452
"/ticket_states":
2129221453
get:
2129321454
summary: List all ticket states
@@ -26431,6 +26592,7 @@ components:
2643126592
- help_center_settings_change
2643226593
- inbound_conversations_change
2643326594
- inbox_access_change
26595+
- inbox_bulk_action
2643426596
- message_deletion
2643526597
- message_state_change
2643626598
- messenger_look_and_feel_change
@@ -38802,21 +38964,13 @@ components:
3880238964
- IN
3880338965
- NIN
3880438966
- "<"
38805-
- "<="
3880638967
- ">"
38807-
- ">="
3880838968
- "~"
3880938969
- "!~"
3881038970
- "^"
3881138971
- "$"
38812-
description: |-
38813-
The accepted operators you can use to define how you want to search for the value. Operator support depends on the field's data type:
38814-
- `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$`
38815-
- `tag_id`: `=` and `!=` only. Every other operator returns an error.
38816-
- `boolean` fields: `=`, `!=`, `IN`, `NIN`
38817-
- `integer` and `float` fields: `=`, `!=`, `IN`, `NIN`, `<`, `>`, `<=`, `>=`
38818-
- `datetime` fields (standard contact timestamps such as `created_at` and `last_seen_at`): `=`, `!=`, `<`, `>`, `<=`, `>=`. Filtering is on the exact second, in UTC.
38819-
- `date` fields (Date custom attributes): `=`, `<`, `>` only. `!=`, `<=`, and `>=` are not supported and return an error. Values are truncated to a whole UTC day.
38972+
description: The accepted operators you can use to define how you want to
38973+
search for the value.
3882038974
example: ">"
3882138975
value:
3882238976
oneOf:
@@ -40529,6 +40683,39 @@ components:
4052940683
- url
4053040684
- locale
4053140685
- source_id
40686+
update_team_members_request:
40687+
description: |
40688+
The request payload for updating a team's membership.
40689+
`admin_ids` is the complete set of teammates who should be on the team once
40690+
the request completes, not a list of changes to apply. Any teammate currently
40691+
on the team but absent from `admin_ids` is removed.
40692+
40693+
Membership is the only part of a team this endpoint writes, and the request is
40694+
read from the body: a parameter sent in the query string is rejected rather than
40695+
applied. A team read from the API can be sent back whole, since the other fields
40696+
of the representation are accepted as long as they are unchanged. Trying to
40697+
change one of them returns a 400 rather than being ignored, as does any field a
40698+
team does not have.
40699+
40700+
On a team that balances assignment across its members, teammates already on the
40701+
team keep their current priority level and teammates being added join as primary
40702+
members. Priority levels cannot be set here, so `admin_priority_level` follows
40703+
from `admin_ids`: it is accepted when sent back unchanged and returns a 400 when
40704+
the request tries to change it.
40705+
type: object
40706+
title: Update Team Members Request Payload
40707+
properties:
40708+
admin_ids:
40709+
type: array
40710+
description: The ids of every teammate who should be a member of the team.
40711+
Must contain at least one id, and no more than 1000.
40712+
items:
40713+
type: integer
40714+
example:
40715+
- 493881
40716+
- 493882
40717+
required:
40718+
- admin_ids
4053240719
update_ticket_request:
4053340720
description: You can update a Ticket
4053440721
type: object

0 commit comments

Comments
 (0)