⚡️ Other integrations

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

https://rest.vitally.io/resources/conversations

Paginated list of Conversations, not including Messages, ordered by updatedAt. The 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"
}
],
"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" }
]
}]
}

Update A Conversation PUT

https://rest.vitally.io/resources/conversations

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" }
]
}]
}

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": []
}
]
}