⚑
Other integrations
πŸ’Ÿ
Account health scores & metrics
Conversations

The Conversation object

Attribute
Description
Editable?
id
Vitally's unique ID for the Conversation
No
externalId
​Your unique ID for the Conversation
Only on create
subject
The subject of the Conversation.
Yes
name
An array of Message objects.
Yes
accounts
An array of Account objects. Associated implicitly via Message to and from.
No
users
An array of User objects. Associated implicitly via Message to and from.
No
admins
An array of Admin objects. Associated implicitly via Message to and from.
No

List Conversations GET

1
https://rest.vitally.io/resources/conversations
Copied!
Paginated list of Conversations, not including Messages, ordered by updatedAt. The Messages for a Conversation are retrieved separately.
Params (see Pagination)
Example Request
1
GET https://rest.vitally.io/resources/conversations?limit=10&from=cursor
Copied!
Example Response
1
{
2
"results": [
3
{
4
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
5
"externalId": "11",
6
"externalUrl": "https://externalsystem.com/11",
7
"subject": "Subject"
8
}
9
],
10
"next": "c29tZWJhc2U2NA=="
11
}
Copied!

Create A Conversation POST

1
https://rest.vitally.io/resources/conversations
Copied!
Create a new conversation with associated Messages.
Request Body
Property
Type
Description
externalId
string
The unique ID of this Conversation in your system
subject
string
The subject of the Conversation
messages
Message[]
An array of Message objects
Example
1
POST https://rest.vitally.io/resources/conversations
2
{
3
"externalId": "thread-100",
4
"subject": "Regarding your account",
5
"messages": [{
6
"externalId": "message-101",
7
"message": "<p>Just checking in.</p>"
8
"from": { "type": "admin", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" },
9
"to": [
10
{ "type": "user", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" }
11
]
12
}]
13
}
Copied!

Update A Conversation PUT

1
https://rest.vitally.io/resources/conversations
Copied!
Update an existing conversation with associated Messages. New messages can be inserted and existing ones will be updated by externalId.
Request Body
Property
Type
Description
subject
string
The subject of the conversation
messages
Message[]
An array of Message objects
Example
1
PUT https://rest.vitally.io/resources/conversations/:id
2
{
3
"subject": "Thanks for the heads up!",
4
"messages": [{
5
"externalId": "message-102",
6
"message": "<p>Thanks for the heads up!</p>"
7
"from": { "type": "user", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" },
8
"to": [
9
{ "type": "admin", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" }
10
]
11
}]
12
}
Copied!

Get A Conversation GET

1
https://rest.vitally.io/resources/conversations/:id
Copied!
Retrieves a Conversation including all Messages.
Example Request
1
GET https://rest.vitally.io/resources/conversations/:id
Copied!
Example Response
1
{
2
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
3
"externalId": "11",
4
"externalUrl": "https://external.com/11",
5
"subject": "Subject",
6
"messages": [
7
{
8
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9
"type": "outbound",
10
"externalId": "12345",
11
"conversationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
12
"message": "<p>Hello there</p>",
13
"timestamp": "2020-12-04T18:37:55.000Z",
14
"from": {
15
"type": "admin",
16
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
17
},
18
"to": [
19
{
20
"type": "user",
21
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
22
}
23
],
24
"cc": [],
25
"bcc": []
26
}
27
]
28
}
Copied!
Last modified 9mo ago