POST /conversations/search
You can search for multiple conversations by the value of their attributes in order to fetch exactly which ones you want.
To search for conversations, you need to send a POST request to https://api.intercom.io/conversations/search.
This will accept a query object in the body which will define your filters in order to search for conversations.
{% admonition type="warning" name="Optimizing search queries" %}
Search queries can be complex, so optimizing them can help the performance of your search.
Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize
pagination to limit the number of results returned. The default is 20 results per page and maximum is 150.
See the pagination section for more details on how to use the starting_after param.
{% /admonition %}
Nesting & Limitations
You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be:
- There's a limit of max 2 nested filters
- There's a limit of max 15 filters for each AND or OR group
Accepted Fields
Most keys listed as part of the conversation model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as created_at accepts a date, the value cannot be a string such as "foorbar").
The source.body field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a "I need support" body - the query should contain a = operator with the value "support" for such conversation to be returned. A query with a = operator and a "need support" value will not yield a result.
| Field | Type |
|---|---|
| id | String |
| created_at | Date (UNIX timestamp) |
| updated_at | Date (UNIX timestamp) |
| source.type | String Accepted fields are conversation, email, facebook, instagram, phone_call, phone_switch, push, sms, twitter and whatsapp. |
| source.id | String |
| source.delivered_as | String |
| source.subject | String |
| source.body | String |
| source.author.id | String |
| source.author.type | String |
| source.author.name | String |
| source.author.email | String |
| source.url | String |
| contact_ids | String |
| teammate_ids | String |
| admin_assignee_id | String |
| team_assignee_id | String |
| channel_initiated | String |
| open | Boolean |
| read | Boolean |
| state | String |
| waiting_since | Date (UNIX timestamp) |
| snoozed_until | Date (UNIX timestamp) |
| tag_ids | String |
| priority | String |
| statistics.time_to_assignment | Integer |
| statistics.time_to_admin_reply | Integer |
| statistics.time_to_first_close | Integer |
| statistics.time_to_last_close | Integer |
| statistics.median_time_to_reply | Integer |
| statistics.first_contact_reply_at | Date (UNIX timestamp) |
| statistics.first_assignment_at | Date (UNIX timestamp) |
| statistics.first_admin_reply_at | Date (UNIX timestamp) |
| statistics.first_close_at | Date (UNIX timestamp) |
| statistics.last_assignment_at | Date (UNIX timestamp) |
| statistics.last_assignment_admin_reply_at | Date (UNIX timestamp) |
| statistics.last_contact_reply_at | Date (UNIX timestamp) |
| statistics.last_admin_reply_at | Date (UNIX timestamp) |
| statistics.last_close_at | Date (UNIX timestamp) |
| statistics.last_closed_by_id | String |
| statistics.count_reopens | Integer |
| statistics.count_assignments | Integer |
| statistics.count_conversation_parts | Integer |
| conversation_rating.requested_at | Date (UNIX timestamp) |
| conversation_rating.replied_at | Date (UNIX timestamp) |
| conversation_rating.score | Integer |
| conversation_rating.remark | String |
| conversation_rating.contact_id | String |
| conversation_rating.admin_d | String |
| ai_agent_participated | Boolean |
| ai_agent.resolution_state | String |
| ai_agent.last_answer_type | String |
| ai_agent.rating | Integer |
| ai_agent.rating_remark | String |
| ai_agent.source_type | String |
| ai_agent.source_title | String |
Accepted Operators
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).
| Operator | Valid Types | Description |
|---|---|---|
| = | All | Equals |
| != | All | Doesn't Equal |
| IN | All | In Shortcut for OR queries Values most be in Array |
| NIN | All | Not In Shortcut for OR ! queries Values must be in Array |
| > | Integer Date (UNIX Timestamp) | Greater (or equal) than |
| < | Integer Date (UNIX Timestamp) | Lower (or equal) than |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
Servers
- https://api.intercom.io
- https://api.eu.intercom.io
- https://api.au.intercom.io
Request headers
| Name | Type | Required | Description |
|---|---|---|---|
Content-Type |
String | Yes |
The media type of the request body.
Default value: "application/json" |
Intercom-Version |
String | No |
Possible values:
Default value: "2.12" |
Request body fields
| Name | Type | Required | Description |
|---|---|---|---|
query |
Yes | ||
pagination |
Object | No | |
pagination.starting_after |
String | No |
The cursor to use in the next request to get the next page of results. |
pagination.per_page |
Integer | No |
The number of results to fetch per page. |
How to start integrating
- Add HTTP Task to your workflow definition.
- Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
- Click Test request to test run your request to the API and see the API's response.