Comment on page
REST API: Conversations
Attribute | Description | Editable? |
id | Vitally's unique ID for the Conversation | No |
externalId | 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 | No | |
users | No | |
admins | No | |
source | The name of the integration your conversation originated in (eg google, intercom , etc) | No |
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.
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=="
}
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[] |
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
}
}
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[] |
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
}
}
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"
}
}
Last modified 7d ago