REST API: Conversations

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 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.

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.

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.

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	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://{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	string	The subject of the conversation
messages	Message[]	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"
  }
}