The Conversation object
Attribute | Description | Editable? |
id | Vitally's unique ID for the Conversation |
|
createdAt | Datetime the conversation was created |
|
updatedAt | Datetime the conversation was updated |
|
externalId | Your unique ID for the Conversation |
|
subject | The subject of the Conversation |
|
messages | An array of Message objects |
|
name | An array of Message objects |
|
traits | Set of key-value pairs to attach to the User |
|
accounts | An array of Account objects. Associated implicitly via Message to and from. |
|
users | An array of User objects. Associated implicitly via Message to and from. |
|
status | Open/Closed status of the conversation. |
|
rating | Satisfied, Unsatisfied, or Neutral rating of the conversation. |
|
admins | An array of Admin objects. Associated implicitly via Message to and from. |
|
source | The name of the integration your conversation originated in (eg |
|
Replace {subdomain} in the endpoints below with your Vitally subdomain.
You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io
The Conversation endpoints do not start conversations with participants or send outbound messages. It creates/updates the conversation in Vitally as a point of reference. These endpoints can be used to create/update historical conversations from other tools into Vitally.
List Conversations GET
Paginated list of Conversations, ordered by updatedAt.
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/conversations
EU Data Center:
https://rest.vitally-eu.io/resources/conversations
Paginated list of Conversations for a single Account, ordered by updatedAt.
Must use Vitally ID for accountId
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/accounts/:accountId/conversations
EU Data Center:
https://rest.vitally-eu.io/resources/accounts/:accountId/conversations
Paginated list of Conversations for a single Organization, ordered by updatedAt.
Must use Vitally ID for organizationId
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/conversations
EU Data Center:
https://rest.vitally-eu.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://{subdomain}.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
Create a new conversation with associated Messages.
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/conversations
EU Data Center:
https://rest.vitally-eu.io/resources/conversations
Request Body
Property | Type | Description |
externalId |
| The unique ID of this Conversation in your system |
subject |
| Required The subject of the Conversation |
messages |
| Required An array of Message objects. Can accept an empty array |
Example
POST https://{subdomain}.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
Update an existing conversation with associated Messages. New messages can be inserted and existing ones will be updated by externalId.
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/conversations/:id
EU Data Center:
https://rest.vitally-eu.io/resources/conversations/:id
Request Body
Property | Type | Description |
subject |
| The subject of the conversation |
messages |
| An array of Message objects |
Example
PUT https://{subdomain}.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
Retrieves a Conversation including all Messages.
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/conversations/:id
EU Data Center:
https://rest.vitally-eu.io/resources/conversations/:id
Example Request
GET https://{subdomain}.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"
}
}
Delete A Conversation DELETE
Deletes a Conversation including all Messages.
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/conversations/:id
EU Data Center:
https://rest.vitally-eu.io/resources/conversations/:id
Example Request
DELETE https://{subdomain}.rest.vitally.io/resources/conversations/:id
Request Body
Property | Type | Description |
id |
| The ID of the conversation |