Links
Comment on page

REST API: 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
traits
Set of key-value pairs to attach to the User
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
source
The name of the integration your conversation originated in (eg google, intercom , etc)
No

List Conversations GET

Paginated list of Conversations, ordered by updatedAt.
https://rest.vitally.io/resources/conversations
Paginated list of Conversations for a single Account, ordered by updatedAt.
https://rest.vitally.io/resources/accounts/:accountId/conversations
Paginated list of Conversations for a single Organization, ordered by updatedAt.
https://rest.vitally.io/resources/organizations/:organizationId/conversations
Note: The above Conversations GET requests do not include Messages. Messages for a Conversation are retrieved separately.
Params (see Pagination)
Example Request
GET https://rest.vitally.io/resources/conversations?limit=10&from=cursor
Example Response
{
"results": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"externalId": "11",
"externalUrl": "https://externalsystem.com/11",
"subject": "Subject",
"traits": {
"expansionOpportunity": true,
}
}
],
"next": "c29tZWJhc2U2NA=="
}

Create A Conversation POST

https://rest.vitally.io/resources/conversations
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
POST https://rest.vitally.io/resources/conversations
{
"externalId": "thread-100",
"subject": "Regarding your account",
"messages": [{
"externalId": "message-101",
"message": "<p>Just checking in.</p>"
"from": { "type": "admin", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" },
"to": [
{ "type": "user", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" }
]
}],
"traits": {
"dealArr": 100000
}
}

Update A Conversation PUT

https://rest.vitally.io/resources/conversations/:id
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
PUT https://rest.vitally.io/resources/conversations/:id
{
"subject": "Thanks for the heads up!",
"messages": [{
"externalId": "message-102",
"message": "<p>Thanks for the heads up!</p>"
"from": { "type": "user", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" },
"to": [
{ "type": "admin", "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx" }
]
}],
"traits": {
"dealArr": 100000
}
}

Get A Conversation GET

https://rest.vitally.io/resources/conversations/:id
Retrieves a Conversation including all Messages.
Example Request
GET https://rest.vitally.io/resources/conversations/:id
Example Response
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"externalId": "11",
"externalUrl": "https://external.com/11",
"subject": "Subject",
"messages": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "outbound",
"externalId": "12345",
"conversationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"message": "<p>Hello there</p>",
"timestamp": "2020-12-04T18:37:55.000Z",
"from": {
"type": "admin",
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"to": [
{
"type": "user",
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
],
"cc": [],
"bcc": []
}
],
"traits": {
"outreachCampaignId": "abc123"
}
}