Conversation
Conversation
Conversations can be of different types such as email, chat, support tickets, and manually logged notes. You can also create your own types in Planhat to represent things such as "in person meeting", "Training", etc. The default types (email, chat, ticket, call) are reserved and should not be created over API.
Property | Required | Type | Description |
---|---|---|---|
_id | objectId | Planhat identifier. | |
subject | string | Title of the conversation. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
description | string | Description of the conversation. | |
snippet | string | Formatted content of the conversation. | |
date | string | ISO date when conversation was created. | |
outDate | string | ISO date when conversation was sent. | |
createDate | string | ISO date when conversation was created. (Autogenerated). | |
type | string | Type of conversation. Must reference a pre-existent conversation type in Planhat, or it will default to type: note. | |
users | array | Array of user objects. | |
endusers | array | Array of involved contacts (endusers ids). (Autogenerated). | |
externalId | string | The conversation id in your own system. | |
activityTags | array | Array of strings to tag your notes. | |
starred | boolean | Flag to mark a conversation as important or relevant. | |
pinned | boolean | Pin a conversation at the top of the company and/or user profile. | |
emailTemplateIds | array | Array of email template ids. (Autogenerated). | |
isOpen | boolean | Set a conversation or ticket as open or not, mostly related to CRM integrations. (Autogenerated). | |
tags | array | Array of strings to tag the conversation. (Autogenerated). | |
waitsToBeFiltered | boolean | Internal system field. (Autogenerated). | |
timeBucket | array | Internal system field. (Autogenerated). | |
archived | boolean | Mark a conversation as archived. | |
numberOfParts | integer | Internal system field. (Autogenerated). | |
sender | array | Array of objects containing sender information. (Autogenerated). | |
history | array | Internal system field. (Autogenerated). | |
userIds | array | Array of user ids involved in the conversation. (Autogenerated). | |
hasMore | boolean | Internal system field. (Autogenerated). | |
isCustomType | boolean | Mark the conversation as custom type or not. (Autogenerated). | |
assigneeName | string | Internal system field. (Autogenerated). | |
numberOfRelevantParts | integer | Internal system field. (Autogenerated). | |
hasAttachments | boolean | Set to true if the conversation has attachments. (Autogenerated). | |
isSeen | boolean | Set to true to flag the conversation as seen. (Autogenerated). | |
custom | object | Custom object with your custom properties. |
Conversations can be of different types such as email, chat, support tickets, and manually logged notes. You can also create your own types in Planhat to represent things such as "in person meeting", "Training", etc. The default types (email, chat, ticket, call) are reserved and should not be created over API.
Property | Required | Type | Description |
---|---|---|---|
_id | objectId | Planhat identifier. | |
subject | string | Title of the conversation. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
description | string | Description of the conversation. | |
snippet | string | Formatted content of the conversation. | |
date | string | ISO date when conversation was created. | |
outDate | string | ISO date when conversation was sent. | |
createDate | string | ISO date when conversation was created. (Autogenerated). | |
type | string | Type of conversation. Must reference a pre-existent conversation type in Planhat, or it will default to type: note. | |
users | array | Array of user objects. | |
endusers | array | Array of involved contacts (endusers ids). (Autogenerated). | |
externalId | string | The conversation id in your own system. | |
activityTags | array | Array of strings to tag your notes. | |
starred | boolean | Flag to mark a conversation as important or relevant. | |
pinned | boolean | Pin a conversation at the top of the company and/or user profile. | |
emailTemplateIds | array | Array of email template ids. (Autogenerated). | |
isOpen | boolean | Set a conversation or ticket as open or not, mostly related to CRM integrations. (Autogenerated). | |
tags | array | Array of strings to tag the conversation. (Autogenerated). | |
waitsToBeFiltered | boolean | Internal system field. (Autogenerated). | |
timeBucket | array | Internal system field. (Autogenerated). | |
archived | boolean | Mark a conversation as archived. | |
numberOfParts | integer | Internal system field. (Autogenerated). | |
sender | array | Array of objects containing sender information. (Autogenerated). | |
history | array | Internal system field. (Autogenerated). | |
userIds | array | Array of user ids involved in the conversation. (Autogenerated). | |
hasMore | boolean | Internal system field. (Autogenerated). | |
isCustomType | boolean | Mark the conversation as custom type or not. (Autogenerated). | |
assigneeName | string | Internal system field. (Autogenerated). | |
numberOfRelevantParts | integer | Internal system field. (Autogenerated). | |
hasAttachments | boolean | Set to true if the conversation has attachments. (Autogenerated). | |
isSeen | boolean | Set to true to flag the conversation as seen. (Autogenerated). | |
custom | object | Custom object with your custom properties. |
Conversations can be of different types such as email, chat, support tickets, and manually logged notes. You can also create your own types in Planhat to represent things such as "in person meeting", "Training", etc. The default types (email, chat, ticket, call) are reserved and should not be created over API.
Property | Required | Type | Description |
---|---|---|---|
_id | objectId | Planhat identifier. | |
subject | string | Title of the conversation. | |
companyId | Yes | objectId | Related company id (planhat identifier). |
companyName | string | Company name. (Autogenerated). | |
description | string | Description of the conversation. | |
snippet | string | Formatted content of the conversation. | |
date | string | ISO date when conversation was created. | |
outDate | string | ISO date when conversation was sent. | |
createDate | string | ISO date when conversation was created. (Autogenerated). | |
type | string | Type of conversation. Must reference a pre-existent conversation type in Planhat, or it will default to type: note. | |
users | array | Array of user objects. | |
endusers | array | Array of involved contacts (endusers ids). (Autogenerated). | |
externalId | string | The conversation id in your own system. | |
activityTags | array | Array of strings to tag your notes. | |
starred | boolean | Flag to mark a conversation as important or relevant. | |
pinned | boolean | Pin a conversation at the top of the company and/or user profile. | |
emailTemplateIds | array | Array of email template ids. (Autogenerated). | |
isOpen | boolean | Set a conversation or ticket as open or not, mostly related to CRM integrations. (Autogenerated). | |
tags | array | Array of strings to tag the conversation. (Autogenerated). | |
waitsToBeFiltered | boolean | Internal system field. (Autogenerated). | |
timeBucket | array | Internal system field. (Autogenerated). | |
archived | boolean | Mark a conversation as archived. | |
numberOfParts | integer | Internal system field. (Autogenerated). | |
sender | array | Array of objects containing sender information. (Autogenerated). | |
history | array | Internal system field. (Autogenerated). | |
userIds | array | Array of user ids involved in the conversation. (Autogenerated). | |
hasMore | boolean | Internal system field. (Autogenerated). | |
isCustomType | boolean | Mark the conversation as custom type or not. (Autogenerated). | |
assigneeName | string | Internal system field. (Autogenerated). | |
numberOfRelevantParts | integer | Internal system field. (Autogenerated). | |
hasAttachments | boolean | Set to true if the conversation has attachments. (Autogenerated). | |
isSeen | boolean | Set to true to flag the conversation as seen. (Autogenerated). | |
custom | object | Custom object with your custom properties. |
To create a conversation, it is required to define a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"users": [
{
"id": "58e231b14246fc73139f29e8"
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42"
}
],
"activityTags": [],
"useSubject": true,
"ownerId": "58e231b14246fc73139f29e8"
}'
Example Response
200 ok
'{
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"_id": "6102e3b08084189dcbf0e3f0",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Little call with the client.",
"companyName": "Tenet",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0,
"owner": "60ccb1c5965cc9e0f3848075",
"followers": [],
"userId": "610015551b990c65d4fb0a4c",
"note": "New conversation: Little call with the client.",
"nickName": "Test user"
}'
To create a conversation, it is required to define a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"users": [
{
"id": "58e231b14246fc73139f29e8"
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42"
}
],
"activityTags": [],
"useSubject": true,
"ownerId": "58e231b14246fc73139f29e8"
}'
Example Response
200 ok
'{
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"_id": "6102e3b08084189dcbf0e3f0",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Little call with the client.",
"companyName": "Tenet",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0,
"owner": "60ccb1c5965cc9e0f3848075",
"followers": [],
"userId": "610015551b990c65d4fb0a4c",
"note": "New conversation: Little call with the client.",
"nickName": "Test user"
}'
To create a conversation, it is required to define a valid companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
Example Request
curl --location -g --request POST 'https://api.planhat.com/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"users": [
{
"id": "58e231b14246fc73139f29e8"
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42"
}
],
"activityTags": [],
"useSubject": true,
"ownerId": "58e231b14246fc73139f29e8"
}'
Example Response
200 ok
'{
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"_id": "6102e3b08084189dcbf0e3f0",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Little call with the client.",
"companyName": "Tenet",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0,
"owner": "60ccb1c5965cc9e0f3848075",
"followers": [],
"userId": "610015551b990c65d4fb0a4c",
"note": "New conversation: Little call with the client.",
"nickName": "Test user"
}'
To update a conversation it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the conversation externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"subject": "Chat with the client",
"description": "<p>Slack chat with the client.</p>"
}'
Example Response
200 ok
'{
"_id": "6102e3b08084189dcbf0e3f0",
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "Chat with the client",
"description": "Slack chat with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Slack chat with the client.",
"companyName": "Tenet",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0
}'
To update a conversation it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the conversation externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"subject": "Chat with the client",
"description": "<p>Slack chat with the client.</p>"
}'
Example Response
200 ok
'{
"_id": "6102e3b08084189dcbf0e3f0",
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "Chat with the client",
"description": "Slack chat with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Slack chat with the client.",
"companyName": "Tenet",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0
}'
To update a conversation it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to update using the conversation externalId and/or sourceId adding a prefix and passing one of these keyables as identifiers.
Example:
or
Example Request
curl --location -g --request PUT 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '{
"subject": "Chat with the client",
"description": "<p>Slack chat with the client.</p>"
}'
Example Response
200 ok
'{
"_id": "6102e3b08084189dcbf0e3f0",
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "Chat with the client",
"description": "Slack chat with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Slack chat with the client.",
"companyName": "Tenet",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0
}'
To get a specific conversation it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a conversation using its externalId adding a prefix and passing this keyable as identifiers.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/conversations/58e57392c9437d10624593fd' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"_id": "58e57392c9437d10624593fd",
"type": "email",
"numberOfParts": 1,
"hasAttachments": false,
"source": "bcc",
"subject": "Test 6 on Oct 21 from BCC",
"snippet": "Two new and one existing endusers! ",
"days": 17095,
"companyId": "56e911619f2ff04215515515",
"timeBucket": [
"2016",
"2016-Q4",
"2016-10",
"2016-W43"
],
"history": [],
"tags": [],
"isOpen": false,
"users": [
{
"id": "57225af2dfb33aa3022e88e9",
"name": "Vargha",
"isOwner": true
}
],
"endusers": [
{
"id": "5b47a07ff1846fd087ede384",
"name": "Max Payne"
}
],
"date": "2016-10-21T15:24:05.000Z",
"__v": 0,
"companyName": "Bonnier",
"createDate": "2016-10-21T15:24:05.000Z",
"outDate": "2016-10-21T15:24:05.000Z",
"numberOfRelevantParts": 1,
"custom": {
"Test FF field to check @today cron job": false,
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"userIds": [
"57225af2dfb33aa3022e88e9"
],
"hasMore": true,
"isCustomType": false,
"assigneeName": "",
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false
}'
To get a specific conversation it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a conversation using its externalId adding a prefix and passing this keyable as identifiers.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/conversations/58e57392c9437d10624593fd' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"_id": "58e57392c9437d10624593fd",
"type": "email",
"numberOfParts": 1,
"hasAttachments": false,
"source": "bcc",
"subject": "Test 6 on Oct 21 from BCC",
"snippet": "Two new and one existing endusers! ",
"days": 17095,
"companyId": "56e911619f2ff04215515515",
"timeBucket": [
"2016",
"2016-Q4",
"2016-10",
"2016-W43"
],
"history": [],
"tags": [],
"isOpen": false,
"users": [
{
"id": "57225af2dfb33aa3022e88e9",
"name": "Vargha",
"isOwner": true
}
],
"endusers": [
{
"id": "5b47a07ff1846fd087ede384",
"name": "Max Payne"
}
],
"date": "2016-10-21T15:24:05.000Z",
"__v": 0,
"companyName": "Bonnier",
"createDate": "2016-10-21T15:24:05.000Z",
"outDate": "2016-10-21T15:24:05.000Z",
"numberOfRelevantParts": 1,
"custom": {
"Test FF field to check @today cron job": false,
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"userIds": [
"57225af2dfb33aa3022e88e9"
],
"hasMore": true,
"isCustomType": false,
"assigneeName": "",
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false
}'
To get a specific conversation it's required to pass the _id in the request URL as a parameter.
Alternately it’s possible to get a conversation using its externalId adding a prefix and passing this keyable as identifiers.
Example:
Example Request
curl --location -g --request GET 'https://api.planhat.com/conversations/58e57392c9437d10624593fd' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"_id": "58e57392c9437d10624593fd",
"type": "email",
"numberOfParts": 1,
"hasAttachments": false,
"source": "bcc",
"subject": "Test 6 on Oct 21 from BCC",
"snippet": "Two new and one existing endusers! ",
"days": 17095,
"companyId": "56e911619f2ff04215515515",
"timeBucket": [
"2016",
"2016-Q4",
"2016-10",
"2016-W43"
],
"history": [],
"tags": [],
"isOpen": false,
"users": [
{
"id": "57225af2dfb33aa3022e88e9",
"name": "Vargha",
"isOwner": true
}
],
"endusers": [
{
"id": "5b47a07ff1846fd087ede384",
"name": "Max Payne"
}
],
"date": "2016-10-21T15:24:05.000Z",
"__v": 0,
"companyName": "Bonnier",
"createDate": "2016-10-21T15:24:05.000Z",
"outDate": "2016-10-21T15:24:05.000Z",
"numberOfRelevantParts": 1,
"custom": {
"Test FF field to check @today cron job": false,
"t1": 0,
"HScore": 0,
"Days in Phase": 0,
"NRR30": 0,
"t123": "undefined",
"Logins": 0,
"Renewal in days": -1,
"Activity Count": 0,
"Week No": 29.285714285714285
},
"userIds": [
"57225af2dfb33aa3022e88e9"
],
"hasMore": true,
"isCustomType": false,
"assigneeName": "",
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false
}'
When fetching multiple conversations there are some options that can be used via query params:
companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 30, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/conversations?limit=2&offset=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'[
{
"date": "2021-07-29T15:29:34.330Z",
"userIds": [
"58e231b14246fc73139f29e8"
],
"hasMore": false,
"isCustomType": false,
"subject": "Chat with the client",
"snippet": "Slack chat with the client.",
"_id": "6102e3b08084189dcbf0e3f0",
"type": "note",
"tags": [],
"createDate": "2021-07-29T17:21:52.347Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Leo company",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"assigneeName": "",
"activityTags": [],
"hasAttachments": false,
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false
},
{
"date": "2021-07-26T16:51:44.146Z",
"userIds": [
"5f16fd8eee876638a9f2483c"
],
"isCustomType": false,
"subject": "t6",
"_id": "60fee824a4c764252c877c2b",
"type": "note",
"tags": [],
"createDate": "2021-07-26T16:51:48.720Z",
"companyId": "584d9d5505ba1b622f04adb3",
"companyName": "Daimler North America",
"users": [
{
"id": "5f16fd8eee876638a9f2483c",
"name": "Ernesto",
"isOwner": true
}
],
"endusers": [],
"assigneeName": "",
"activityTags": [],
"hasAttachments": false,
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false,
"custom": {
"Activity Count": 0,
"Days in Phase": 0,
"Logins": 0
}
}
]'
When fetching multiple conversations there are some options that can be used via query params:
companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 30, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/conversations?limit=2&offset=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'[
{
"date": "2021-07-29T15:29:34.330Z",
"userIds": [
"58e231b14246fc73139f29e8"
],
"hasMore": false,
"isCustomType": false,
"subject": "Chat with the client",
"snippet": "Slack chat with the client.",
"_id": "6102e3b08084189dcbf0e3f0",
"type": "note",
"tags": [],
"createDate": "2021-07-29T17:21:52.347Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Leo company",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"assigneeName": "",
"activityTags": [],
"hasAttachments": false,
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false
},
{
"date": "2021-07-26T16:51:44.146Z",
"userIds": [
"5f16fd8eee876638a9f2483c"
],
"isCustomType": false,
"subject": "t6",
"_id": "60fee824a4c764252c877c2b",
"type": "note",
"tags": [],
"createDate": "2021-07-26T16:51:48.720Z",
"companyId": "584d9d5505ba1b622f04adb3",
"companyName": "Daimler North America",
"users": [
{
"id": "5f16fd8eee876638a9f2483c",
"name": "Ernesto",
"isOwner": true
}
],
"endusers": [],
"assigneeName": "",
"activityTags": [],
"hasAttachments": false,
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false,
"custom": {
"Activity Count": 0,
"Days in Phase": 0,
"Logins": 0
}
}
]'
When fetching multiple conversations there are some options that can be used via query params:
companyId: Filter using company id. Multiple ids can be used separating them by commas.
limit: Limit the list length. Default as 30, max. 2000.
offset: Start the list on a specific integer index.
sort: Sort based on a specific property. Prefix the property "-" to change the sort order.
select: Select specific properties. Multiple properties can be specified separating them by commas.
Example Request
curl --location -g --request GET 'https://api.planhat.com/conversations?limit=2&offset=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'[
{
"date": "2021-07-29T15:29:34.330Z",
"userIds": [
"58e231b14246fc73139f29e8"
],
"hasMore": false,
"isCustomType": false,
"subject": "Chat with the client",
"snippet": "Slack chat with the client.",
"_id": "6102e3b08084189dcbf0e3f0",
"type": "note",
"tags": [],
"createDate": "2021-07-29T17:21:52.347Z",
"companyId": "61006bc89a3e0b702ed8ea49",
"companyName": "Leo company",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"assigneeName": "",
"activityTags": [],
"hasAttachments": false,
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false
},
{
"date": "2021-07-26T16:51:44.146Z",
"userIds": [
"5f16fd8eee876638a9f2483c"
],
"isCustomType": false,
"subject": "t6",
"_id": "60fee824a4c764252c877c2b",
"type": "note",
"tags": [],
"createDate": "2021-07-26T16:51:48.720Z",
"companyId": "584d9d5505ba1b622f04adb3",
"companyName": "Daimler North America",
"users": [
{
"id": "5f16fd8eee876638a9f2483c",
"name": "Ernesto",
"isOwner": true
}
],
"endusers": [],
"assigneeName": "",
"activityTags": [],
"hasAttachments": false,
"isSeen": false,
"starred": false,
"pinned": false,
"archived": false,
"custom": {
"Activity Count": 0,
"Days in Phase": 0,
"Logins": 0
}
}
]'
To delete a conversation it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"_id": "6102e3b08084189dcbf0e3f0",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "Chat with the client",
"description": "<p>Slack chat with the client.</p>",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Slack chat with the client.",
"companyName": "Leo company",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0
}'
To delete a conversation it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"_id": "6102e3b08084189dcbf0e3f0",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "Chat with the client",
"description": "<p>Slack chat with the client.</p>",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Slack chat with the client.",
"companyName": "Leo company",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0
}'
To delete a conversation it's required to pass the _id in the request URL as a parameter.
Example Request
curl --location -g --request DELETE 'https://api.planhat.com/conversations/6102e3b08084189dcbf0e3f0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}'
Example Response
200 ok
'{
"starred": false,
"pinned": false,
"autoTags": [],
"activityTags": [],
"emailTemplateIds": [],
"isOpen": false,
"tags": [],
"waitsToBeFiltered": true,
"timeBucket": [],
"archived": false,
"_id": "6102e3b08084189dcbf0e3f0",
"users": [
{
"id": "58e231b14246fc73139f29e8",
"name": "Alex",
"isOwner": true
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "Chat with the client",
"description": "<p>Slack chat with the client.</p>",
"endusers": [
{
"id": "610091916d643a7c418aef42",
"name": "Lara Croft"
}
],
"snippet": "Slack chat with the client.",
"companyName": "Leo company",
"createDate": "2021-07-29T17:21:52.347Z",
"sender": [],
"history": [],
"__v": 0
}'
To create a conversation it's required to define a companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a conversation it is required to specify in the payload the _id or the externalId or sourceId.
Since this is a bulk upsert operation it's possible to create and/or update multiple conversations with the same payload.
For more details please refer to the bulk upsert section.
There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"users": [
{
"id": "58e231b14246fc73139f29e8"
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42"
}
],
"activityTags": [],
"useSubject": true,
"ownerId": "58e231b14246fc73139f29e8"
}
]'
Example Response
200 ok
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "61672167d4ac8780f8f680af"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"61672167d4ac8780f8f680af"
],
"permissionErrors": []
}'
To create a conversation it's required to define a companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a conversation it is required to specify in the payload the _id or the externalId or sourceId.
Since this is a bulk upsert operation it's possible to create and/or update multiple conversations with the same payload.
For more details please refer to the bulk upsert section.
There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"users": [
{
"id": "58e231b14246fc73139f29e8"
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42"
}
],
"activityTags": [],
"useSubject": true,
"ownerId": "58e231b14246fc73139f29e8"
}
]'
Example Response
200 ok
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "61672167d4ac8780f8f680af"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"61672167d4ac8780f8f680af"
],
"permissionErrors": []
}'
To create a conversation it's required to define a companyId.
You can instead reference the company externalId or sourceId using the following command structure: "companyId": "extid-[company externalId]" or "companyId": "srcid-[company sourceId]".
To update a conversation it is required to specify in the payload the _id or the externalId or sourceId.
Since this is a bulk upsert operation it's possible to create and/or update multiple conversations with the same payload.
For more details please refer to the bulk upsert section.
There is an upper limit of 5,000 items per request.
Example Request
curl --location -g --request PUT 'https://api.planhat.com/conversations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{apiToken}}' \
--data-raw '[
{
"users": [
{
"id": "58e231b14246fc73139f29e8"
}
],
"date": "2021-07-29T15:29:34.330Z",
"type": "note",
"companyId": "61006bc89a3e0b702ed8ea49",
"subject": "New conversation",
"description": "Little call with the client.",
"endusers": [
{
"id": "610091916d643a7c418aef42"
}
],
"activityTags": [],
"useSubject": true,
"ownerId": "58e231b14246fc73139f29e8"
}
]'
Example Response
200 ok
'{
"created": 1,
"createdErrors": [],
"insertsKeys": [
{
"_id": "61672167d4ac8780f8f680af"
}
],
"updated": 0,
"updatedErrors": [],
"updatesKeys": [],
"nonupdates": 0,
"modified": [],
"upsertedIds": [
"61672167d4ac8780f8f680af"
],
"permissionErrors": []
}'