Create a conversation - ProVision Public API

POST

conversation

submit

Create a conversation

curl --request POST \
  --url https://connect.provisionapp.io/v1/conversation/submit \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "subject": "<string>",
  "requesterId": "<string>",
  "snoozeUntil": "2023-11-07T05:31:56Z",
  "assigneeId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
  "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "senderId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
  "customProperties": {
    "warranty_count": 5,
    "region": "east",
    "onsite_required": true
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subject: '<string>',
    requesterId: '<string>',
    snoozeUntil: '2023-11-07T05:31:56Z',
    assigneeId: 'ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344',
    conversationAssigneeGroupId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    senderId: 'ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344',
    customProperties: {warranty_count: 5, region: 'east', onsite_required: true}
  })
};

fetch('https://connect.provisionapp.io/v1/conversation/submit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://connect.provisionapp.io/v1/conversation/submit"

payload = {
    "subject": "<string>",
    "requesterId": "<string>",
    "snoozeUntil": "2023-11-07T05:31:56Z",
    "assigneeId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
    "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "senderId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
    "customProperties": {
        "warranty_count": 5,
        "region": "east",
        "onsite_required": True
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "conversation": {
    "id": "<string>",
    "friendlyId": "<string>",
    "subject": "<string>",
    "snoozeUntil": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "deletedAt": "2023-11-07T05:31:56Z",
    "assigneeGroupUpdatedAt": "2023-11-07T05:31:56Z",
    "assigneeUpdatedAt": "2023-11-07T05:31:56Z",
    "conversationStatusUpdatedAt": "2023-11-07T05:31:56Z",
    "lastMessageReceivedAt": "2023-11-07T05:31:56Z",
    "requesterUpdatedAt": "2023-11-07T05:31:56Z",
    "customProperties": {
      "warranty_count": 5,
      "region": "east",
      "onsite_required": true
    },
    "sites": [
      {
        "id": "<string>",
        "address1": "<string>",
        "address2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "tosAccepted": "<string>",
        "clientSegment": "<string>",
        "cppExpDate": "2023-11-07T05:31:56Z",
        "businessName": "<string>",
        "brandId": "<string>",
        "primaryClientId": "<string>",
        "primaryProjectId": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "sla": 123,
        "isMonitored": true
      }
    ],
    "assigneeId": "<string>",
    "assignee": {
      "id": "<string>",
      "firstName": "<string>",
      "lastName": "<string>"
    },
    "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "conversationAssigneeGroup": {
      "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "requesterId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "requester": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "identityId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "email": "<string>"
    },
    "participants": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identityId": "<string>",
        "firstName": "<string>",
        "lastName": "<string>",
        "email": "<string>"
      }
    ],
    "labels": [
      "<string>"
    ]
  },
  "message": {
    "id": "<string>",
    "body": "<string>",
    "isPrivate": true
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

Authorizations

x-api-key

string

header

required

Send the API key in the x-api-key header.

Body

application/json

subject

string

required

requesterId

string

required

Pattern: ^ovcid-.*$

type

enum<string> | null

Available options:

support_ticket,

member_services,

non_support_event,

null

status

enum<string> | null

Available options:

new,

open,

snoozed,

on_hold,

solved,

closed,

null

urgency

enum<string> | null

Available options:

urgent,

normal,

low,

life_safety,

null

snoozeUntil

string<date-time>

assigneeId

string

Platform user id. Newer ids are ovuid-<uuid>; legacy users may have bare (e.g. numeric) ids.

Minimum string length: 1

Example:

"ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344"

conversationAssigneeGroupId

string<uuid>

senderId

string

Platform user id. Newer ids are ovuid-<uuid>; legacy users may have bare (e.g. numeric) ids.

Minimum string length: 1

Example:

"ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344"

message

object

Show child attributes

customProperties

object

Custom property values, keyed by property id. Ids and value types come from the properties defined for your partner, so this object cannot be described field by field here: an unknown id or a value that does not match the property type is rejected with 400. Only the ids you send are modified — omit a property to leave it untouched. To clear one, send null; a blank string and an empty array count as empty too, for every property type alike.

Show child attributes

Example:

{
  "warranty_count": 5,
  "region": "east",
  "onsite_required": true
}

Response

Created conversation

conversation

object

required

Show child attributes

message

object

required

Show child attributes

Create a conversation

curl --request POST \
  --url https://connect.provisionapp.io/v1/conversation/submit \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "subject": "<string>",
  "requesterId": "<string>",
  "snoozeUntil": "2023-11-07T05:31:56Z",
  "assigneeId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
  "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "senderId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
  "customProperties": {
    "warranty_count": 5,
    "region": "east",
    "onsite_required": true
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subject: '<string>',
    requesterId: '<string>',
    snoozeUntil: '2023-11-07T05:31:56Z',
    assigneeId: 'ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344',
    conversationAssigneeGroupId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    senderId: 'ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344',
    customProperties: {warranty_count: 5, region: 'east', onsite_required: true}
  })
};

fetch('https://connect.provisionapp.io/v1/conversation/submit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://connect.provisionapp.io/v1/conversation/submit"

payload = {
    "subject": "<string>",
    "requesterId": "<string>",
    "snoozeUntil": "2023-11-07T05:31:56Z",
    "assigneeId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
    "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "senderId": "ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344",
    "customProperties": {
        "warranty_count": 5,
        "region": "east",
        "onsite_required": True
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "conversation": {
    "id": "<string>",
    "friendlyId": "<string>",
    "subject": "<string>",
    "snoozeUntil": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "deletedAt": "2023-11-07T05:31:56Z",
    "assigneeGroupUpdatedAt": "2023-11-07T05:31:56Z",
    "assigneeUpdatedAt": "2023-11-07T05:31:56Z",
    "conversationStatusUpdatedAt": "2023-11-07T05:31:56Z",
    "lastMessageReceivedAt": "2023-11-07T05:31:56Z",
    "requesterUpdatedAt": "2023-11-07T05:31:56Z",
    "customProperties": {
      "warranty_count": 5,
      "region": "east",
      "onsite_required": true
    },
    "sites": [
      {
        "id": "<string>",
        "address1": "<string>",
        "address2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "tosAccepted": "<string>",
        "clientSegment": "<string>",
        "cppExpDate": "2023-11-07T05:31:56Z",
        "businessName": "<string>",
        "brandId": "<string>",
        "primaryClientId": "<string>",
        "primaryProjectId": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "sla": 123,
        "isMonitored": true
      }
    ],
    "assigneeId": "<string>",
    "assignee": {
      "id": "<string>",
      "firstName": "<string>",
      "lastName": "<string>"
    },
    "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "conversationAssigneeGroup": {
      "conversationAssigneeGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    },
    "requesterId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "requester": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "identityId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "email": "<string>"
    },
    "participants": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "identityId": "<string>",
        "firstName": "<string>",
        "lastName": "<string>",
        "email": "<string>"
      }
    ],
    "labels": [
      "<string>"
    ]
  },
  "message": {
    "id": "<string>",
    "body": "<string>",
    "isPrivate": true
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "<string>"
  }
}