REST API: Messages

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 Message object

Property	Type	Description	Editable
id	string	Vitally's unique ID for the Message	No
type	"inbound" | "outbound"	The type of Message. Inferred from the sender type.	No
externalId	string	The unique ID of the message in your system	Only on create
timestamp	string	The ISO-formatted string timestamp of when the message was sent	Yes
message	string	Required The HTML content of the message.	Yes
from	Participant	Required A JSON object describing the sender Participant.	Yes
to	Participant[]	Required An array of JSON objects describing the recipient Participants.	Yes
cc	Participant[]	An array of JSON objects describing the cc recipient Participants.	Yes
bcc	Participant[]	An array of JSON objects describing the bcc recipient Participants.	Yes

The Participant Object

Participant

Property	Type	Description
type	string	"admin" or "user"
id	string	The unique Vitally ID of the Admin or User

Create A Message POST

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/conversations/:conversationId/messages

EU Data Center:

https://rest.vitally-eu.io/resources/conversations/:conversationId/messages

Request Body

Property	Type	Description
externalId	string	Required The unique ID of the message in your system
message	string	Required The HTML content of the message.
from	Participant	Required A JSON object describing the sender Participant.
to	Participant[]	Required An array of JSON objects describing the recipient Participants.
timestamp	string	The ISO-formatted string timestamp of when the message was sent
cc	Participant[]	An array of JSON objects describing the cc recipient Participants.
bcc	Participant[]	An array of JSON objects describing the bcc recipient Participants.

Participant

Property	Type	Description
type	string	"admin" or "user"
id	string	The ID of the Admin or User

Example Request

POST https://{subdomain}.rest.vitally.io/resources/conversations/:id/messages
{
  "externalId": "message-1",
  "conversationId": "thread-1",
  "message": "<p>Hello there</p>",
  "timestamp": "2020-12-11T20:16:27.370Z",
  "from": {
    "type": "admin",
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "to": [
    {
      "type": "user",
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

Example Response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "outbound",
  "externalId": "message-1",
  "externalUrl": null,
  "conversationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "message": "<p>Hello there</p>",
  "timestamp": "2020-12-11T20:16:27.370Z",
  "from": {
    "type": "admin",
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "to": [
    {
      "type": "user",
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],
  "cc": [],
  "bcc": []
}

Delete A Message DELETE

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/messages/:id

EU Data Center:

https://rest.vitally-eu.io/resources/messages/:id

Request Params

Property	Type	Description
id	string	The message ID assigned by Vitally