Overview

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Chaport REST API lets you integrate Chaport with your application and manage chats, visitors, and messages programmatically. This documentation covers available endpoints, request and response formats, and authentication.

Check out basic usage examples on the right side.

In addition to API endpoints, Chaport provides webhooks for receiving real-time events (for example, new messages or chat updates). See Webhooks and Events below.

Email: REST API Help

Base URLs:

• https://app.chaport.com/api/v1

Authentication

Authorization: Bearer <your-access-token>

All API requests must include the Authorization HTTP header with a bearer token (see the example on the right).

You can generate or copy your access token in Settings → API.

To verify that your token works, send a GET request to /me.json.

Operators

The Operators API lets you manage operators (team members) in your Chaport account.

List Operators

Code samples

GET https://app.chaport.com/api/v1/operators HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/operators',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/operators', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/operators',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /operators

Retrieves all existing operators.

Example responses

Status 200

{
  "result": [
    {
      "id": "59747c3ff77948220136b7b3",
      "email": "[email protected]",
      "name": "Jon Snow",
      "language": "en",
      "jobTitle": "The Wall supervisor",
      "role": "operator",
      "lastLoginAt": "2025-10-03T10:47:31.873Z",
      "emailConfirmedAt": "2025-10-02T09:44:12.873Z",
      "lastActivityAt": "2025-10-03T10:47:31.873Z",
      "image": "string",
      "lastStatus": "online",
      "lastStatusValidUntil": "2025-10-05T10:47:31.873Z",
      "realStatus": "online"
    }
  ]
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	[Operator]	true	List of operators
result.id	string	true	Operator ID
result.email	string(email)	true	Operator email address
result.name	string	true	Operator name
result.language	string	true	App language
result.jobTitle	string	false	Job title
result.role	string	true	operator – a generic operator, admin – an operator with advanced administrative permissions
result.lastLoginAt	string(date-time)	false	Time of the last login
result.emailConfirmedAt	string(date-time)	false	Time when the operator confirmed their email address
result.lastActivityAt	string(date-time)	false	Time of the most recent activity
result.image	string	false	Profile image
result.lastStatus	string	false	Last status explicitly set (manual or automatic)
result.lastStatusValidUntil	string(date-time)	false	Time until which lastStatus is considered valid when computing realStatus
result.realStatus	string	false	Effective status computed from presence and the last known status

Create an Operator

Code samples

POST https://app.chaport.com/api/v1/operators HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "email": "[email protected]",
  "name": "Jon Snow",
  "language": "en",
  "jobTitle": "The Wall supervisor",
  "role": "operator",
  "password": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/operators',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://app.chaport.com/api/v1/operators', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://app.chaport.com/api/v1/operators',
  params: {
  }, headers: headers

p JSON.parse(result)

POST /operators

Creates a new operator.

Example request body

{
  "email": "[email protected]",
  "name": "Jon Snow",
  "language": "en",
  "jobTitle": "The Wall supervisor",
  "role": "operator",
  "password": "string"
}

Body parameters

Parameter	Type	Required	Description
email	string(email)	true	Operator email address
name	string	true	Operator name
language	string	true	App language
jobTitle	string	false	Job title
role	string	true	operator – a generic operator, admin – an operator with advanced administrative permissions
password	string	false	Optional. If omitted, the operator must request an activation email from the login screen (log in without a password) and set their password

Example responses

Status 200

{
  "id": "string",
  "created": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
id	string	true	Operator ID
created	boolean	true	Whether a new operator has been created or not

Retrieve an Operator

Code samples

GET https://app.chaport.com/api/v1/operators/:operatorId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/operators/:operatorId',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/operators/:operatorId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/operators/:operatorId',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /operators/:operatorId

Retrieves a single operator by ID.

Path parameters

Parameter	Type	Required	Description
operatorId	string	true	Operator ID

Example responses

Status 200

{
  "result": {
    "id": "59747c3ff77948220136b7b3",
    "email": "[email protected]",
    "name": "Jon Snow",
    "language": "en",
    "jobTitle": "The Wall supervisor",
    "role": "operator",
    "lastLoginAt": "2025-10-03T10:47:31.873Z",
    "emailConfirmedAt": "2025-10-02T09:44:12.873Z",
    "lastActivityAt": "2025-10-03T10:47:31.873Z",
    "image": "string",
    "lastStatus": "online",
    "lastStatusValidUntil": "2025-10-05T10:47:31.873Z",
    "realStatus": "online"
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Operator not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	Operator	true	Operator
result.id	string	true	Operator ID
result.email	string(email)	true	Operator email address
result.name	string	true	Operator name
result.language	string	true	App language
result.jobTitle	string	false	Job title
result.role	string	true	operator – a generic operator, admin – an operator with advanced administrative permissions
result.lastLoginAt	string(date-time)	false	Time of the last login
result.emailConfirmedAt	string(date-time)	false	Time when the operator confirmed their email address
result.lastActivityAt	string(date-time)	false	Time of the most recent activity
result.image	string	false	Profile image
result.lastStatus	string	false	Last status explicitly set (manual or automatic)
result.lastStatusValidUntil	string(date-time)	false	Time until which lastStatus is considered valid when computing realStatus
result.realStatus	string	false	Effective status computed from presence and the last known status

Update an Operator

Code samples

PUT https://app.chaport.com/api/v1/operators/:operatorId HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "name": "Jon Snow",
  "language": "en",
  "jobTitle": "The Wall supervisor",
  "role": "operator"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/operators/:operatorId',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.put('https://app.chaport.com/api/v1/operators/:operatorId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.put 'https://app.chaport.com/api/v1/operators/:operatorId',
  params: {
  }, headers: headers

p JSON.parse(result)

PUT /operators/:operatorId

Updates an operator by ID.

Example request body

{
  "name": "Jon Snow",
  "language": "en",
  "jobTitle": "The Wall supervisor",
  "role": "operator"
}

Path parameters

Parameter	Type	Required	Description
operatorId	string	true	Operator ID

Body parameters

Parameter	Type	Required	Description
name	string	true	Operator name
language	string	true	App language
jobTitle	string	false	Job title
role	string	true	operator – a generic operator, admin – an operator with advanced administrative permissions

Example responses

Status 200

{
  "updated": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
400	Bad Request	Invalid or missing parameters in the request, find more details in the response body
404	Not Found	Operator not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
updated	boolean	true	Whether the operator has been updated or not

Delete an Operator

Code samples

DELETE https://app.chaport.com/api/v1/operators/:operatorId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/operators/:operatorId',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.delete('https://app.chaport.com/api/v1/operators/:operatorId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.delete 'https://app.chaport.com/api/v1/operators/:operatorId',
  params: {
  }, headers: headers

p JSON.parse(result)

DELETE /operators/:operatorId

Deletes an operator by ID.

Path parameters

Parameter	Type	Required	Description
operatorId	string	true	Operator ID

Example responses

Status 200

{
  "deleted": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
400	Bad Request	Invalid or missing parameters in the request, find more details in the response body
404	Not Found	Operator not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
deleted	boolean	true	Whether the operator has been deleted or not

Update Operator Status

Code samples

POST https://app.chaport.com/api/v1/operators/:operatorId/status HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "status": "online",
  "ttl": 3600,
  "validUntil": "2025-10-10T10:47:31.873Z"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/operators/:operatorId/status',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://app.chaport.com/api/v1/operators/:operatorId/status', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://app.chaport.com/api/v1/operators/:operatorId/status',
  params: {
  }, headers: headers

p JSON.parse(result)

POST /operators/:operatorId/status

Sets an operator's lastStatus. Provide exactly one of ttl or validUntil to control how long this status is treated as the operator’s effective status (realStatus).

Example request body

{
  "status": "online",
  "ttl": 3600,
  "validUntil": "2025-10-10T10:47:31.873Z"
}

Body parameters

Parameter	Type	Required	Description
status	string	true	Operator status
ttl	number(float)	false	Duration in seconds for which the status should remain valid unless changed manually. Alternative to validUntil
validUntil	string(date-time)	false	Time until which the status should remain valid unless changed manually. Alternative to ttl

Example responses

Status 200

{
  "updated": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Operator not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
updated	boolean	true	Whether the operator has been updated or not

Visitors

The Visitors API lets you read and update data associated with your website visitors.

List Visitors

Code samples

GET https://app.chaport.com/api/v1/visitors HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/visitors', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/visitors',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /visitors

Retrieves visitors ordered by the time of their most recent chat (most recent first).

Query parameters

Parameter	Type	Required	Description
page	integer	false	Results page number. Pages are 1-indexed. Use links.next and links.prev from response to fetch the next/previous page.

Example responses

Status 200

{
  "result": [
    {
      "id": "59747c3ff77948220136b7cd",
      "widgetId": "11111111-2222-eeee-bbbb-aaaaaa777777",
      "sourceHost": "example.com",
      "name": "London #1399",
      "referrer": "www.example.com",
      "language": "en",
      "lastSeen": "2017-10-03T10:47:31.873Z",
      "email": "[email protected]",
      "location": "United Kingdom, London",
      "custom": {},
      "consents": {
        "emailMarketing": true
      },
      "phone": "+44 (111) 111 11 11",
      "notes": "Asked us to notify him when the Others come. What is he talking about?",
      "utm": {
        "source": "string",
        "medium": "string",
        "term": "string",
        "campaign": "string",
        "content": "string"
      },
      "browser": {
        "name": "Chrome",
        "version": "67.0.3396.69"
      },
      "os": {
        "name": "OS X",
        "version": "14.14"
      }
    }
  ],
  "links": {
    "next": "string",
    "prev": "string"
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	[Visitor]	true	Page of visitors
result.id	string	true	Visitor ID
result.widgetId	string	true	Visitor ID assigned by the widget
result.sourceHost	string	false	Website from which the visitor contacted you
result.name	string	false	Visitor name. By default, name is likely to include identified geolocation and a visitor number. However, if IP geolocation is unsuccessful, a name may be an integer representing a visitor number only
result.referrer	string	false	Referrer
result.language	string	false	Widget UI language for this visitor. Typically derived from the visitor’s browser preferences, unless overridden by your JS API configuration
result.lastSeen	string(date-time)	false	Time when the visitor was last seen
result.email	string(email)	false	Visitor email address
result.location	string	false	Detected location (country and city when available)
result.custom	object	false	Custom visitor data. Configure your own visitor fields to display this data in visitor info panel
result.consents	object	false	Consents granted by the visitor
result.consents.emailMarketing	boolean	false	Whether email marketing consent is granted
result.phone	string	false	Visitor phone number (free-form)
result.notes	string	false	Visitor-related notes left by operators
result.utm	object	false	UTM parameters associated with the visitor
result.utm.source	string	false	UTM source
result.utm.medium	string	false	UTM medium
result.utm.term	string	false	UTM term
result.utm.campaign	string	false	UTM campaign
result.utm.content	string	false	UTM content
result.browser	object	false	Browser information
result.browser.name	string	false	Browser name
result.browser.version	string	false	Browser version
result.os	object	false	OS information
result.os.name	string	false	OS name
result.os.version	string	false	OS version
links	object	false	Pagination links
links.next	string	false	Relative URL to the next page of results if available
links.prev	string	false	Relative URL to the previous page of results if available

Retrieve a Visitor

Code samples

GET https://app.chaport.com/api/v1/visitors/:visitorId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/visitors/:visitorId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/visitors/:visitorId',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /visitors/:visitorId

Retrieves a visitor by ID.

Path parameters

Parameter	Type	Required	Description
visitorId	string	true	Visitor ID

Example responses

Status 200

{
  "result": {
    "id": "59747c3ff77948220136b7cd",
    "widgetId": "11111111-2222-eeee-bbbb-aaaaaa777777",
    "sourceHost": "example.com",
    "name": "London #1399",
    "referrer": "www.example.com",
    "language": "en",
    "lastSeen": "2017-10-03T10:47:31.873Z",
    "email": "[email protected]",
    "location": "United Kingdom, London",
    "custom": {},
    "consents": {
      "emailMarketing": true
    },
    "phone": "+44 (111) 111 11 11",
    "notes": "Asked us to notify him when the Others come. What is he talking about?",
    "utm": {
      "source": "string",
      "medium": "string",
      "term": "string",
      "campaign": "string",
      "content": "string"
    },
    "browser": {
      "name": "Chrome",
      "version": "67.0.3396.69"
    },
    "os": {
      "name": "OS X",
      "version": "14.14"
    }
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Visitor not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	Visitor	true	Visitor
result.id	string	true	Visitor ID
result.widgetId	string	true	Visitor ID assigned by the widget
result.sourceHost	string	false	Website from which the visitor contacted you
result.name	string	false	Visitor name. By default, name is likely to include identified geolocation and a visitor number. However, if IP geolocation is unsuccessful, a name may be an integer representing a visitor number only
result.referrer	string	false	Referrer
result.language	string	false	Widget UI language for this visitor. Typically derived from the visitor’s browser preferences, unless overridden by your JS API configuration
result.lastSeen	string(date-time)	false	Time when the visitor was last seen
result.email	string(email)	false	Visitor email address
result.location	string	false	Detected location (country and city when available)
result.custom	object	false	Custom visitor data. Configure your own visitor fields to display this data in visitor info panel
result.consents	object	false	Consents granted by the visitor
result.consents.emailMarketing	boolean	false	Whether email marketing consent is granted
result.phone	string	false	Visitor phone number (free-form)
result.notes	string	false	Visitor-related notes left by operators
result.utm	object	false	UTM parameters associated with the visitor
result.utm.source	string	false	UTM source
result.utm.medium	string	false	UTM medium
result.utm.term	string	false	UTM term
result.utm.campaign	string	false	UTM campaign
result.utm.content	string	false	UTM content
result.browser	object	false	Browser information
result.browser.name	string	false	Browser name
result.browser.version	string	false	Browser version
result.os	object	false	OS information
result.os.name	string	false	OS name
result.os.version	string	false	OS version

Update a Visitor

Code samples

PUT https://app.chaport.com/api/v1/visitors/:visitorId HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "sourceHost": "example.com",
  "name": "London #1399",
  "email": "[email protected]",
  "custom": {},
  "consents": {
    "emailMarketing": true
  },
  "phone": "+44 (111) 111 11 11",
  "notes": "Asked us to notify him when the Others come. What is he talking about?",
  "utm": {
    "source": "string",
    "medium": "string",
    "term": "string",
    "campaign": "string",
    "content": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.put('https://app.chaport.com/api/v1/visitors/:visitorId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.put 'https://app.chaport.com/api/v1/visitors/:visitorId',
  params: {
  }, headers: headers

p JSON.parse(result)

PUT /visitors/:visitorId

Updates a visitor by ID. Updates only the fields provided in the request body. Omitted fields are not changed. Response contains updated visitor data.

Example request body

{
  "sourceHost": "example.com",
  "name": "London #1399",
  "email": "[email protected]",
  "custom": {},
  "consents": {
    "emailMarketing": true
  },
  "phone": "+44 (111) 111 11 11",
  "notes": "Asked us to notify him when the Others come. What is he talking about?",
  "utm": {
    "source": "string",
    "medium": "string",
    "term": "string",
    "campaign": "string",
    "content": "string"
  }
}

Path parameters

Parameter	Type	Required	Description
visitorId	string	true	Visitor ID

Body parameters

Parameter	Type	Required	Description
sourceHost	string	false	Website from which the visitor contacted you
name	string	false	Visitor name. By default, name is likely to include identified geolocation and a visitor number. However, if IP geolocation is unsuccessful, a name may be an integer representing a visitor number only
email	string(email)	false	Visitor email address
custom	object	false	Custom visitor data. Configure your own visitor fields to display this data in visitor info panel
consents	object	false	Consents granted by the visitor
consents.emailMarketing	boolean	false	Whether email marketing consent is granted
phone	string	false	Visitor phone number (free-form)
notes	string	false	Visitor-related notes left by operators
utm	object	false	UTM parameters associated with the visitor
utm.source	string	false	UTM source
utm.medium	string	false	UTM medium
utm.term	string	false	UTM term
utm.campaign	string	false	UTM campaign
utm.content	string	false	UTM content

Example responses

Status 200

{
  "updated": {
    "id": "59747c3ff77948220136b7cd",
    "widgetId": "11111111-2222-eeee-bbbb-aaaaaa777777",
    "sourceHost": "example.com",
    "name": "London #1399",
    "referrer": "www.example.com",
    "language": "en",
    "lastSeen": "2017-10-03T10:47:31.873Z",
    "email": "[email protected]",
    "location": "United Kingdom, London",
    "custom": {},
    "consents": {
      "emailMarketing": true
    },
    "phone": "+44 (111) 111 11 11",
    "notes": "Asked us to notify him when the Others come. What is he talking about?",
    "utm": {
      "source": "string",
      "medium": "string",
      "term": "string",
      "campaign": "string",
      "content": "string"
    },
    "browser": {
      "name": "Chrome",
      "version": "67.0.3396.69"
    },
    "os": {
      "name": "OS X",
      "version": "14.14"
    }
  }
}

Responses

Status	Meaning	Description
200	OK	Successfully updated. The response returns the updated visitor object in updated
404	Not Found	Visitor not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
updated	Visitor	true	Updated visitor object
updated.id	string	true	Visitor ID
updated.widgetId	string	true	Visitor ID assigned by the widget
updated.sourceHost	string	false	Website from which the visitor contacted you
updated.name	string	false	Visitor name. By default, name is likely to include identified geolocation and a visitor number. However, if IP geolocation is unsuccessful, a name may be an integer representing a visitor number only
updated.referrer	string	false	Referrer
updated.language	string	false	Widget UI language for this visitor. Typically derived from the visitor’s browser preferences, unless overridden by your JS API configuration
updated.lastSeen	string(date-time)	false	Time when the visitor was last seen
updated.email	string(email)	false	Visitor email address
updated.location	string	false	Detected location (country and city when available)
updated.custom	object	false	Custom visitor data. Configure your own visitor fields to display this data in visitor info panel
updated.consents	object	false	Consents granted by the visitor
updated.consents.emailMarketing	boolean	false	Whether email marketing consent is granted
updated.phone	string	false	Visitor phone number (free-form)
updated.notes	string	false	Visitor-related notes left by operators
updated.utm	object	false	UTM parameters associated with the visitor
updated.utm.source	string	false	UTM source
updated.utm.medium	string	false	UTM medium
updated.utm.term	string	false	UTM term
updated.utm.campaign	string	false	UTM campaign
updated.utm.content	string	false	UTM content
updated.browser	object	false	Browser information
updated.browser.name	string	false	Browser name
updated.browser.version	string	false	Browser version
updated.os	object	false	OS information
updated.os.name	string	false	OS name
updated.os.version	string	false	OS version

Delete a Visitor

Code samples

DELETE https://app.chaport.com/api/v1/visitors/:visitorId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.delete('https://app.chaport.com/api/v1/visitors/:visitorId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.delete 'https://app.chaport.com/api/v1/visitors/:visitorId',
  params: {
  }, headers: headers

p JSON.parse(result)

DELETE /visitors/:visitorId

Deletes a visitor by ID.

Path parameters

Parameter	Type	Required	Description
visitorId	string	true	Visitor ID

Example responses

Status 200

{
  "deleted": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Visitor not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
deleted	boolean	true	Whether the visitor has been deleted or not

Chats

The Chats API lets you read and update chats.

Retrieve Last Visitor Chat

Code samples

GET https://app.chaport.com/api/v1/visitors/:visitorId/chats HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId/chats',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/visitors/:visitorId/chats', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/visitors/:visitorId/chats',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /visitors/:visitorId/chats

Retrieves the visitor’s current or most recent chat. To fetch older chats, use the URLs in links.more from the response.

Path parameters

Parameter	Type	Required	Description
visitorId	string	true	Visitor ID

Query parameters

Parameter	Type	Required	Description
eventTypes	array	false	List of event types to include. Ignored when transcript=true
transcript	boolean	false	If true, returns events as a transcript (message events only)

Example responses

Status 200

{
  "result": {
    "id": 120904824,
    "startedAt": "2017-10-03T10:47:31.873Z",
    "startPage": {
      "url": "https://example.com/some-page",
      "title": "Example.com | Home page"
    },
    "rating": 1,
    "ip": "string",
    "initiator": "visitor",
    "events": [
      [
        {
          "type": "visitor-message",
          "timestamp": "2018-09-25T13:14:01Z",
          "params": {
            "text": "Hello! How do I do this thing?"
          }
        },
        {
          "type": "operator-message",
          "timestamp": "2018-09-25T13:14:13Z",
          "params": {
            "operatorId": "123abc123abc123abc123abc",
            "text": "Hello! To do this thing please do that thing and follow instructions on the screen."
          }
        }
      ]
    ],
    "stage": "engaged",
    "operators": [
      "123894abc958123894abc958"
    ],
    "assignedTeam": "123894abc958123894abc958",
    "lastMessageAt": "2017-10-03T10:57:31.873Z",
    "lastMessageChannel": "facebook",
    "lastMessageChannelId": "123abc123abc123abc123abc",
    "missed": false
  },
  "links": {
    "app": "string",
    "more": [
      "string"
    ]
  }
}

Status 404

{
  "links": {
    "more": [
      "string"
    ]
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Chat not found. Response may contain links to related chats
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	Chat	true	Chat
result.id	integer	false	Chat ID
result.startedAt	string(date-time)	false	Time when the chat was started
result.startPage	object	false	Details of the page where the chat was initiated
result.startPage.url	string	true	Start page URL
result.startPage.title	string	true	Start page title
result.rating	integer	false	Rating given to the chat by visitor
result.ip	string	false	Visitor IP address during this chat
result.initiator	string	false	Chat initiator. Possible values are: auto-invitation, chat-bot, operator, visitor, system
result.events	[ChatEvent]	false	List of the chat events
result.events.type	string	true	Type of the chat event (i.e., a chat event discriminator)
result.events.timestamp	string(date-time)	true	Time of the chat event
result.stage	string	false	Chat stage Values: initiated – visitor started a chat, no operator reply yet offline - like initiated, but all operators were offline responded – operator replied; visitor has not replied since engaged - visitor messaged after an operator message (conversation started) invited manually – operator initiated a chat; visitor did not reply closed - operator closed the chat without sending a message
result.operators	[string]	false	Assigned operators IDs
result.assignedTeam	string	false	Assigned team ID
result.lastMessageAt	string(date-time)	false	Time of the last message
result.lastMessageChannel	string	false	Channel (integration name) through which last message came
result.lastMessageChannelId	string	false	Integration ID
result.missed	boolean	false	Whether the chat is considered missed
links	object	false	Related API URLs
links.app	string	false	App link
links.more	[string]	false	API URLs to request other chats

Response Schema

Status Code 404

Name	Type	Required	Description
links	object	false	Related API URLs
links.more	[string]	false	API URLs to request other chats

Update Last Visitor Chat

Code samples

PUT https://app.chaport.com/api/v1/visitors/:visitorId/chats HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "startPage": {
    "url": "https://example.com/some-page",
    "title": "Example.com | Home page"
  },
  "rating": 1,
  "stage": "engaged",
  "operators": [
    "123894abc958123894abc958"
  ],
  "missed": false
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId/chats',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.put('https://app.chaport.com/api/v1/visitors/:visitorId/chats', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.put 'https://app.chaport.com/api/v1/visitors/:visitorId/chats',
  params: {
  }, headers: headers

p JSON.parse(result)

PUT /visitors/:visitorId/chats

Updates the visitor’s current or most recent chat. Updates only the fields provided in the request body. Omitted fields are not changed.

To reassign the chat, pass operators as an array with a single operator or team ID. To unassign, pass an empty array.

Example request body

{
  "startPage": {
    "url": "https://example.com/some-page",
    "title": "Example.com | Home page"
  },
  "rating": 1,
  "stage": "engaged",
  "operators": [
    "123894abc958123894abc958"
  ],
  "missed": false
}

Path parameters

Parameter	Type	Required	Description
visitorId	string	true	Visitor ID

Body parameters

Parameter	Type	Required	Description
startPage	object	false	Details of the page where the chat was initiated
startPage.url	string	true	Start page URL
startPage.title	string	true	Start page title
rating	integer	false	Rating given to the chat by visitor
stage	string	false	Chat stage Values: initiated – visitor started a chat, no operator reply yet offline - like initiated, but all operators were offline responded – operator replied; visitor has not replied since engaged - visitor messaged after an operator message (conversation started) invited manually – operator initiated a chat; visitor did not reply closed - operator closed the chat without sending a message
operators	[string]	false	Assigned operators IDs
missed	boolean	false	Whether the chat is considered missed

Example responses

Status 200

{
  "updated": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
400	Bad Request	Invalid or missing parameters in the request, find more details in the response body
404	Not Found	Chat not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
updated	boolean	true	Whether the chat has been updated or not

Retrieve a Chat

Code samples

GET https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /visitors/:visitorId/chats/:chatId

Retrieves a chat by the visitor ID and the chat ID.

Path parameters

Parameter	Type	Required	Description
visitorId	string	true	Visitor ID
chatId	integer	true	Chat ID

Query parameters

Parameter	Type	Required	Description
eventTypes	array	false	Chat event types to be included in the response. Ignored if transcript is requested.
transcript	boolean	false	Pass true to retrieve chat events as a transcript. Only includes message events.

Example responses

Status 200

{
  "result": {
    "id": 120904824,
    "startedAt": "2017-10-03T10:47:31.873Z",
    "startPage": {
      "url": "https://example.com/some-page",
      "title": "Example.com | Home page"
    },
    "rating": 1,
    "ip": "string",
    "initiator": "visitor",
    "events": [
      [
        {
          "type": "visitor-message",
          "timestamp": "2018-09-25T13:14:01Z",
          "params": {
            "text": "Hello! How do I do this thing?"
          }
        },
        {
          "type": "operator-message",
          "timestamp": "2018-09-25T13:14:13Z",
          "params": {
            "operatorId": "123abc123abc123abc123abc",
            "text": "Hello! To do this thing please do that thing and follow instructions on the screen."
          }
        }
      ]
    ],
    "stage": "engaged",
    "operators": [
      "123894abc958123894abc958"
    ],
    "assignedTeam": "123894abc958123894abc958",
    "lastMessageAt": "2017-10-03T10:57:31.873Z",
    "lastMessageChannel": "facebook",
    "lastMessageChannelId": "123abc123abc123abc123abc",
    "missed": false
  },
  "links": {
    "app": "string",
    "more": [
      "string"
    ]
  }
}

Status 404

{
  "links": {
    "more": [
      "string"
    ]
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Chat not found. Response may contain links to related chats
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	Chat	true	Chat
result.id	integer	false	Chat ID
result.startedAt	string(date-time)	false	Time when the chat was started
result.startPage	object	false	Details of the page where the chat was initiated
result.startPage.url	string	true	Start page URL
result.startPage.title	string	true	Start page title
result.rating	integer	false	Rating given to the chat by visitor
result.ip	string	false	Visitor IP address during this chat
result.initiator	string	false	Chat initiator. Possible values are: auto-invitation, chat-bot, operator, visitor, system
result.events	[ChatEvent]	false	List of the chat events
result.events.type	string	true	Type of the chat event (i.e., a chat event discriminator)
result.events.timestamp	string(date-time)	true	Time of the chat event
result.stage	string	false	Chat stage Values: initiated – visitor started a chat, no operator reply yet offline - like initiated, but all operators were offline responded – operator replied; visitor has not replied since engaged - visitor messaged after an operator message (conversation started) invited manually – operator initiated a chat; visitor did not reply closed - operator closed the chat without sending a message
result.operators	[string]	false	Assigned operators IDs
result.assignedTeam	string	false	Assigned team ID
result.lastMessageAt	string(date-time)	false	Time of the last message
result.lastMessageChannel	string	false	Channel (integration name) through which last message came
result.lastMessageChannelId	string	false	Integration ID
result.missed	boolean	false	Whether the chat is considered missed
links	object	false	Related API URLs
links.app	string	false	App link
links.more	[string]	false	API URLs to request other chats

Response Schema

Status Code 404

Name	Type	Required	Description
links	object	false	Related API URLs
links.more	[string]	false	API URLs to request other chats

List Chat Events

Code samples

GET https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /visitors/:visitorId/chats/:chatId/events

Retrieves all chat events for the specified chat.

Example responses

Status 200

{
  "result": [
    {
      "type": "string",
      "timestamp": "2026-01-14T10:50:23Z"
    }
  ]
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	[ChatEvent]	true	Abstract base for all chat events
result.type	string	true	Type of the chat event (i.e., a chat event discriminator)
result.timestamp	string(date-time)	true	Time of the chat event

Retrieve a Chat Event

Code samples

GET https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events/:eventId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events/:eventId',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events/:eventId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/visitors/:visitorId/chats/:chatId/events/:eventId',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /visitors/:visitorId/chats/:chatId/events/:eventId

Retrieves a chat event.

Example responses

Status 200

{
  "result": {
    "type": "string",
    "timestamp": "2026-01-14T10:50:23Z"
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Chat event not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	ChatEvent	true	Chat event
result.type	string	true	Type of the chat event (i.e., a chat event discriminator)
result.timestamp	string(date-time)	true	Time of the chat event

Messages

The Messages API lets you create, update, and delete message events in chats. It can create a visitor and start a new chat automatically when needed, which makes it suitable for chatbot and external integration workflows.

Send a Message

Code samples

POST https://app.chaport.com/api/v1/messages HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "visitorId": "stringstringstringstring",
  "widgetVisitorId": "string",
  "platform": "facebook",
  "platformVisitorId": "12378421",
  "chatEvent": {
    "type": "visitor-message",
    "params": {
      "text": "Help me!"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/messages',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://app.chaport.com/api/v1/messages', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://app.chaport.com/api/v1/messages',
  params: {
  }, headers: headers

p JSON.parse(result)

POST /messages

Creates a message event. If the visitor does not exist, a visitor is created. If there is no recent chat, a new chat may be created.

Example request body

{
  "visitorId": "stringstringstringstring",
  "widgetVisitorId": "string",
  "platform": "facebook",
  "platformVisitorId": "12378421",
  "chatEvent": {
    "type": "visitor-message",
    "params": {
      "text": "Help me!"
    }
  }
}

Body parameters

Parameter	Type	Required	Description
visitorId	string	false	Visitor ID. If provided, identifies the visitor to send the message for
widgetVisitorId	string	false	Visitor ID assigned by the widget (alternative identifier)
platform	string	false	Platform the visitor comes from (for example, facebook or custom)
platformVisitorId	string	false	Visitor ID on the specified platform (alternative identifier)
chatEvent	ChatEvent	true	Message event to create. Supports visitor and operator message events

Example responses

Status 200

{
  "id": "def123def123def123def123",
  "created": true,
  "visitor": {
    "id": "cbc543cbc543cbc543cbc543",
    "created": false
  },
  "chat": {
    "id": 91032841204,
    "created": true
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
id	string	true	Message event ID
created	boolean	false	Whether the message event was created or not
visitor	object	false	Properties of the associated visitor
visitor.id	string	false	Visitor ID
visitor.created	boolean	false	Whether a visitor had to be created or not
chat	object	false	Properties of the associated chat
chat.id	integer	false	Chat ID
chat.created	boolean	false	Whether a new chat had to be created or not

Update a Message

Code samples

PUT https://app.chaport.com/api/v1/messages?visitorId=stringstringstringstring&chatEventId=string HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "deliveryStatus": "sending",
  "failureMessage": "string",
  "text": "string",
  "isRich": true
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/messages?visitorId=stringstringstringstring&chatEventId=string',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.put('https://app.chaport.com/api/v1/messages', params={
  'visitorId': 'stringstringstringstring',  'chatEventId': 'string'
}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.put 'https://app.chaport.com/api/v1/messages',
  params: {
  'visitorId' => 'string',
'chatEventId' => 'string'
}, headers: headers

p JSON.parse(result)

PUT /messages

Updates a message event. Identify the visitor using visitorId or widgetVisitorId, and identify the message using chatEventId or chatEventExternalId.

Example request body

{
  "deliveryStatus": "sending",
  "failureMessage": "string",
  "text": "string",
  "isRich": true
}

Query parameters

Parameter	Type	Required	Description
visitorId	string	true, if widgetVisitorId is not provided	Visitor ID
widgetVisitorId	string	false	Visitor ID assigned by the widget
chatEventId	string	true, if chatEventExternalId is not provided	Chat event ID
chatEventExternalId	string	false	External chat event ID (see Send a message)

Body parameters

Parameter	Type	Required	Description
deliveryStatus	string	false	Delivery status (one of sending, failed, success)
failureMessage	string	false	Failure reason (when deliveryStatus=failed)
text	string	false	Updated message text
isRich	boolean	false	Whether text contains Markdown formatting. Supported for operator messages only

Example responses

Status 200

{
  "updated": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
updated	boolean	true	Whether the chat event has been updated or not

Delete a Message

Code samples

DELETE https://app.chaport.com/api/v1/messages?visitorId=stringstringstringstring&chatEventId=string HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/messages?visitorId=stringstringstringstring&chatEventId=string',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.delete('https://app.chaport.com/api/v1/messages', params={
  'visitorId': 'stringstringstringstring',  'chatEventId': 'string'
}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.delete 'https://app.chaport.com/api/v1/messages',
  params: {
  'visitorId' => 'string',
'chatEventId' => 'string'
}, headers: headers

p JSON.parse(result)

DELETE /messages

Deletes a message event. Identify the visitor using visitorId or widgetVisitorId, and identify the message using chatEventId or chatEventExternalId.

Query parameters

Parameter	Type	Required	Description
visitorId	string	true, if widgetVisitorId is not provided	Visitor ID
widgetVisitorId	string	false	Visitor ID assigned by the widget
chatEventId	string	true, if chatEventExternalId is not provided	Chat event ID
chatEventExternalId	string	false	External chat event ID (see Send a message)

Example responses

Status 200

{
  "deleted": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
deleted	boolean	true	Whether the chat event has been deleted or not

Webhooks

Chaport can notify your application when certain events happen. The Webhooks API allows you to view and manage your webhook subscriptions.

Webhook notifications are delivered as HTTP POST requests to your targetUrl. Your endpoint should respond with a status code according to the table below.

Status	Meaning	Description
2xx	OK	Notification accepted (no retry)
404	Not Found	Rejected permanently (no retry)
410	Gone	Subscription is no longer valid (no retry). Chaport will delete the webhook subscription and stop sending notifications
Other 4xx and 5xx	Other error	Delivery failed and will be retried several times with an increasing delay (starting at a few minutes and gradually increasing up to a few hours)

See webhook events.

List Webhooks

Code samples

GET https://app.chaport.com/api/v1/events/subscriptions HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/events/subscriptions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/events/subscriptions', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/events/subscriptions',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /events/subscriptions

Retrieves a list of your webhooks.

Example responses

Status 200

{
  "result": [
    {
      "id": "59747c3ff77948220136b7aa",
      "targetUrl": "http://your-server.com/notify",
      "event": [
        "chat.started",
        "chat.finished"
      ],
      "createdAt": "2017-10-12T10:47:31.873Z"
    }
  ]
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	[Webhook]	true	List of webhooks
result.id	string	false	Webhook ID
result.targetUrl	string	true	Event notifications are sent to this URL
result.event	[string]	true	Array of event names
result.createdAt	string(date-time)	false	Time the webhook was created

Create a Webhook

Code samples

POST https://app.chaport.com/api/v1/events/subscriptions HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "targetUrl": "http://your-server.com/notify",
  "event": [
    "chat.started",
    "chat.finished"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/events/subscriptions',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://app.chaport.com/api/v1/events/subscriptions', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://app.chaport.com/api/v1/events/subscriptions',
  params: {
  }, headers: headers

p JSON.parse(result)

POST /events/subscriptions

Creates a new webhook. See webhook events.

Example request body

{
  "targetUrl": "http://your-server.com/notify",
  "event": [
    "chat.started",
    "chat.finished"
  ]
}

Body parameters

Parameter	Type	Required	Description
targetUrl	string	true	Event notifications are sent to this URL
event	[string]	true	Array of event names

Example responses

Status 200

{
  "id": "string",
  "created": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
id	string	true	Webhook ID
created	boolean	true	Whether a new webhook has been created or not

Retrieve a Webhook

Code samples

GET https://app.chaport.com/api/v1/events/subscriptions/:hookId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/events/subscriptions/:hookId',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://app.chaport.com/api/v1/events/subscriptions/:hookId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://app.chaport.com/api/v1/events/subscriptions/:hookId',
  params: {
  }, headers: headers

p JSON.parse(result)

GET /events/subscriptions/:hookId

Retrieves a webhook by ID.

Path parameters

Parameter	Type	Required	Description
hookId	string	true	Webhook ID

Example responses

Status 200

{
  "result": {
    "id": "59747c3ff77948220136b7aa",
    "targetUrl": "http://your-server.com/notify",
    "event": [
      "chat.started",
      "chat.finished"
    ],
    "createdAt": "2017-10-12T10:47:31.873Z"
  }
}

Responses

Status	Meaning	Description
200	OK	Successful request
404	Not Found	Webhook not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
result	Webhook	true	Webhook
result.id	string	false	Webhook ID
result.targetUrl	string	true	Event notifications are sent to this URL
result.event	[string]	true	Array of event names
result.createdAt	string(date-time)	false	Time the webhook was created

Update a Webhook

Code samples

PUT https://app.chaport.com/api/v1/events/subscriptions/:hookId HTTP/1.1
Host: app.chaport.com
Content-Type: application/json
Accept: application/json

const request = require('node-fetch');
const inputBody = '{
  "targetUrl": "http://your-server.com/notify",
  "event": [
    "chat.started",
    "chat.finished"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/events/subscriptions/:hookId',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.put('https://app.chaport.com/api/v1/events/subscriptions/:hookId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.put 'https://app.chaport.com/api/v1/events/subscriptions/:hookId',
  params: {
  }, headers: headers

p JSON.parse(result)

PUT /events/subscriptions/:hookId

Updates a webhook by ID. Updates only the fields provided in the request body. Omitted fields are not changed.

Example request body

{
  "targetUrl": "http://your-server.com/notify",
  "event": [
    "chat.started",
    "chat.finished"
  ]
}

Path parameters

Parameter	Type	Required	Description
hookId	string	true	Webhook ID

Body parameters

Parameter	Type	Required	Description
targetUrl	string	true	Event notifications are sent to this URL
event	[string]	true	Array of event names

Example responses

Status 200

{
  "updated": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
400	Bad Request	Invalid or missing parameters in the request, find more details in the response body
404	Not Found	Webhook not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
updated	boolean	true	Whether the webhook has been updated or not

Delete a Webhook

Code samples

DELETE https://app.chaport.com/api/v1/events/subscriptions/:hookId HTTP/1.1
Host: app.chaport.com

Accept: application/json

const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://app.chaport.com/api/v1/events/subscriptions/:hookId',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.delete('https://app.chaport.com/api/v1/events/subscriptions/:hookId', params={

}, headers = headers)

print r.json()

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.delete 'https://app.chaport.com/api/v1/events/subscriptions/:hookId',
  params: {
  }, headers: headers

p JSON.parse(result)

DELETE /events/subscriptions/:hookId

Deletes a webhook by ID.

Path parameters

Parameter	Type	Required	Description
hookId	string	true	Webhook ID

Example responses

Status 200

{
  "deleted": true
}

Responses

Status	Meaning	Description
200	OK	Successful request
400	Bad Request	Invalid or missing parameters in the request, find more details in the response body
404	Not Found	Webhook not found
500	Internal Server Error	Server was unable to process the request due to an internal error

Response Schema

Status Code 200

Name	Type	Required	Description
deleted	boolean	true	Whether the webhook has been deleted or not

Webhook Events

This section lists webhook events that you can subscribe to using the Webhooks API.

Visitor Created

Webhook payload sample

{
  "event": "visitor.created",
  "link": "/api/v1/visitors/123abc123abc123abc123abc"
}

Subscribe with event=visitor.created when creating a webhook.

This event fires when a new visitor is created (typically when they start their first chat).

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
link	string	true	Relative API URL to retrieve the created visitor

Visitor Updated

Webhook payload sample

{
  "event": "visitor.updated",
  "link": "/api/v1/visitors/123abc123abc123abc123abc",
  "extras": {
    "fields": [
      "name",
      "email"
    ]
  }
}

Subscribe with event=visitor.updated when creating a webhook.

This event fires when one or more of the following visitor fields get updated: name, email, phone, notes, custom and consents.

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
link	string	true	Relative API URL to retrieve the updated visitor
extras	object	false	Additional event context
extras.fields	[string]	false	List of updated fields

Chat Started

Webhook payload sample

{
  "event": "chat.started",
  "link": "/api/v1/visitors/123abc123abc123abc123abc/chats",
  "extras": {
    "visitorId": "789dfe789dfe789dfe789dfe",
    "chatId": 123123123123,
    "stage": "initiated"
  }
}

Subscribe with event=chat.started when creating a webhook.

This event fires when a new chat is started. Note: if the chat is renewed (i.e., one of the participants sends a new message shortly after the chat was marked as finished) this event doesn't fire again.

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
link	string	true	Relative API URL to retrieve the started chat
extras	object	false	Additional event context
extras.visitorId	string	false	Visitor ID
extras.chatId	integer	false	Chat ID
extras.stage	string	false	Current stage of the chat

Chat Finished

Webhook payload sample

{
  "event": "chat.finished",
  "link": "/api/v1/visitors/123abc123abc123abc123abc/chats",
  "extras": {
    "visitorId": "789dfe789dfe789dfe789dfe"
  }
}

Subscribe with event=chat.finished when creating a webhook.

This event fires after a chat is idle for about 10 minutes. Note: a chat can be restarted shortly after it was finished, so this event may fire multiple times for the same chat.

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
link	string	true	Relative API URL to retrieve the finished chat
extras	object	false	Additional event context
extras.visitorId	string	false	Visitor ID

Chat Closed

Webhook payload sample

{
  "event": "chat.closed",
  "link": "/api/v1/visitors/123abc123abc123abc123abc/chats",
  "extras": {
    "visitorId": "789dfe789dfe789dfe789dfe",
    "action": "close"
  }
}

Subscribe with event=chat.closed when creating a webhook.

This event fires when a chat is closed. If chat is re-opened and closed again at some point, this event fires again.

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
link	string	true	Relative API URL to retrieve the closed chat
extras	object	false	Additional event context
extras.visitorId	string	false	Visitor ID
extras.action	string	false	Action that caused the chat to close: close, auto-close or mute.

Close actions

• close – manually closed by an operator
• auto-close – closed by the system due to a Close answered chats automatically setting
• mute – closed as a side-effect of the visitor being banned in chat

Chat Stage Updated

Webhook payload sample

{
  "event": "chat.stage.updated",
  "payload": {
    "visitorId": "789dfe789dfe789dfe789dfe",
    "chatId": 131238712374,
    "oldStage": "initiated",
    "newStage": "responded"
  }
}

Subscribe with event=chat.stage.updated when creating a webhook.

This event fires whenever a chat stage is updated.

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
payload	object	true	Holder of the webhook payload
payload.visitorId	string	true	Visitor ID
payload.chatId	integer	true	Chat ID
payload.oldStage	string	true	Chat stage before update
payload.newStage	string	true	Chat stage after update

Message Sent

Webhook payload sample

{
  "event": "chat.newEvent",
  "link": "/api/v1/visitors/123abc123abc123abc123abc/chats/123123123123/events/cba321cba321cba321cba321",
  "extras": {
    "operatorId": "123abc123abc123abc123abc",
    "visitorId": "789dfe789dfe789dfe789dfe",
    "chatId": 12389012374583,
    "stage": "engaged",
    "eventType": "visitor-message",
    "chatEventId": "123cde123cde123cde123cde"
  }
}

Subscribe to one or several of these events to receive relevant message notifications:

• chat.newEvent.operatorMessage – operator sent a text message
• chat.newEvent.operatorFileTransfer - operator sent a file
• chat.newEvent.visitorMessage – visitor sent a text message
• chat.newEvent.visitorFileTransfer – visitor sent a file
• chat.newEvent.botMessage – chat bot sent a text message
• chat.newEvent.faqMessage – chat bot suggested FAQ articles
• chat.newEvent – any of the above messages

Don't subscribe to both chat.newEvent and specific message events to avoid duplicate webhook notifications. If you prefer receiving all messages, subscribe to chat.newEvent, otherwise subscribe to specific message events. To get the full message data, fetch link.

See how to create a webhook.

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
link	string	true	Relative API URL to retrieve the chat event
extras	object	true	Additional event context
extras.operatorId	string	false	Operator ID (only for operator messages)
extras.visitorId	string	true	Visitor ID
extras.chatId	integer	true	Chat ID
extras.stage	string	true	Current chat stage
extras.eventType	string	true	Chat event type
extras.chatEventId	string	true	Chat event ID
extras.chatEventExternalId	string	false	Chat event external ID (for externally sourced messages)
extras.platform	string	false	External platform name (e.g., Facebook)
extras.platformVisitorId	string	false	Visitor ID granted by the external platform (e.g., Facebook user ID for Facebook)

Message Read

Webhook payload sample

{
  "event": "chat.messageRead",
  "payload": {
    "visitorId": "789dfe789dfe789dfe789dfe",
    "operatorId": "123dfe123dfe123dfe123dfe",
    "unread": 0
  }
}

Subscribe with event=chat.messageRead when creating a webhook.

This event fires whenever any of the chat participants read unread messages.

Payload parameters

Parameter	Type	Required	Description
event	string	true	Event name
payload	object	true	Holder of the webhook payload
payload.visitorId	string	true	Visitor ID
payload.operatorId	string	true	Operator ID
payload.unread	integer	true	Number of remaining unread messages

Schemas

Chat

{
  "id": 120904824,
  "startedAt": "2017-10-03T10:47:31.873Z",
  "startPage": {
    "url": "https://example.com/some-page",
    "title": "Example.com | Home page"
  },
  "rating": 1,
  "ip": "string",
  "initiator": "visitor",
  "events": [
    [
      {
        "type": "visitor-message",
        "timestamp": "2018-09-25T13:14:01Z",
        "params": {
          "text": "Hello! How do I do this thing?"
        }
      },
      {
        "type": "operator-message",
        "timestamp": "2018-09-25T13:14:13Z",
        "params": {
          "operatorId": "123abc123abc123abc123abc",
          "text": "Hello! To do this thing please do that thing and follow instructions on the screen."
        }
      }
    ]
  ],
  "stage": "engaged",
  "operators": [
    "123894abc958123894abc958"
  ],
  "assignedTeam": "123894abc958123894abc958",
  "lastMessageAt": "2017-10-03T10:57:31.873Z",
  "lastMessageChannel": "facebook",
  "lastMessageChannelId": "123abc123abc123abc123abc",
  "missed": false
} 

Properties

Name	Type	Required	Description
id	integer	false	Chat ID
startedAt	string(date-time)	false	Time when the chat was started
startPage	object	false	Details of the page where the chat was initiated
startPage.url	string	true	Start page URL
startPage.title	string	true	Start page title
rating	integer	false	Rating given to the chat by visitor
ip	string	false	Visitor IP address during this chat
initiator	string	false	Chat initiator. Possible values are: auto-invitation, chat-bot, operator, visitor, system
events	[ChatEvent]	false	List of the chat events
events.type	string	true	Type of the chat event (i.e., a chat event discriminator)
events.timestamp	string(date-time)	true	Time of the chat event
stage	string	false	Chat stage Values: initiated – visitor started a chat, no operator reply yet offline - like initiated, but all operators were offline responded – operator replied; visitor has not replied since engaged - visitor messaged after an operator message (conversation started) invited manually – operator initiated a chat; visitor did not reply closed - operator closed the chat without sending a message
operators	[string]	false	Assigned operators IDs
assignedTeam	string	false	Assigned team ID
lastMessageAt	string(date-time)	false	Time of the last message
lastMessageChannel	string	false	Channel (integration name) through which last message came
lastMessageChannelId	string	false	Integration ID
missed	boolean	false	Whether the chat is considered missed

ChatUpdate

{
  "startPage": {
    "url": "https://example.com/some-page",
    "title": "Example.com | Home page"
  },
  "rating": 1,
  "stage": "engaged",
  "operators": [
    "123894abc958123894abc958"
  ],
  "missed": false
} 

Properties

Name	Type	Required	Description
startPage	object	false	Details of the page where the chat was initiated
startPage.url	string	true	Start page URL
startPage.title	string	true	Start page title
rating	integer	false	Rating given to the chat by visitor
stage	string	false	Chat stage Values: initiated – visitor started a chat, no operator reply yet offline - like initiated, but all operators were offline responded – operator replied; visitor has not replied since engaged - visitor messaged after an operator message (conversation started) invited manually – operator initiated a chat; visitor did not reply closed - operator closed the chat without sending a message
operators	[string]	false	Assigned operators IDs
missed	boolean	false	Whether the chat is considered missed

Operator

{
  "id": "59747c3ff77948220136b7b3",
  "email": "[email protected]",
  "name": "Jon Snow",
  "language": "en",
  "jobTitle": "The Wall supervisor",
  "role": "operator",
  "lastLoginAt": "2025-10-03T10:47:31.873Z",
  "emailConfirmedAt": "2025-10-02T09:44:12.873Z",
  "lastActivityAt": "2025-10-03T10:47:31.873Z",
  "image": "string",
  "lastStatus": "online",
  "lastStatusValidUntil": "2025-10-05T10:47:31.873Z",
  "realStatus": "online"
} 

Properties

Name	Type	Required	Description
id	string	true	Operator ID
email	string(email)	true	Operator email address
name	string	true	Operator name
language	string	true	App language
jobTitle	string	false	Job title
role	string	true	operator – a generic operator, admin – an operator with advanced administrative permissions
lastLoginAt	string(date-time)	false	Time of the last login
emailConfirmedAt	string(date-time)	false	Time when the operator confirmed their email address
lastActivityAt	string(date-time)	false	Time of the most recent activity
image	string	false	Profile image
lastStatus	string	false	Last status explicitly set (manual or automatic)
lastStatusValidUntil	string(date-time)	false	Time until which lastStatus is considered valid when computing realStatus
realStatus	string	false	Effective status computed from presence and the last known status

OperatorCreate

{
  "email": "[email protected]",
  "name": "Jon Snow",
  "language": "en",
  "jobTitle": "The Wall supervisor",
  "role": "operator",
  "password": "string"
} 

Properties

Name	Type	Required	Description
email	string(email)	true	Operator email address
name	string	true	Operator name
language	string	true	App language
jobTitle	string	false	Job title
role	string	true	operator – a generic operator, admin – an operator with advanced administrative permissions
password	string	false	Optional. If omitted, the operator must request an activation email from the login screen (log in without a password) and set their password

OperatorStatusUpdate

{
  "status": "online",
  "ttl": 3600,
  "validUntil": "2025-10-10T10:47:31.873Z"
} 

Properties

Name	Type	Required	Description
status	string	true	Operator status
ttl	number(float)	false	Duration in seconds for which the status should remain valid unless changed manually. Alternative to validUntil
validUntil	string(date-time)	false	Time until which the status should remain valid unless changed manually. Alternative to ttl

OperatorUpdate

{
  "name": "Jon Snow",
  "language": "en",
  "jobTitle": "The Wall supervisor",
  "role": "operator"
} 

Properties

Name	Type	Required	Description
name	string	true	Operator name
language	string	true	App language
jobTitle	string	false	Job title
role	string	true	operator – a generic operator, admin – an operator with advanced administrative permissions

Visitor

{
  "id": "59747c3ff77948220136b7cd",
  "widgetId": "11111111-2222-eeee-bbbb-aaaaaa777777",
  "sourceHost": "example.com",
  "name": "London #1399",
  "referrer": "www.example.com",
  "language": "en",
  "lastSeen": "2017-10-03T10:47:31.873Z",
  "email": "[email protected]",
  "location": "United Kingdom, London",
  "custom": {},
  "consents": {
    "emailMarketing": true
  },
  "phone": "+44 (111) 111 11 11",
  "notes": "Asked us to notify him when the Others come. What is he talking about?",
  "utm": {
    "source": "string",
    "medium": "string",
    "term": "string",
    "campaign": "string",
    "content": "string"
  },
  "browser": {
    "name": "Chrome",
    "version": "67.0.3396.69"
  },
  "os": {
    "name": "OS X",
    "version": "14.14"
  }
} 

Properties

Name	Type	Required	Description
id	string	true	Visitor ID
widgetId	string	true	Visitor ID assigned by the widget
sourceHost	string	false	Website from which the visitor contacted you
name	string	false	Visitor name. By default, name is likely to include identified geolocation and a visitor number. However, if IP geolocation is unsuccessful, a name may be an integer representing a visitor number only
referrer	string	false	Referrer
language	string	false	Widget UI language for this visitor. Typically derived from the visitor’s browser preferences, unless overridden by your JS API configuration
lastSeen	string(date-time)	false	Time when the visitor was last seen
email	string(email)	false	Visitor email address
location	string	false	Detected location (country and city when available)
custom	object	false	Custom visitor data. Configure your own visitor fields to display this data in visitor info panel
consents	object	false	Consents granted by the visitor
consents.emailMarketing	boolean	false	Whether email marketing consent is granted
phone	string	false	Visitor phone number (free-form)
notes	string	false	Visitor-related notes left by operators
utm	object	false	UTM parameters associated with the visitor
utm.source	string	false	UTM source
utm.medium	string	false	UTM medium
utm.term	string	false	UTM term
utm.campaign	string	false	UTM campaign
utm.content	string	false	UTM content
browser	object	false	Browser information
browser.name	string	false	Browser name
browser.version	string	false	Browser version
os	object	false	OS information
os.name	string	false	OS name
os.version	string	false	OS version

VisitorWrite

{
  "sourceHost": "example.com",
  "name": "London #1399",
  "email": "[email protected]",
  "custom": {},
  "consents": {
    "emailMarketing": true
  },
  "phone": "+44 (111) 111 11 11",
  "notes": "Asked us to notify him when the Others come. What is he talking about?",
  "utm": {
    "source": "string",
    "medium": "string",
    "term": "string",
    "campaign": "string",
    "content": "string"
  }
} 

Properties

Name	Type	Required	Description
sourceHost	string	false	Website from which the visitor contacted you
name	string	false	Visitor name. By default, name is likely to include identified geolocation and a visitor number. However, if IP geolocation is unsuccessful, a name may be an integer representing a visitor number only
email	string(email)	false	Visitor email address
custom	object	false	Custom visitor data. Configure your own visitor fields to display this data in visitor info panel
consents	object	false	Consents granted by the visitor
consents.emailMarketing	boolean	false	Whether email marketing consent is granted
phone	string	false	Visitor phone number (free-form)
notes	string	false	Visitor-related notes left by operators
utm	object	false	UTM parameters associated with the visitor
utm.source	string	false	UTM source
utm.medium	string	false	UTM medium
utm.term	string	false	UTM term
utm.campaign	string	false	UTM campaign
utm.content	string	false	UTM content

Webhook

{
  "id": "59747c3ff77948220136b7aa",
  "targetUrl": "http://your-server.com/notify",
  "event": [
    "chat.started",
    "chat.finished"
  ],
  "createdAt": "2017-10-12T10:47:31.873Z"
} 

Properties

Name	Type	Required	Description
id	string	false	Webhook ID
targetUrl	string	true	Event notifications are sent to this URL
event	[string]	true	Array of event names
createdAt	string(date-time)	false	Time the webhook was created

WebhookWrite

{
  "targetUrl": "http://your-server.com/notify",
  "event": [
    "chat.started",
    "chat.finished"
  ]
} 

Properties

Name	Type	Required	Description
targetUrl	string	true	Event notifications are sent to this URL
event	[string]	true	Array of event names

ChatEvent

{
  "type": "string",
  "timestamp": "2026-01-14T10:50:23Z"
} 

Properties

Name	Type	Required	Description
type	string	true	Type of the chat event (i.e., a chat event discriminator)
timestamp	string(date-time)	true	Time of the chat event

EmailRequestChatEvent

{
  "type": "email-request",
  "timestamp": "2017-08-28T08:24:56.899Z"
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to email-request
timestamp	string(date-time)	true	Time of the chat event

OperatorChangeChatEvent

{
  "type": "operator-change",
  "timestamp": "2017-08-28T08:24:56.899Z",
  "params": {
    "operatorId": "123abc123abc123abc123abc",
    "targetOperatorId": "321cba321cba321cba321cba"
  }
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to operator-change
timestamp	string(date-time)	true	Time of the chat event
params	object	false	Parameters specific to operator-change event
params.operatorId	string	false	ID of the transferring operator. If at the time this operator is assigned to the chat, this assignment is removed
params.targetOperatorId	string	false	ID of the operator to be assigned to the chat.

OperatorInviteChatEvent

{
  "type": "operator-invite",
  "timestamp": "2017-08-28T08:24:56.899Z",
  "params": {
    "operatorId": "123abc123abc123abc123abc",
    "targetOperatorId": "321cba321cba321cba321cba"
  }
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to operator-invite
timestamp	string(date-time)	true	Time of the chat event
params	object	false	Parameters specific to a operator-invite event
params.operatorId	string	false	ID of the inviting operator.
params.targetOperatorId	string	false	ID of the operator being invited.

OperatorMessageChatEvent

{
  "type": "operator-message",
  "timestamp": "2017-08-28T08:24:56.899Z",
  "params": {
    "operatorId": "123abc123abc123abc123abc",
    "text": "You can find whatever your are looking for wherever you are looking at."
  }
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to operator-message
timestamp	string(date-time)	true	Time of the chat event
params	object	false	Parameters specific to operator's message
params.text	string	false	Text of the message
params.operatorId	string	false	ID of the authoring operator

TriggerMessageChatEvent

{
  "type": "trigger-message",
  "timestamp": "2017-08-28T08:24:56.899Z",
  "params": {
    "text": "Hey! How can I help you?"
  }
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to trigger-message
timestamp	string(date-time)	true	Time of the chat event
params	object	false	Parameters specific to trigger messages
params.text	string	false	Text of the message

VisitorMessageChatEvent

{
  "type": "visitor-message",
  "timestamp": "2017-08-28T08:24:56.899Z",
  "params": {
    "text": "Hello! I have a question regarding your application form. Can you help me?"
  }
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to visitor-message
timestamp	string(date-time)	true	Time of the chat event
params	object	false	Parameters specific to visitor's message
params.text	string	false	Text of the message

VisitorMutedChatEvent

{
  "type": "visitor-muted",
  "timestamp": "2017-08-28T08:24:56.899Z",
  "params": {
    "operatorId": "123abc123abc123abc123abc",
    "mute": true
  }
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to visitor-muted
timestamp	string(date-time)	true	Time of the chat event
params	object	false	Parameters specific to visitor-ban event.
params.operatorId	string	false	ID of the operator banning/unbanning the visitor
params.mute	boolean	false	true if visitor is banned, false if the ban is lifted.

VisitorOpenedPageChatEvent

{
  "type": "visitor-opened-page",
  "timestamp": "2017-08-28T08:24:56.899Z",
  "params": {
    "url": "https://your-website.com/opened-page",
    "title": "HTML title of the opened page"
  }
} 

Properties

Name	Type	Required	Description
type	string	true	Equals to visitor-opened-page
timestamp	string(date-time)	true	Time of the chat event
params	object	false	Parameters specific to open-page chat events
params.url	string	false	URL of the opened page
params.title	string	false	HTML title of the opened page

Javascript API

To customize the chat widget on your website (identify users, pass visitor data, and more), see the Javascript API docs.