REST API Reference (V1)

Updated on July 11, 2024

The Crisp REST API offers access and control over all Crisp data (conversations, contacts and more).

All resources that you will most likely use are prefixed with a star symbol (⭐).

While integrating the REST API, you may be interested in the following guides:


You may also download the ⬇️ Postman collection that we provide for the Crisp REST API.

Basein Website

Check If Website Exists

HEAD
/v1/website{?domain}

Checks if given website exists (by domain).

URI Parameters
domain
stringRequired

The website domain to check against

  • HEADhttps://api.crisp.chat/v1/website
  • Tiersuserplugin
HTTP
Request
(loading)
Response
(loading)

Create Website

POST
/v1/website

Creates a new website.

Request Body
name
stringRequired

Website name

domain
stringRequired

Website domain

  • POSThttps://api.crisp.chat/v1/website
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Get A Website

GET
/v1/website/{website_id}

Resolves an existing website information.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
website_id
string

Website identifier

name
string

Website name

domain
string

Website domain

logo
string

Website custom logo image URL (can be blank)

  • GEThttps://api.crisp.chat/v1/website/website_id
  • Tiersuserplugin
HTTP
Request
(loading)
Response
(loading)

Delete A Website

DELETE
/v1/website/{website_id}

Deletes an existing website.

The deletion will be scheduled and not processed immediately, for security reasons. It will be executed after a few days. All website owners will be notified of the ongoing deletion via email, which they can request a cancellation.
URI Parameters
website_id
stringRequired

The website identifier

Request Body
verify
stringRequired

User password (used to double-authenticate deletion)

  • DELETEhttps://api.crisp.chat/v1/website/website_id
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Abort Website Deletion

DELETE
/v1/website/{website_id}/expunge

Aborts scheduled deletion for an existing website.

URI Parameters
website_id
stringRequired

The website identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/expunge
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Conversationsin Website

⭐ List Conversations

GET
/v1/website/{website_id}/conversations/{page_number}{?per_page}{&search_query}{&search_type}{&search_operator}{&include_empty}{&filter_unread}{&filter_resolved}{&filter_not_resolved}{&filter_mention}{&filter_assigned}{&filter_unassigned}{&filter_date_start}{&filter_date_end}{&order_date_created}{&order_date_updated}{&order_date_waiting}

Lists conversations for website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

Page number for conversations paging

per_page
stringOptional

Page size for conversations paging (between 20 and 50, defaults to 20)

search_query
stringOptional

Search query in all conversations (text if type is text or segment, filter if type is filter)

search_type
stringOptional

Search type (either text, segment or filter)

search_operator
stringOptional

Search operator if search type is filter (or or and respectful to boolean algebra, defaults to and if not set)

include_empty
stringOptional

Whether to include conversations without any message (1 or 0, defaults to 0)

filter_unread
stringOptional

Whether to return only conversations with unread messages (1 or 0, defaults to 0)

filter_resolved
stringOptional

Whether to return only conversations that are resolved (1 or 0, defaults to 0)

filter_not_resolved
stringOptional

Whether to return only conversations that are not resolved (1 or 0, defaults to 0)

filter_mention
stringOptional

Whether to return only conversations where user is mentioned (1 or 0, defaults to 0)

filter_assigned
stringOptional

Whether to return only conversations that are assigned to user identifier

filter_unassigned
stringOptional

Whether to return only conversations that are not assigned to any user (1 or 0, defaults to 0)

filter_date_start
stringOptional

When to start relative to conversation update date (date, ISO 8601, eg. 2018-03-01T17:00:00.000Z)

filter_date_end
stringOptional

When to end relative to conversation update date (date, ISO 8601, eg. 2018-04-01T10:30:00.000Z)

order_date_created
stringOptional

Whether to order conversations by date created instead of default order (1 or 0, defaults to 0)

order_date_updated
stringOptional

Whether to order conversations by date updated instead of default order (1 or 0, defaults to 0)

order_date_waiting
stringOptional

Whether to order conversations by longest date waiting instead of default order, this also filters out non-waiting conversations (1 or 0, defaults to 0)

Response Data
error
boolean
reason
string
data
array[object]
session_id
string

Session identifier

website_id
string

Website identifier

people_id
string

People identifier

state
enum[string]

Conversation state

Values

  • pending
  • unresolved
  • resolved
status
enum[number]

Conversation status (an alias of state; useful for sorting conversations)

Values

  • 1
  • 2
is_verified
boolean

Whether session is verified or not (user email ownership is authenticated)

is_blocked
boolean

Whether session is blocked or not (block messages from visitor)

availability
enum[string]

Visitor availability

Values

  • online
  • offline
active
object

User activity statistics (eg. moved their mouse if reported from the Crisp chatbox)

now
boolean

Whether user is considered active right now or not

last
number

Timestamp at which the user was last active

last_message
string

Last message excerpt (from visitor)

preview_message
object

Preview of conversation (message from visitor or operator)

type
enum[string]

Preview message type

Values

  • text
  • note
  • file
  • animation
  • audio
  • picker
  • field
  • carousel
from
enum[string]

Preview message sender

Values

  • user
  • operator
excerpt
string

Preview message excerpt

fingerprint
number

Preview message fingerprint

topic
string

Topic for conversation (based on messages)

participants
array[object]

External participants for this conversation

type
enum[string]

External participant type

Values

  • email
target
string

External participant target (ie. email address, identifier, etc.)

mentions
array[string]

Mentioned user identifiers (from conversation messages)

created_at
number

Conversation creation timestamp

updated_at
number

Conversation update timestamp

waiting_since
number

Conversation waiting since timestamp (if any)

compose
object

Compose states

operator
object

Compose state for operator

type
enum[string]

Compose state type

Values

  • start
  • stop
excerpt
string

Message excerpt for compose state

timestamp
number

Timestamp for compose state

user
object

Compose user information

user_id
string

Compose user identifier

nickname
string

Compose user nickname

avatar
string

Compose user avatar

automated
boolean

Whether compose is automated or not (ie. comes from a bot)

visitor
object

Compose state for visitor

type
enum[string]

Compose state type

Values

  • start
  • stop
excerpt
string

Message excerpt for compose state

timestamp
number

Timestamp for compose state

automated
boolean

Whether compose is automated or not (ie. comes from a bot)

unread
object

Unread messages counters

operator
number

Unread messages counter for operator

visitor
number

Unread messages counter for visitor

assigned
object

Assigned operator (if any)

user_id
string

Operator user identifier

meta
object

Meta-data for conversation

nickname
string

Visitor nickname

email
string

Visitor email

phone
string

Visitor phone

address
string

Visitor address

subject
string

Subject for conversation (if any)

ip
string

Visitor IP address

data
object

Visitor data

avatar
string

Visitor avatar

device
object

Device information

capabilities
array[enum[string]]

Visitor device capabilities

Values

  • browsing
  • call
geolocation
object

Geolocation information for visitor device

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

system
object

Visitor device system information

os
object

Operating system information

version
string

OS version

name
string

OS name

engine
object

Rendering engine information

version
string

Engine version

name
string

Engine name

browser
object

Browser information

major
string

Browser major version (eg: version 8.1 has a major of 8)

version
string

Browser version

name
string

Browser name

useragent
string

Visitor user agent

timezone
number

Visitor device timezone offset (UTC)

locales
array[string]

Visitor device locales

segments
array[string]

Segments attributed to conversation

  • GEThttps://api.crisp.chat/v1/website/website_id/conversations/page_number
  • Tiersuserplugin
  • Scopeswebsite:conversation:sessions
HTTP
Request
(loading)
Response
(loading)

List Suggested Conversation Segments

GET
/v1/website/{website_id}/conversations/suggest/segments/{page_number}

Lists suggested conversation segments for website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

The page number (paging in segment list)

Response Data
error
boolean
reason
string
data
array[object]
segment
string

Segment value

count
number

Number of occurences of this segment

  • GEThttps://api.crisp.chat/v1/website/website_id/conversations/suggest/segments/page_number
  • Tiersuserplugin
  • Scopeswebsite:conversation:suggest
HTTP
Request
(loading)
Response
(loading)

Delete Suggested Conversation Segment

DELETE
/v1/website/{website_id}/conversations/suggest/segment

Deletes a suggested conversation segment for website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
segment
stringRequired

Segment to be deleted from suggestions

  • DELETEhttps://api.crisp.chat/v1/website/website_id/conversations/suggest/segment
  • Tiersuserplugin
  • Scopeswebsite:conversation:suggest
HTTP
Request
(loading)
Response
(loading)

List Suggested Conversation Data Keys

GET
/v1/website/{website_id}/conversations/suggest/data/{page_number}

Lists suggested conversation data keys for website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

The page number (paging in data list)

Response Data
error
boolean
reason
string
data
array[object]
key
string

Data key value

count
number

Number of occurences of this data key

  • GEThttps://api.crisp.chat/v1/website/website_id/conversations/suggest/data/page_number
  • Tiersuserplugin
  • Scopeswebsite:conversation:suggest
HTTP
Request
(loading)
Response
(loading)

Delete Suggested Conversation Data Key

DELETE
/v1/website/{website_id}/conversations/suggest/data

Deletes a suggested conversation data key for website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
key
stringRequired

Data key to be deleted from suggestions

  • DELETEhttps://api.crisp.chat/v1/website/website_id/conversations/suggest/data
  • Tiersuserplugin
  • Scopeswebsite:conversation:suggest
HTTP
Request
(loading)
Response
(loading)

Conversationin Website

⭐ Create A New Conversation

POST
/v1/website/{website_id}/conversation

Creates a new conversation.

This conversation will not be visible in your Crisp Inbox until a message is sent with an user from value.
URI Parameters
website_id
stringRequired

The website identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation
  • Tiersuserplugin
  • Scopeswebsite:conversation:initiate
HTTP
Request
(loading)
Response
(loading)

Check If Conversation Exists

HEAD
/v1/website/{website_id}/conversation/{session_id}

Checks if given conversation session identifier exists.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

  • HEADhttps://api.crisp.chat/v1/website/website_id/conversation/session_id
  • Tiersuserplugin
  • Scopeswebsite:conversation:sessions
HTTP
Request
(loading)
Response
(loading)

⭐ Get A Conversation

GET
/v1/website/{website_id}/conversation/{session_id}

Resolves conversation information.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
session_id
string

Session identifier

website_id
string

Website identifier

people_id
string

People identifier

state
enum[string]

Conversation state

Values

  • pending
  • unresolved
  • resolved
status
enum[number]

Conversation status (an alias of state; useful for sorting conversations)

Values

  • 1
  • 2
is_verified
boolean

Whether session is verified or not (user email ownership is authenticated)

is_blocked
boolean

Whether session is blocked or not (block messages from visitor)

availability
enum[string]

Visitor availability

Values

  • online
  • offline
active
object

User activity statistics (eg. moved their mouse if reported from the Crisp chatbox)

now
boolean

Whether user is considered active right now or not

last
number

Timestamp at which the user was last active

last_message
string

Last message excerpt

preview_message
object

Preview of conversation (message from visitor or operator)

type
enum[string]

Preview message type

Values

  • text
  • note
  • file
  • animation
  • audio
  • picker
  • field
  • carousel
from
enum[string]

Preview message sender

Values

  • user
  • operator
excerpt
string

Preview message excerpt

fingerprint
number

Preview message fingerprint

topic
string

Topic for conversation (based on messages)

mentions
array[string]

Mentioned user identifiers (from conversation messages)

participants
array[object]

External participants for this conversation

type
enum[string]

External participant type

Values

  • email
target
string

External participant target (ie. email address, identifier, etc.)

created_at
number

Conversation creation timestamp

updated_at
number

Conversation update timestamp

waiting_since
number

Conversation waiting since timestamp (if any)

compose
object

Compose states

operator
object

Compose state for operator

type
enum[string]

Compose state type

Values

  • start
  • stop
excerpt
string

Message excerpt for compose state

timestamp
number

Timestamp for compose state

user
object

Compose user information

user_id
string

Compose user identifier

nickname
string

Compose user nickname

avatar
string

Compose user avatar

automated
boolean

Whether compose is automated or not (ie. comes from a bot)

visitor
object

Compose state for visitor

type
enum[string]

Compose state type

Values

  • start
  • stop
excerpt
string

Message excerpt for compose state

timestamp
number

Timestamp for compose state

automated
boolean

Whether compose is automated or not (ie. comes from a bot)

unread
object

Unread messages counters

operator
number

Unread messages counter for operator

visitor
number

Unread messages counter for visitor

assigned
object

Assigned operator (if any)

user_id
string

Operator user identifier

meta
object

Meta-data for conversation

nickname
string

Visitor nickname

email
string

Visitor email

phone
string

Visitor phone

address
string

Visitor address

subject
string

Subject for conversation (if any)

ip
string

Visitor IP address

data
object

Visitor data

avatar
string

Visitor avatar

device
object

Device information

capabilities
array[enum[string]]

Visitor device capabilities

Values

  • browsing
  • call
geolocation
object

Geolocation information for visitor device

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

system
object

Visitor device system information

os
object

Operating system information

version
string

OS version

name
string

OS name

engine
object

Rendering engine information

version
string

Engine version

name
string

Engine name

browser
object

Browser information

major
string

Browser major version (eg: version 8.1 has a major of 8)

version
string

Browser version

name
string

Browser name

useragent
string

Visitor user agent

timezone
number

Visitor device timezone offset (UTC)

locales
array[string]

Visitor device locales

segments
array[string]

Segments attributed to conversation

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id
  • Tiersuserplugin
  • Scopeswebsite:conversation:sessions
HTTP
Request
(loading)
Response
(loading)

Remove A Conversation

DELETE
/v1/website/{website_id}/conversation/{session_id}

Removes a conversation in website.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/conversation/session_id
  • Tiersuserplugin
  • Scopeswebsite:conversation:sessions
HTTP
Request
(loading)
Response
(loading)

Initiate A Conversation With Existing Session

POST
/v1/website/{website_id}/conversation/{session_id}/initiate

Initiates a conversation from an existing session.

Used to initiate a conversation from website visitor list.

The client acknowledgement is sent back asynchronously on the RTM Events channel, using the event namespace session:request:initiated.

This method shall not be used to create a conversation. Please use Create a New Conversation instead.
URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/initiate
  • Tiersuserplugin
  • Scopeswebsite:conversation:initiate
HTTP
Request
(loading)
Response
(loading)

⭐ Get Messages In Conversation

GET
/v1/website/{website_id}/conversation/{session_id}/messages{?timestamp_before}

Resolves messages in an existing conversation. Returns the last batch of messages if there are many messages in the conversation. Then, messages can be paged up to most recent message using the timestamp_before parameter.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

timestamp_before
stringOptional

Returned message batch should end before given timestamp (used for infinite scroll paging)

Response Data
error
boolean
reason
string
data
array[object]
session_id
string

Session identifier

website_id
string

Website identifier

type
enum[string]

Message type

Values

  • text
  • note
  • file
  • animation
  • audio
  • picker
  • field
  • carousel
  • event
from
enum[string]

Message sender

Values

  • user
  • operator
origin
enum[string]

Message origin

Values

  • chat
  • email
  • urn:*
content
object

Message content (string if type is text or note, object if type is file, animation, audio, picker, field, carousel or event)

id
string

Object identifier (only set if message type is picker or field)

text
string

Object text (only set if message type is picker, field, carousel or event)

explain
string

Object explanatory text (only set if message type is field)

value
string

Object value (only set if message type is field)

choices
array[object]

Object choices (only set if message type is picker)

value
string

Choice value

icon
string

Choice icon (if any, must be an emoji character)

label
string

Choice label

selected
boolean

Whether choice is selected or not

action
object

Specific action to take when choice gets clicked (if any)

type
enum[string]

Action type

Values

  • frame
  • link
target
string

Action target URL

targets
array[object]

Object targets (only set if message type is carousel)

title
string

Target title

description
string

Target description

image
string

Target banner image URL (if any)

actions
array[object]

Target action buttons

label
string

Action label

url
string

Action link URL

name
string

Object name (only set if message type is file)

duration
number

Object duration in seconds (only set if message type is audio)

url
string

Object URL (only set if message type is file, animation or audio)

type
string

Object MIME type (only set if message type is file, animation or audio)

namespace
enum[string]

Event namespace (only set if message type is event)

Values

  • state:resolved
  • user:blocked
  • reminder:scheduled
  • thread:started
  • thread:ended
  • participant:added
  • participant:removed
  • call:started
  • call:ended
required
boolean

Indicates if message must be filled before continuing (only set if message type is picker or field)

preview
array[object]

Preview of URLs contained in message

url
string

Previewed URL

website
string

Website domain for previewed URL

title
string

Page title for previewed URL

preview
object

Preview information

excerpt
string

Text excerpt from the page (may not be set)

image
string

Main image from the page (may not be set)

embed
string

Embeddable frame of main page media (may not be set)

stamped
boolean

Whether message was fully processed in the internal Crisp pipeline (eg: preview was done)

edited
boolean

Whether message was edited after being sent or not

translated
boolean

Whether message was auto-translated or not

automated
boolean

Whether message is automated or not (ie. comes from a bot)

mentions
array[string]

Mentioned user identifiers

read
enum[string]

Channel in which message has been read (can be empty)

Values

  • chat
  • email
  • urn:*
delivered
enum[string]

Channel in which message has lastly been delivered (can be empty)

Values

  • chat
  • email
  • urn:*
fingerprint
number

Unique message fingerprint (useful to avoid duplicates when using the API as per with the real-time sockets)

timestamp
number

Timestamp at which the message was sent

user
object

Sending user information

type
enum[string]

Sending user type (if any)

Values

  • website
  • participant
user_id
string

Sending user identifier (may be operator user identifier or session identifier)

nickname
string

Sending user nickname

avatar
string

Sending user avatar

references
array[object]

References adding more context to message (if any)

type
enum[string]

Reference type

Values

  • link
name
string

Reference name

target
string

Reference target (eg. page URL if type is link)

original
object

Original message data (if any)

original_id
string

Original identifier

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/messages
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

⭐ Send A Message In Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/message

Sends a message in an existing conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
type
enum[string]Required

Message type

Values

  • text
  • note
  • file
  • animation
  • audio
  • picker
  • field
  • carousel
  • event
from
enum[string]Required

Message sender

Values

  • user
  • operator
origin
enum[string]Required

Message origin

Values

  • chat
  • email
  • urn:*
content
objectRequired

Message content (string if type is text or note, object if type is file, animation, audio, picker, field, carousel or event)

id
stringRequired

Object identifier (only set if message type is picker or field)

text
stringRequired

Object text (only set if message type is picker, field, carousel or event)

explain
stringRequired

Object explanatory text (only set if message type is field)

value
stringOptional

Object value (only set if message type is field)

choices
array[object]Required

Object choices (only set if message type is picker)

value
stringRequired

Choice value

icon
stringOptional

Choice icon (must be an emoji character)

label
stringRequired

Choice label

selected
booleanRequired

Whether choice is selected or not

action
objectOptional

Specific action to take when choice gets clicked

type
enum[string]Required

Action type

Values

  • frame
  • link
target
stringRequired

Action target URL

targets
array[object]Required

Object targets (only set if message type is carousel)

title
stringRequired

Target title

description
stringRequired

Target description

image
stringOptional

Target banner image URL

actions
array[object]Required

Target action buttons

label
stringRequired

Action label

url
stringRequired

Action link URL

name
stringRequired

Object name (only set if message type is file)

duration
numberRequired

Object duration in seconds (only set if message type is audio)

url
stringRequired

Object URL (only set if message type is file, animation or audio)

type
stringRequired

Object MIME type (only set if message type is file, animation or audio)

namespace
enum[string]Required

Event namespace (only set if message type is event)

Values

  • state:resolved
  • user:blocked
  • reminder:scheduled
  • thread:started
  • thread:ended
  • participant:added
  • participant:removed
  • call:started
  • call:ended
required
booleanOptional

Indicates if message must be filled before continuing (only set if message type is picker or field)

mentions
array[string]Optional

Mentioned user identifiers

fingerprint
numberOptional

Unique message fingerprint (useful to avoid duplicates when using the API as per with the real-time sockets)

user
objectOptional

Sending user information

type
enum[string]Optional

Sending user type

Values

  • website
  • participant
nickname
stringOptional

Sending user nickname

avatar
stringOptional

Sending user avatar

references
array[object]Optional

References adding more context to message

type
enum[string]Required

Reference type

Values

  • link
name
stringRequired

Reference name

target
stringRequired

Reference target (eg. page URL if type is link)

original
objectOptional

Original message data (if set, original data will then be available on a separate route)

type
enum[string]Required

Original message data MIME type

Values

  • text/html
content
stringRequired

Original message data content

timestamp
numberOptional

Timestamp at which the message was sent, in milliseconds (if different than the current timestamp, eg. to ingest older messages)

stealth
booleanOptional

Message stealth mode (ie. do not propagate message to the other party)

translated
booleanOptional

Whether message was auto-translated or not

automated
booleanOptional

Whether message is automated or not (ie. comes from a bot)

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/message
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

Get A Message In Conversation

GET
/v1/website/{website_id}/conversation/{session_id}/message/{fingerprint}

Resolves an existing message in an existing conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

fingerprint
stringRequired

The message fingerprint

Response Data
error
boolean
reason
string
data
object
session_id
string

Session identifier

website_id
string

Website identifier

type
enum[string]

Message type

Values

  • text
  • note
  • file
  • animation
  • audio
  • picker
  • field
  • carousel
  • event
from
enum[string]

Message sender

Values

  • user
  • operator
origin
enum[string]

Message origin

Values

  • chat
  • email
  • urn:*
content
object

Message content (string if type is text or note, object if type is file, animation, audio, picker, field, carousel or event)

id
string

Object identifier (only set if message type is picker or field)

text
string

Object text (only set if message type is picker, field, carousel or event)

explain
string

Object explanatory text (only set if message type is field)

value
string

Object value (only set if message type is field)

choices
array[object]

Object choices (only set if message type is picker)

value
string

Choice value

icon
string

Choice icon (if any, must be an emoji character)

label
string

Choice label

selected
boolean

Whether choice is selected or not

action
object

Specific action to take when choice gets clicked (if any)

type
enum[string]

Action type

Values

  • frame
  • link
target
string

Action target URL

targets
array[object]

Object targets (only set if message type is carousel)

title
string

Target title

description
string

Target description

image
string

Target banner image URL (if any)

actions
array[object]

Target action buttons

label
string

Action label

url
string

Action link URL

name
string

Object name (only set if message type is file)

duration
number

Object duration in seconds (only set if message type is audio)

url
string

Object URL (only set if message type is file, animation or audio)

type
string

Object MIME type (only set if message type is file, animation or audio)

namespace
enum[string]

Event namespace (only set if message type is event)

Values

  • state:resolved
  • user:blocked
  • reminder:scheduled
  • thread:started
  • thread:ended
  • participant:added
  • participant:removed
  • call:started
  • call:ended
required
boolean

Indicates if message must be filled before continuing (only set if message type is picker or field)

preview
array[object]

Preview of URLs contained in message

url
string

Previewed URL

website
string

Website domain for previewed URL

title
string

Page title for previewed URL

preview
object

Preview information

excerpt
string

Text excerpt from the page (may not be set)

image
string

Main image from the page (may not be set)

embed
string

Embeddable frame of main page media (may not be set)

stamped
boolean

Whether message was fully processed in the internal Crisp pipeline (eg: preview was done)

edited
boolean

Whether message was edited after being sent or not

translated
boolean

Whether message was auto-translated or not

automated
boolean

Whether message is automated or not (ie. comes from a bot)

mentions
array[string]

Mentioned user identifiers

read
enum[string]

Channel in which message has been read (can be empty)

Values

  • chat
  • email
  • urn:*
delivered
enum[string]

Channel in which message has lastly been delivered (can be empty)

Values

  • chat
  • email
  • urn:*
fingerprint
number

Unique message fingerprint (useful to avoid duplicates when using the API as per with the real-time sockets)

timestamp
number

Timestamp at which the message was sent

user
object

Sending user information

type
enum[string]

Sending user type (if any)

Values

  • website
  • participant
user_id
string

Sending user identifier (may be operator user identifier or session identifier)

nickname
string

Sending user nickname

avatar
string

Sending user avatar

references
array[object]

References adding more context to message (if any)

type
enum[string]

Reference type

Values

  • link
name
string

Reference name

target
string

Reference target (eg. page URL if type is link)

original
object

Original message data (if any)

original_id
string

Original identifier

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/message/fingerprint
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

Update A Message In Conversation

PATCH
/v1/website/{website_id}/conversation/{session_id}/message/{fingerprint}

Edits an existing message in an existing conversation.

The updated event is sent back asynchronously on the RTM Events channel, using the event namespace message:updated.

Note that editing messages is only possible if the conversation is initiated from the Crisp Chatbox. This will not work with integrations such as: Email, Messenger, Telegram, etc.
URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

fingerprint
stringRequired

The edited message fingerprint

Request Body
content
objectRequired

Message content (string if type is text or note, object if type is file, animation, audio, picker, field, carousel or event)

id
stringRequired

Object identifier (only set if message type is picker or field)

text
stringRequired

Object text (only set if message type is picker, field, carousel or event)

explain
stringRequired

Object explanatory text (only set if message type is field)

value
stringOptional

Object value (only set if message type is field)

choices
array[object]Required

Object choices (only set if message type is picker)

value
stringRequired

Choice value

icon
stringOptional

Choice icon (must be an emoji character)

label
stringRequired

Choice label

selected
booleanRequired

Whether choice is selected or not

action
objectOptional

Specific action to take when choice gets clicked

type
enum[string]Required

Action type

Values

  • frame
  • link
target
stringRequired

Action target URL

targets
array[object]Required

Object targets (only set if message type is carousel)

title
stringRequired

Target title

description
stringRequired

Target description

image
stringOptional

Target banner image URL

actions
array[object]Required

Target action buttons

label
stringRequired

Action label

url
stringRequired

Action link URL

name
stringRequired

Object name (only set if message type is file)

duration
numberRequired

Object duration in seconds (only set if message type is audio)

url
stringRequired

Object URL (only set if message type is file, animation or audio)

type
stringRequired

Object MIME type (only set if message type is file, animation or audio)

namespace
enum[string]Required

Event namespace (only set if message type is event)

Values

  • state:resolved
  • user:blocked
  • reminder:scheduled
  • thread:started
  • thread:ended
  • participant:added
  • participant:removed
  • call:started
  • call:ended
required
booleanOptional

Indicates if message must be filled before continuing (only set if message type is picker or field)

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/message/fingerprint
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

Remove A Message In Conversation

DELETE
/v1/website/{website_id}/conversation/{session_id}/message/{fingerprint}

Removes an existing message in an existing conversation. Used to retract a previously-sent message.

The updated event is sent back asynchronously on the RTM Events channel, using the event namespace message:removed.

Note that retracting messages may not completely remove the message if it was already sent over email, or if the chatbox is not online whilst the message is removed. As well, certain integrations ignore message removals.
URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

fingerprint
stringRequired

The removed message fingerprint

  • DELETEhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/message/fingerprint
HTTP
Request
(loading)
Response
(loading)

Compose A Message In Conversation

PATCH
/v1/website/{website_id}/conversation/{session_id}/compose

Starts or stop composing a message in an existing conversation. This route is used for MagicType preview.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
type
enum[string]Required

Compose type

Values

  • start
  • stop
from
enum[string]Required

Compose sender

Values

  • user
  • operator
excerpt
stringOptional

Compose excerpt (MagicType preview)

stealth
booleanOptional

Compose stealth mode (ie. do not propagate compose to the other party)

automated
booleanOptional

Whether compose is automated or not (ie. comes from a bot)

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/compose
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

⭐ Mark Messages As Read In Conversation

PATCH
/v1/website/{website_id}/conversation/{session_id}/read

Marks messages as read in conversation. Either using given message fingerprints, or all messages.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
from
enum[string]Required

Sender direction

Values

  • user
  • operator
origin
enum[string]Required

Read receipt origin

Values

  • chat
  • email
  • urn:*
fingerprints
array[number]Optional

Target message fingerprints (if not set, this marks all messages as read in conversation)

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/read
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

⭐ Mark Messages As Delivered In Conversation

PATCH
/v1/website/{website_id}/conversation/{session_id}/delivered

Marks messages as delivered in conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
from
enum[string]Required

Sender direction

Values

  • operator
origin
enum[string]Required

Delivered receipt origin

Values

  • chat
  • email
  • urn:*
fingerprints
array[number]Required

Target message fingerprints

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/delivered
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

Update Conversation Open State

PATCH
/v1/website/{website_id}/conversation/{session_id}/open

Updates conversation open state for authenticated operator user. Lets other operators see which conversation people are on at any given moment. This state automatically expires after a while, if not renewed.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
opened
booleanRequired

Open state

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/open
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

⭐ Get Conversation Routing Assign

GET
/v1/website/{website_id}/conversation/{session_id}/routing

Resolves assigned operator for conversation routing.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
assigned
object

Assigned operator (if any)

user_id
string

Operator user identifier

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/routing
  • Tiersuserplugin
  • Scopeswebsite:conversation:routing
HTTP
Request
(loading)
Response
(loading)

⭐ Assign Conversation Routing

PATCH
/v1/website/{website_id}/conversation/{session_id}/routing

Assigns conversation routing to an operator, or unassign.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
assigned
objectRequired

Assigned operator (set to blank value for none)

user_id
stringRequired

Operator user identifier

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/routing
  • Tiersuserplugin
  • Scopeswebsite:conversation:routing
HTTP
Request
(loading)
Response
(loading)

⭐ Get Conversation Metas

GET
/v1/website/{website_id}/conversation/{session_id}/meta

Resolves conversation meta information.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
nickname
string

Visitor nickname

email
string

Visitor email

phone
string

Visitor phone

address
string

Visitor address

subject
string

Subject for conversation (if any)

ip
string

Visitor IP address

data
object

Visitor data

avatar
string

Visitor avatar

device
object

Device information

capabilities
array[enum[string]]

Visitor device capabilities

Values

  • browsing
  • call
geolocation
object

Geolocation information for visitor device

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

system
object

Visitor device system information

os
object

Operating system information

version
string

OS version

name
string

OS name

engine
object

Rendering engine information

version
string

Engine version

name
string

Engine name

browser
object

Browser information

major
string

Browser major version (eg: version 8.1 has a major of 8)

version
string

Browser version

name
string

Browser name

useragent
string

Visitor user agent

timezone
number

Visitor device timezone offset (UTC)

locales
array[string]

Visitor device locales

segments
array[string]

Segments attributed to conversation

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/meta
  • Tiersuserplugin
  • Scopeswebsite:conversation:sessions
HTTP
Request
(loading)
Response
(loading)

⭐ Update Conversation Metas

PATCH
/v1/website/{website_id}/conversation/{session_id}/meta

Updates conversation meta information.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
nickname
stringOptional

Visitor nickname

email
stringOptional

Visitor email

avatar
stringOptional

Visitor avatar

ip
stringOptional

Visitor IP address

data
objectOptional

Visitor data

phone
stringOptional

Visitor phone number

address
stringOptional

Visitor address

subject
stringOptional

Subject for conversation (or none)

segments
array[string]Optional

Segments for conversation

device
objectOptional

Visitor device information

capabilities
array[enum[string]]Optional

Visitor device capabilities

Values

  • browsing
  • call
geolocation
objectOptional

Geolocation information for visitor device

country
stringOptional

Country code (can be blank)

region
stringOptional

Region code (can be blank)

city
stringOptional

City name (can be blank)

coordinates
objectRequired

Location coordinates

latitude
numberRequired

Latitude coordinate

longitude
numberRequired

Longitude coordinate

system
objectOptional

Visitor device system information

os
objectOptional

Operating system information

version
stringRequired

OS version

name
stringRequired

OS name

engine
objectOptional

Rendering engine information

version
stringRequired

Engine version

name
stringRequired

Engine name

browser
objectOptional

Browser information

major
stringRequired

Browser major version (eg: version 8.1 has a major of 8)

version
stringRequired

Browser version

name
stringRequired

Browser name

useragent
stringRequired

Visitor user agent

timezone
numberOptional

Visitor device timezone offset (UTC)

locales
array[string]Optional

Visitor device locales

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/meta
  • Tiersuserplugin
  • Scopeswebsite:conversation:sessions
HTTP
Request
(loading)
Response
(loading)

Get An Original Message In Conversation

GET
/v1/website/{website_id}/conversation/{session_id}/original/{original_id}

Resolves an existing original message in an existing conversation. This route is mainly used to retrieve original HTML content and headers for emails.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

original_id
stringRequired

The original identifier

Response Data
error
boolean
reason
string
data
object
website_id
string

Website identifier

session_id
string

Session identifier

original_id
string

Original identifier

type
enum[string]

Original message data MIME type

Values

  • text/html
headers
object

Original message headers

content
string

Original message data content

timestamp
number

Timestamp at which the original was stored

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/original/original_id
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

List Conversation Pages

GET
/v1/website/{website_id}/conversation/{session_id}/pages/{page_number}

Lists browsed pages in conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

page_number
stringOptional

The page number (paging in page list)

Response Data
error
boolean
reason
string
data
array[object]
page_title
string

Page title as seen by visitor browser

page_url
string

Page URL

page_referrer
string

Page referrer (if any)

timestamp
number

Timestamp of page access (when the page was loaded)

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/pages/page_number
  • Tiersuserplugin
  • Scopeswebsite:conversation:pages
HTTP
Request
(loading)
Response
(loading)

List Conversation Events

GET
/v1/website/{website_id}/conversation/{session_id}/events/{page_number}

Lists stacked events in conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

page_number
stringOptional

The page number (paging in event list)

Response Data
error
boolean
reason
string
data
array[object]
text
string

Text for event

data
object

Data for event (if any)

color
enum[string]

Color for event (if any)

Values

  • red
  • orange
  • yellow
  • green
  • blue
  • purple
  • pink
  • brown
  • grey
  • black
timestamp
number

Timestamp of event (when the event was stacked)

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/events/page_number
  • Tiersuserplugin
  • Scopeswebsite:conversation:events
HTTP
Request
(loading)
Response
(loading)

List Conversation Files

GET
/v1/website/{website_id}/conversation/{session_id}/files/{page_number}

Lists files in conversation (extracted from messages).

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

page_number
stringOptional

The page number (paging in file list)

Response Data
error
boolean
reason
string
data
array[object]
name
string

File name

type
string

File MIME type

url
string

File URL

fingerprint
number

Unique file message fingerprint (file container message)

timestamp
number

Timestamp of file message (when the file container message was sent)

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/files/page_number
  • Tiersuserplugin
  • Scopeswebsite:conversation:messages
HTTP
Request
(loading)
Response
(loading)

Get Conversation State

GET
/v1/website/{website_id}/conversation/{session_id}/state

Resolves conversation state (resolved, unresolved or pending).

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
state
enum[string]

Conversation state

Values

  • pending
  • unresolved
  • resolved
  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/state
  • Tiersuserplugin
  • Scopeswebsite:conversation:states
HTTP
Request
(loading)
Response
(loading)

⭐ Change Conversation State

PATCH
/v1/website/{website_id}/conversation/{session_id}/state

Updates conversation state (resolved, unresolved or pending).

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
state
enum[string]Required

Conversation state

Values

  • pending
  • unresolved
  • resolved
  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/state
  • Tiersuserplugin
  • Scopeswebsite:conversation:states
HTTP
Request
(loading)
Response
(loading)

Get Conversation Participants

GET
/v1/website/{website_id}/conversation/{session_id}/participants

Resolves conversation participants (external participants, eg. emails to be set in CC).

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
participants
array[object]

External participants for conversation

type
enum[string]

External participant type

Values

  • email
target
string

External participant target (ie. email address, identifier, etc.)

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/participants
  • Tiersuserplugin
  • Scopeswebsite:conversation:participants
HTTP
Request
(loading)
Response
(loading)

Save Conversation Participants

PUT
/v1/website/{website_id}/conversation/{session_id}/participants

Saves conversation participants (external participants, eg. emails to be set in CC).

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
participants
array[object]Required

External participants for conversation

type
enum[string]Required

External participant type

Values

  • email
target
stringRequired

External participant target (ie. email address, identifier, etc.)

  • PUThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/participants
  • Tiersuserplugin
  • Scopeswebsite:conversation:participants
HTTP
Request
(loading)
Response
(loading)

Get Block Status For Conversation

GET
/v1/website/{website_id}/conversation/{session_id}/block

Resolves conversation block status.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
blocked
boolean

Block state

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/block
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

Block Incoming Messages For Conversation

PATCH
/v1/website/{website_id}/conversation/{session_id}/block

Blocks further incoming messages from a conversation. Messages from visitor will be silently dropped, but you can still send messages to visitor.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
blocked
booleanRequired

Block state

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/block
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

Get Verify Status For Conversation

GET
/v1/website/{website_id}/conversation/{session_id}/verify

Resolves conversation verify status.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
verified
boolean

Verify status

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/verify
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

Update Verify Status For Conversation

PATCH
/v1/website/{website_id}/conversation/{session_id}/verify

Updates conversation verify status. When a conversation user is verified, a verified badge shows in the Crisp apps.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
verified
booleanRequired

Verify status

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/verify
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

Request Email Transcript For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/transcript

Requests an email transcript for a conversation. The transcript is emailed to the authenticated user, or to the indicated email. It contains all conversation history and may be kept for as an external record.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
to
enum[string]Required

Target user to send the transcript to

Values

  • user
  • operator
email
stringOptional

Target email (if not set, the transcript is sent to the email address of the target user)

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/transcript
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

Request Chatbox Binding Purge For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/purge

Requests a chatbox binding purge for conversation. The visitor must be online for the purge to be proceeded.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/purge
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

Request User Feedback For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/feedback

Requests feedback from user for conversation. The visitor must be online for the feedback request to be delivered.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/feedback
  • Tiersuserplugin
  • Scopeswebsite:conversation:actions
HTTP
Request
(loading)
Response
(loading)

List Browsing Sessions For Conversation

GET
/v1/website/{website_id}/conversation/{session_id}/browsing

Lists available browsing sessions for conversation. A browsing session can be initiated to stream user screen content to operators.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
array[object]
browsing_id
string

Browsing session identifier

browsing_token
string

Browsing token (used to authenticate cross-channel requests, eg. to the HTTP proxy)

useragent
string

Useragent for browsing session

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/browsing
  • Tiersuserplugin
  • Scopeswebsite:conversation:browsing
HTTP
Request
(loading)
Response
(loading)

Initiate Browsing Session For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/browsing

Initiates browsing session for conversation.

Used to ask a client to prepare for a streamed browsing session for all open tabs, and request acknowledgement of when the client is ready to accept browsing stream actions (one acknowledgement per tab).

The client acknowledgement is sent back asynchronously on the RTM Events channel, using the event namespace browsing:request:initiated if initiated, or browsing:request:rejected if not initiated.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/browsing
  • Tiersuserplugin
  • Scopeswebsite:conversation:browsing
HTTP
Request
(loading)
Response
(loading)

Send Action To An Existing Browsing Session

PATCH
/v1/website/{website_id}/conversation/{session_id}/browsing/{browsing_id}

Sends an action to an existing browsing session. Used to send stream actions to a browsing session (eg. to start or stop the stream session).

The client acknowledgement is sent back asynchronously on the streaming channel, using either the event namespace app:browsing:action:started or app:browsing:action:stopped (depending on the request action parameter, if action is start or stop).

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

browsing_id
stringRequired

The browsing session identifier

Request Body
action
enum[string]Required

Browsing action

Values

  • start
  • stop
  • heartbeat
  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/browsing/browsing_id
  • Tiersuserplugin
  • Scopeswebsite:conversation:browsing
HTTP
Request
(loading)
Response
(loading)

Assist An Existing Browsing Session

PATCH
/v1/website/{website_id}/conversation/{session_id}/browsing/{browsing_id}/assist

Assists an existing browsing session. Used by LiveAssist™ to start or stop an assist session, used by operators to take control on the screen of user browser (mouse move and scroll).

The client acknowledgement is sent back asynchronously on the streaming channel, using either the event namespace app:browsing:assist:started or app:browsing:assist:stopped (depending on the request action parameter, if action is start or stop). Other actions do not imply real-time feedbacks.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

browsing_id
stringRequired

The browsing session identifier

Request Body
action
enum[string]Required

Assist action

Values

  • start
  • stop
  • heartbeat
  • mouse
  • scroll
  • click
mouse
objectOptional

Mouse position for assist cursor in browsing session (action must be mouse)

x
numberRequired

Mouse cursor horizontal position

y
numberRequired

Mouse cursor vertical position

click
objectOptional

Click target for assist cursor in browsing session (action must be click)

x
numberRequired

Click cursor horizontal position

y
numberRequired

Click cursor vertical position

scroll
objectOptional

Scroll position for assist scroll wheel in browsing session (action must be scroll)

x
numberRequired

Scroll wheel horizontal position

y
numberRequired

Scroll wheel vertical position

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/browsing/browsing_id/assist
  • Tiersuserplugin
  • Scopeswebsite:conversation:browsing
HTTP
Request
(loading)
Response
(loading)

Initiate New Call Session For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/call

Initiates a new audio/video call session for conversation.

Used to request a client to open a call session (audio + video). The client acknowledgement is sent back asynchronously on the RTM Events channel, using either the event namespace call:request:accept or call:request:decline.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
mode
enum[string]Required

Mode of the call to start

Values

  • video
  • audio
  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/call
  • Tiersuserplugin
  • Scopeswebsite:conversation:calls
HTTP
Request
(loading)
Response
(loading)

Get Ongoing Call Session For Conversation

GET
/v1/website/{website_id}/conversation/{session_id}/call

Gets the ongoing audio/video call session for conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Response Data
error
boolean
reason
string
data
object
call_id
string

Call session identifier (if any call ongoing)

  • GEThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/call
  • Tiersuserplugin
  • Scopeswebsite:conversation:calls
HTTP
Request
(loading)
Response
(loading)

Abort Ongoing Call Session For Conversation

DELETE
/v1/website/{website_id}/conversation/{session_id}/call/{call_id}

Aborts the ongoing audio/video call session for conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

call_id
stringRequired

The call identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/call/call_id
  • Tiersuserplugin
  • Scopeswebsite:conversation:calls
HTTP
Request
(loading)
Response
(loading)

Transmit Signaling On Ongoing Call Session

PATCH
/v1/website/{website_id}/conversation/{session_id}/call/{call_id}/signaling

Transmits a signaling payload for the ongoing audio/video call session for conversation.

Used to emit a signaling payload to the other client, that is also part of the call session. The client signaling payloads are sent back asynchronously on the streaming channel, using either the event namespace app:call:signaling:sdp or app:call:signaling:candidate.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

call_id
stringRequired

The call identifier

Request Body
type
enum[string]Required

Signaling type to transmit

Values

  • sdp
  • candidate
payload
objectRequired

Signaling payload to transmit

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/call/call_id/signaling
  • Tiersuserplugin
  • Scopeswebsite:conversation:calls
HTTP
Request
(loading)
Response
(loading)

Deliver Widget Button Action For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/widget/{plugin_id}/button

Delivers a button action on plugin widget for conversation, used to perform an action on the plugin, eg. refund a user. A hook will be sent to the plugin widget receiver.

Delivery completion or failure will be acknowledged on the RTM Events channel, using the event namespace widget:action:processed.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

plugin_id
stringRequired

The plugin identifier for widget

Request Body
section_id
stringRequired

Widget section identifier

item_id
stringRequired

Widget item identifier

data
objectRequired

Data to be sent along the button hook (can be empty)

value
objectOptional

Value to be sent along the button hook (if any)

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/widget/plugin_id/button
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Deliver Widget Data Action For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/widget/{plugin_id}/data

Delivers a data action on plugin widget for conversation, used to either fetch or edit a data value from the plugin, eg. fetch a user unpaid balance. A hook will be sent to the plugin widget receiver.

Delivery completion will be acknowledged on the RTM Events channel, using the event namespace widget:action:processed.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

plugin_id
stringRequired

The plugin identifier for widget

Request Body
section_id
stringRequired

Widget section identifier

item_id
stringRequired

Widget item identifier

action
enum[string]Required

Action to take on data

Values

  • fetch
  • edit
data
objectOptional

Payload data (if action is fetch)

value
stringOptional

Replacement value for data (if action is edit)

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/widget/plugin_id/data
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Schedule A Reminder For Conversation

POST
/v1/website/{website_id}/conversation/{session_id}/reminder

Schedules a reminder in the future for conversation, with a note to your future-self. A push notification and an email will be sent, as well as a note in the conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
date
stringRequired

Date in the future at which you want to be reminded (ISO 8601)

note
stringRequired

Note message to be sent as a reminder

  • POSThttps://api.crisp.chat/v1/website/website_id/conversation/session_id/reminder
  • Tiersuserplugin
  • Scopeswebsite:conversation:reminders
HTTP
Request
(loading)
Response
(loading)

Peoplein Website

Get People Statistics

GET
/v1/website/{website_id}/people/stats

Resolves the amount of people stored in the CRM.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
total
number

Total number of people

  • GEThttps://api.crisp.chat/v1/website/website_id/people/stats
  • Tiersuserplugin
  • Scopeswebsite:people:statistics
HTTP
Request
(loading)
Response
(loading)

List Suggested People Segments

GET
/v1/website/{website_id}/people/suggest/segments/{page_number}

Lists suggested segments for people.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

The page number (paging in segment list)

Response Data
error
boolean
reason
string
data
array[object]
segment
string

Segment value

count
number

Number of occurences of this segment

  • GEThttps://api.crisp.chat/v1/website/website_id/people/suggest/segments/page_number
  • Tiersuserplugin
  • Scopeswebsite:people:suggest
HTTP
Request
(loading)
Response
(loading)

Delete Suggested People Segment

DELETE
/v1/website/{website_id}/people/suggest/segment

Deletes a suggested segment for people.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
segment
stringRequired

Segment to be deleted from suggestions

  • DELETEhttps://api.crisp.chat/v1/website/website_id/people/suggest/segment
  • Tiersuserplugin
  • Scopeswebsite:people:suggest
HTTP
Request
(loading)
Response
(loading)

List Suggested People Data Keys

GET
/v1/website/{website_id}/people/suggest/data/{page_number}

Lists suggested data keys for people.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

The page number (paging in data list)

Response Data
error
boolean
reason
string
data
array[object]
key
string

Data key value

count
number

Number of occurences of this data key

  • GEThttps://api.crisp.chat/v1/website/website_id/people/suggest/data/page_number
  • Tiersuserplugin
  • Scopeswebsite:people:suggest
HTTP
Request
(loading)
Response
(loading)

Delete Suggested People Data Key

DELETE
/v1/website/{website_id}/people/suggest/data

Deletes a suggested data key for people.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
key
stringRequired

Data key to be deleted from suggestions

  • DELETEhttps://api.crisp.chat/v1/website/website_id/people/suggest/data
  • Tiersuserplugin
  • Scopeswebsite:people:suggest
HTTP
Request
(loading)
Response
(loading)

List Suggested People Events

GET
/v1/website/{website_id}/people/suggest/events/{page_number}

Lists suggested events for people.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

The page number (paging in event list)

Response Data
error
boolean
reason
string
data
array[object]
text
string

Event text

count
number

Number of occurences of this event

  • GEThttps://api.crisp.chat/v1/website/website_id/people/suggest/events/page_number
  • Tiersuserplugin
  • Scopeswebsite:people:suggest
HTTP
Request
(loading)
Response
(loading)

Delete Suggested People Event

DELETE
/v1/website/{website_id}/people/suggest/event

Deletes a suggested event for people.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
text
stringRequired

Event text to be deleted from suggestions

  • DELETEhttps://api.crisp.chat/v1/website/website_id/people/suggest/event
  • Tiersuserplugin
  • Scopeswebsite:people:suggest
HTTP
Request
(loading)
Response
(loading)

⭐ List People Profiles

GET
/v1/website/{website_id}/people/profiles/{page_number}{?per_page}{&sort_field}{&sort_order}{&search_operator}{&search_filter}{&search_text}{&filter_date_start}{&filter_date_end}

Lists people profiles for website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

Page number for people paging

per_page
stringOptional

Page size for people paging (between 20 and 50, defaults to 20)

sort_field
stringOptional

Sort on field (based on available search field names, eg. nickname and more)

sort_order
stringOptional

Sort order (ascending or descending)

search_operator
stringOptional

Search operator (or or and respectful to boolean algebra, defaults to and if not set)

search_filter
stringOptional

Search filter (object filter mapped as string)

search_text
stringOptional

Search text (text for a quick search)

filter_date_start
stringOptional

When to start relative to profile creation date (date, ISO 8601)

filter_date_end
stringOptional

When to end relative to profile creation date (date, ISO 8601)

Response Data
error
boolean
reason
string
data
array[object]
people_id
string

People identifier

email
string

Email for people profile

person
object

Personal information

nickname
string

Nickname for user (includes first name and last name)

avatar
string

Avatar for user

gender
enum[string]

Gender for user

Values

  • male
  • female
phone
string

Phone number for user

address
string

Address for user

description
string

Description for user

website
string

Website of user

timezone
number

Timezone offset of user (UTC)

profiles
array[object]

Online profiles for user

type
string

Profile type (eg: facebook, twitter)

handle
string

User handle on online platform

url
string

URL for the profile

employment
object

Employment information for user

name
string

Company name

domain
string

Company domain name

title
string

User title in company

role
string

User role in company

seniority
string

User seniority in company

geolocation
object

Geolocation information for user

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

locales
array[string]

Locales supported by user (ISO 639-1)

company
object

Company information

name
string

Company name

legal_name
string

Company legal name

domain
string

Company domain name

url
string

Company website URL

description
string

Company description

timezone
number

Company timezone offset (UTC)

phones
array[string]

Company phone numbers

emails
array[string]

Company email addresses

geolocation
object

Company location

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

metrics
object

Metrics for company

employees
number

Number of employees

market_cap
number

Market capitalization

raised
number

Money raised

arr
number

Annual Recurring Revenue

tags
array[string]

Tags for company

segments
array[string]

Segments attributed to people profile

notepad
string

Private notepad on people profile

active
object

User activity statistics (based on last active session from user)

now
boolean

Whether user is considered active right now or not

last
number

Timestamp at which the user was last active

score
number

Score associated to this profile, from 1 to 5 (based on ratings from user)

created_at
number

Profile creation timestamp

updated_at
number

Profile update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/people/profiles/page_number
  • Tiersuserplugin
  • Scopeswebsite:people:profiles
HTTP
Request
(loading)
Response
(loading)

⭐ Add New People Profile

POST
/v1/website/{website_id}/people/profile

Adds a new people profile.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
email
stringRequired

Email for people profile

person
objectRequired

Personal information

nickname
stringRequired

Nickname for user (includes first name and last name)

avatar
stringOptional

Avatar for user

gender
enum[string]Optional

Gender for user

Values

  • male
  • female
phone
stringOptional

Phone number for user

address
stringOptional

Address for user

description
stringOptional

Description for user

website
stringOptional

Website of user

timezone
numberOptional

Timezone offset of user (UTC)

profiles
array[object]Optional

Online profiles for user

type
stringRequired

Profile type (eg: facebook, twitter)

handle
stringOptional

User handle on online platform

url
stringRequired

URL for the profile

employment
objectOptional

Employment information for user

name
stringRequired

Company name

domain
stringOptional

Company domain name

title
stringOptional

User title in company

role
stringOptional

User role in company

seniority
stringOptional

User seniority in company

geolocation
objectOptional

Geolocation information for user

country
stringOptional

Country code (can be blank)

region
stringOptional

Region code (can be blank)

city
stringOptional

City name (can be blank)

coordinates
objectOptional

Location coordinates

latitude
numberRequired

Latitude coordinate

longitude
numberRequired

Longitude coordinate

locales
array[string]Optional

Locales supported by user (ISO 639-1)

company
objectOptional

Company information

name
stringRequired

Company name

legal_name
stringOptional

Company legal name

domain
stringOptional

Company domain name

url
stringOptional

Company website URL

description
stringOptional

Company description

timezone
numberOptional

Company timezone offset (UTC)

phones
array[string]Optional

Company phone numbers

emails
array[string]Optional

Company email addresses

geolocation
objectOptional

Company location

country
stringOptional

Country code (can be blank)

region
stringOptional

Region code (can be blank)

city
stringOptional

City name (can be blank)

coordinates
objectOptional

Location coordinates

latitude
numberRequired

Latitude coordinate

longitude
numberRequired

Longitude coordinate

metrics
objectOptional

Metrics for company

employees
numberOptional

Number of employees

market_cap
numberOptional

Market capitalization

raised
numberOptional

Money raised

arr
numberOptional

Annual Recurring Revenue

tags
array[string]Optional

Tags for company

segments
array[string]Optional

Segments attributed to people profile

notepad
stringOptional

Private notepad on people profile

active
numberOptional

Timestamp at which the user was last active

  • POSThttps://api.crisp.chat/v1/website/website_id/people/profile
  • Tiersuserplugin
  • Scopeswebsite:people:profiles
HTTP
Request
(loading)
Response
(loading)

⭐ Check If People Profile Exists

HEAD
/v1/website/{website_id}/people/profile/{people_id}

Checks if given people profile exists.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

  • HEADhttps://api.crisp.chat/v1/website/website_id/people/profile/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:profiles
HTTP
Request
(loading)
Response
(loading)

⭐ Get People Profile

GET
/v1/website/{website_id}/people/profile/{people_id}

Resolves people profile.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Response Data
error
boolean
reason
string
data
object
people_id
string

People identifier

email
string

Email for people profile

person
object

Personal information

nickname
string

Nickname for user (includes first name and last name)

avatar
string

Avatar for user

gender
enum[string]

Gender for user

Values

  • male
  • female
phone
string

Phone number for user

address
string

Address for user

description
string

Description for user

website
string

Website of user

timezone
number

Timezone offset of user (UTC)

profiles
array[object]

Online profiles for user

type
string

Profile type (eg: facebook, twitter)

handle
string

User handle on online platform

url
string

URL for the profile

employment
object

Employment information for user

name
string

Company name

domain
string

Company domain name

title
string

User title in company

role
string

User role in company

seniority
string

User seniority in company

geolocation
object

Geolocation information for user

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

locales
array[string]

Locales supported by user (ISO 639-1)

company
object

Company information

name
string

Company name

legal_name
string

Company legal name

domain
string

Company domain name

url
string

Company website URL

description
string

Company description

timezone
number

Company timezone offset (UTC)

phones
array[string]

Company phone numbers

emails
array[string]

Company email addresses

geolocation
object

Company location

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

metrics
object

Metrics for company

employees
number

Number of employees

market_cap
number

Market capitalization

raised
number

Money raised

arr
number

Annual Recurring Revenue

tags
array[string]

Tags for company

segments
array[string]

Segments attributed to people profile

notepad
string

Private notepad on people profile

active
object

User activity statistics (based on last active session from user)

now
boolean

Whether user is considered active right now or not

last
number

Timestamp at which the user was last active

score
number

Score associated to this profile, from 1 to 5 (based on ratings from user)

created_at
number

Profile creation timestamp

updated_at
number

Profile update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/people/profile/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:profiles
HTTP
Request
(loading)
Response
(loading)

⭐ Save People Profile

PUT
/v1/website/{website_id}/people/profile/{people_id}

Saves people profile, and overwrite all previous information.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Request Body
email
stringRequired

Email for people profile

person
objectRequired

Personal information

nickname
stringRequired

Nickname for user (includes first name and last name)

avatar
stringOptional

Avatar for user

gender
enum[string]Optional

Gender for user

Values

  • male
  • female
phone
stringOptional

Phone number for user

address
stringOptional

Address for user

description
stringOptional

Description for user

website
stringOptional

Website of user

timezone
numberOptional

Timezone offset of user (UTC)

profiles
array[object]Optional

Online profiles for user

type
stringRequired

Profile type (eg: facebook, twitter)

handle
stringOptional

User handle on online platform

url
stringRequired

URL for the profile

employment
objectOptional

Employment information for user

name
stringRequired

Company name

domain
stringOptional

Company domain name

title
stringOptional

User title in company

role
stringOptional

User role in company

seniority
stringOptional

User seniority in company

geolocation
objectOptional

Geolocation information for user

country
stringOptional

Country code (can be blank)

region
stringOptional

Region code (can be blank)

city
stringOptional

City name (can be blank)

coordinates
objectOptional

Location coordinates

latitude
numberRequired

Latitude coordinate

longitude
numberRequired

Longitude coordinate

locales
array[string]Optional

Locales supported by user (ISO 639-1)

company
objectOptional

Company information

name
stringRequired

Company name

legal_name
stringOptional

Company legal name

domain
stringOptional

Company domain name

url
stringOptional

Company website URL

description
stringOptional

Company description

timezone
numberOptional

Company timezone offset (UTC)

phones
array[string]Optional

Company phone numbers

emails
array[string]Optional

Company email addresses

geolocation
objectOptional

Company location

country
stringOptional

Country code (can be blank)

region
stringOptional

Region code (can be blank)

city
stringOptional

City name (can be blank)

coordinates
objectOptional

Location coordinates

latitude
numberRequired

Latitude coordinate

longitude
numberRequired

Longitude coordinate

metrics
objectOptional

Metrics for company

employees
numberOptional

Number of employees

market_cap
numberOptional

Market capitalization

raised
numberOptional

Money raised

arr
numberOptional

Annual Recurring Revenue

tags
array[string]Optional

Tags for company

segments
array[string]Optional

Segments attributed to people profile

notepad
stringOptional

Private notepad on people profile

active
numberOptional

Timestamp at which the user was last active

  • PUThttps://api.crisp.chat/v1/website/website_id/people/profile/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:profiles
HTTP
Request
(loading)
Response
(loading)

⭐ Update People Profile

PATCH
/v1/website/{website_id}/people/profile/{people_id}

Updates people profile, and save only changed fields on the previous profile revision.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Request Body
email
stringOptional

Email for people profile

person
objectOptional

Personal information

nickname
stringOptional

Nickname for user (includes first name and last name)

avatar
stringOptional

Avatar for user

gender
enum[string]Optional

Gender for user

Values

  • male
  • female
phone
stringOptional

Phone number for user

address
stringOptional

Address for user

description
stringOptional

Description for user

website
stringOptional

Website of user

timezone
numberOptional

Timezone offset of user (UTC)

profiles
array[object]Optional

Online profiles for user

type
stringOptional

Profile type (eg: facebook, twitter)

handle
stringOptional

User handle on online platform

url
stringOptional

URL for the profile

employment
objectOptional

Employment information for user

name
stringOptional

Company name

domain
stringOptional

Company domain name

title
stringOptional

User title in company

role
stringOptional

User role in company

seniority
stringOptional

User seniority in company

geolocation
objectOptional

Geolocation information for user

country
stringOptional

Country code (can be blank)

region
stringOptional

Region code (can be blank)

city
stringOptional

City name (can be blank)

coordinates
objectOptional

Location coordinates

latitude
numberOptional

Latitude coordinate

longitude
numberOptional

Longitude coordinate

locales
array[string]Optional

Locales supported by user (ISO 639-1)

company
objectOptional

Company information

name
stringOptional

Company name

legal_name
stringOptional

Company legal name

domain
stringOptional

Company domain name

url
stringOptional

Company website URL

description
stringOptional

Company description

timezone
numberOptional

Company timezone offset (UTC)

phones
array[string]Optional

Company phone numbers

emails
array[string]Optional

Company email addresses

geolocation
objectOptional

Company location

country
stringOptional

Country code (can be blank)

region
stringOptional

Region code (can be blank)

city
stringOptional

City name (can be blank)

coordinates
objectOptional

Location coordinates

latitude
numberOptional

Latitude coordinate

longitude
numberOptional

Longitude coordinate

metrics
objectOptional

Metrics for company

employees
numberOptional

Number of employees

market_cap
numberOptional

Market capitalization

raised
numberOptional

Money raised

arr
numberOptional

Annual Recurring Revenue

tags
array[string]Optional

Tags for company

segments
array[string]Optional

Segments attributed to people profile

notepad
stringOptional

Private notepad on people profile

active
numberOptional

Timestamp at which the user was last active

  • PATCHhttps://api.crisp.chat/v1/website/website_id/people/profile/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:profiles
HTTP
Request
(loading)
Response
(loading)

⭐ Remove People Profile

DELETE
/v1/website/{website_id}/people/profile/{people_id}

Removes people profile in website.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

  • DELETEhttps://api.crisp.chat/v1/website/website_id/people/profile/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:profiles
HTTP
Request
(loading)
Response
(loading)

List People Conversations

GET
/v1/website/{website_id}/people/conversations/{people_id}/list/{page_number}{?filter_unread}{&filter_resolved}{&filter_not_resolved}

Lists conversations linked to people.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

page_number
stringOptional

The page number (paging in conversation list)

filter_unread
stringOptional

Whether to return only conversations with unread messages (1 or 0, defaults to 0)

filter_resolved
stringOptional

Whether to return only conversations that are resolved (1 or 0, defaults to 0)

filter_not_resolved
stringOptional

Whether to return only conversations that are not resolved (1 or 0, defaults to 0)

Response Data
error
boolean
reason
string
data
array[string]
  • GEThttps://api.crisp.chat/v1/website/website_id/people/conversations/people_id/list/page_number
  • Tiersuserplugin
  • Scopeswebsite:people:conversations
HTTP
Request
(loading)
Response
(loading)

List People Campaigns

GET
/v1/website/{website_id}/people/campaigns/{people_id}/list/{page_number}

Lists campaigns linked to people.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

page_number
stringOptional

The page number (paging in campaign list)

Response Data
error
boolean
reason
string
data
array[object]
campaign_id
string

Campaign identifier

type
enum[string]

Campaign type

Values

  • one-shot
  • automated
name
string

Campaign name

created_at
number

Campaign creation timestamp

updated_at
number

Campaign update timestamp

dispatched_at
number

Campaign dispatch timestamp

occurred_at
number

Statistic occurred timestamp

statistics
array[enum[string]]

Statistic points on campaign (ie. actions the user took on campaign)

Values

  • campaign:opened
  • campaign:clicked
  • campaign:unsubscribed
  • GEThttps://api.crisp.chat/v1/website/website_id/people/campaigns/people_id/list/page_number
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Add A People Event

POST
/v1/website/{website_id}/people/events/{people_id}

Stacks an event for people.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Request Body
text
stringRequired

Text for event

data
objectOptional

Data for event (if any)

color
enum[string]Optional

Color for event (if any)

Values

  • red
  • orange
  • yellow
  • green
  • blue
  • purple
  • pink
  • brown
  • grey
  • black
  • POSThttps://api.crisp.chat/v1/website/website_id/people/events/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:events
HTTP
Request
(loading)
Response
(loading)

List People Events

GET
/v1/website/{website_id}/people/events/{people_id}/list/{page_number}

Lists stacked events for people.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

page_number
stringOptional

The page number (paging in event list)

Response Data
error
boolean
reason
string
data
array[object]
text
string

Text for event

data
object

Data for event (if any)

color
enum[string]

Color for event (if any)

Values

  • red
  • orange
  • yellow
  • green
  • blue
  • purple
  • pink
  • brown
  • grey
  • black
timestamp
number

Timestamp of event (when the event was stacked)

  • GEThttps://api.crisp.chat/v1/website/website_id/people/events/people_id/list/page_number
  • Tiersuserplugin
  • Scopeswebsite:people:events
HTTP
Request
(loading)
Response
(loading)

Get People Data

GET
/v1/website/{website_id}/people/data/{people_id}

Gets stored data for people.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Response Data
error
boolean
reason
string
data
object
data
object

People data

  • GEThttps://api.crisp.chat/v1/website/website_id/people/data/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:data
HTTP
Request
(loading)
Response
(loading)

Save People Data

PUT
/v1/website/{website_id}/people/data/{people_id}

Saves stored data for people. This replaces any already-set data with the new data keys.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Request Body
data
objectOptional

People data

  • PUThttps://api.crisp.chat/v1/website/website_id/people/data/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:data
HTTP
Request
(loading)
Response
(loading)

Update People Data

PATCH
/v1/website/{website_id}/people/data/{people_id}

Updates stored data for people. This merges the new data keys with already-set data.

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Request Body
data
objectOptional

People data

  • PATCHhttps://api.crisp.chat/v1/website/website_id/people/data/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:data
HTTP
Request
(loading)
Response
(loading)

Get People Subscription Status

GET
/v1/website/{website_id}/people/subscription/{people_id}

Resolves subscription status for people (subscribed or unsubscribed).

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Response Data
error
boolean
reason
string
data
object
email
boolean

Whether people is subscribed to emails or not

  • GEThttps://api.crisp.chat/v1/website/website_id/people/subscription/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:subscriptions
HTTP
Request
(loading)
Response
(loading)

Update People Subscription Status

PATCH
/v1/website/{website_id}/people/subscription/{people_id}

Updates current subscription status for people (subscribe or unsubscribe).

URI Parameters
website_id
stringRequired

The website identifier

people_id
stringRequired

The people identifier (also allowed: people email)

Request Body
email
booleanRequired

Whether to subscribe to emails or not

  • PATCHhttps://api.crisp.chat/v1/website/website_id/people/subscription/people_id
  • Tiersuserplugin
  • Scopeswebsite:people:subscriptions
HTTP
Request
(loading)
Response
(loading)

Export People Profiles

POST
/v1/website/{website_id}/people/export/profiles

Exports people profiles. The exported data is sent back to email to the requester user.

URI Parameters
website_id
stringRequired

The website identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/people/export/profiles
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Import People Profiles

POST
/v1/website/{website_id}/people/import/profiles

Imports people profiles. The imported data, eg. a CSV file containing user emails and full names is used to populate website user database.

The import events are sent back asynchronously on the RTM Events channel, using either the event namespace people:import:progress or people:import:done.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
url
stringRequired

File URL containing user data to be imported

mapping
array[object]Required

Raw data to Crisp data mapping

column
numberRequired

Mapping from raw data column index (starts at 1)

field
enum[string]Required

Mapping to Crisp field (regular field, or virtual field starting with _.)

Values

  • email
  • segments
  • notepad
  • person.nickname
  • person.phone
  • person.address
  • person.website
  • person.geolocation.country
  • person.geolocation.city
  • company.name
  • data.[*]
  • created_at
  • active
  • _.person.first_name
  • _.person.last_name
  • _.unsubscribed
options
objectRequired

Import options

column_separator
stringRequired

One-character column separator

skip_header
booleanRequired

Whether to skip headers or not

  • POSThttps://api.crisp.chat/v1/website/website_id/people/import/profiles
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Visitorsin Website

Count Visitors

GET
/v1/website/{website_id}/visitors/count

Counts visitors currently on website.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
count
number

Number of visitors currently on website

active
number

Number of active visitors currently on website (those actively browsing)

limited
boolean

Whether visitor sockets are limited or not (due to high traffic)

  • GEThttps://api.crisp.chat/v1/website/website_id/visitors/count
  • Tiersuserplugin
  • Scopeswebsite:visitors
HTTP
Request
(loading)
Response
(loading)

List Visitors

GET
/v1/website/{website_id}/visitors/list/{page_number}

Lists visitors currently on website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

Page number for visitors paging

Response Data
error
boolean
reason
string
data
array[object]
session_id
string

Session identifier for visitor

nickname
string

Nickname for visitor

email
string

Email for visitor

avatar
string

Avatar for visitor

useragent
string

Useragent as advertised by visitor browser

initiated
boolean

Whether session is initiated or not

active
boolean

Whether the user is actively browsing or not

last_page
object

Last page browsed by visitor

page_title
string

Last page title

page_url
string

Last page URL

geolocation
object

Geolocation for visitor

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

timezone
number

Visitor timezone offset (UTC)

capabilities
array[enum[string]]

Capabilities of the visitor device

Values

  • browsing
  • call
locales
array[string]

Locales supported by visitor (ISO 639-1)

  • GEThttps://api.crisp.chat/v1/website/website_id/visitors/list/page_number
  • Tiersuserplugin
  • Scopeswebsite:visitors
HTTP
Request
(loading)
Response
(loading)

Pinpoint Visitors On A Map

GET
/v1/website/{website_id}/visitors/map{?center_latitude}{&center_longitude}{&center_radius}

Maps visitors in a geographical area, given a geographical center and a map radius (defaults to whole Earth if none given). Visitors are grouped in geographical points. There is a static number of points per area (the area is composed of sub-divisions of equal size). Only points which contain visitors are returned.

The map precision increases as the area radius decreases. If there are too many visitors in a given geographical point, an approximate visitors count number will be given.

URI Parameters
website_id
stringRequired

The website identifier

center_latitude
stringOptional

Area center point latitude

center_longitude
stringOptional

Area center point longitude

center_radius
stringOptional

Area radius (in kilometers)

Response Data
error
boolean
reason
string
data
object
visitors
object

Visitors for geographical point

count
number

Number of visitors in geographical point

threshold
number

The maximum count number as restricted by the API for calculations (may vary)

sessions
array[object]

Sessions associated to the geographical point

session_id
string

Session identifier for session

nickname
string

Nickname for session

email
string

Email for session

avatar
string

Avatar for session

initiated
boolean

Whether session is initiated or not

active
boolean

Whether the user is actively browsing or not

last_page
object

Last page browsed by session

page_title
string

Last page title

page_url
string

Last page URL

timezone
number

Visitor timezone offset (UTC)

capabilities
array[enum[string]]

Capabilities of the visitor device

Values

  • browsing
  • call
locales
array[string]

Locales supported by visitor (ISO 639-1)

geolocation
object

Geolocation for geographical point

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

  • GEThttps://api.crisp.chat/v1/website/website_id/visitors/map
  • Tiersuserplugin
  • Scopeswebsite:visitors
HTTP
Request
(loading)
Response
(loading)

Get Session Identifier From Token

GET
/v1/website/{website_id}/visitors/token/{token_id}

Transforms a token to a session identifier, if any session is bound to the token. The token can be bound to a session from the Crisp chatbox.

URI Parameters
website_id
stringRequired

The website identifier

token_id
stringRequired

The token identifier

Response Data
error
boolean
reason
string
data
array[object]
session_id
string

Session identifier

token_id
string

Token value

  • GEThttps://api.crisp.chat/v1/website/website_id/visitors/token/token_id
  • Tiersuserplugin
  • Scopeswebsite:visitors
HTTP
Request
(loading)
Response
(loading)

Count Blocked Visitors

GET
/v1/website/{website_id}/visitors/blocked

Counts all blocked visitors on website, by rule list.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
array[object]
rule
enum[string]

Rule name

Values

  • ip
  • email
blocked
number

Number of blocked visitors for rule

  • GEThttps://api.crisp.chat/v1/website/website_id/visitors/blocked
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Count Blocked Visitors In Rule

GET
/v1/website/{website_id}/visitors/blocked/{block_rule}

Counts all blocked visitors in rule list on website.

URI Parameters
website_id
stringRequired

The website identifier

block_rule
stringRequired

The block rule (ip or email)

Response Data
error
boolean
reason
string
data
object
rule
enum[string]

Rule name

Values

  • ip
  • email
blocked
number

Number of blocked visitors for rule

  • GEThttps://api.crisp.chat/v1/website/website_id/visitors/blocked/block_rule
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Clear Blocked Visitors In Rule

DELETE
/v1/website/{website_id}/visitors/blocked/{block_rule}

Clears all blocked visitors in rule list on website.

URI Parameters
website_id
stringRequired

The website identifier

block_rule
stringRequired

The block rule (ip or email)

  • DELETEhttps://api.crisp.chat/v1/website/website_id/visitors/blocked/block_rule
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Availabilityin Website

Get Website Availability Status

GET
/v1/website/{website_id}/availability/status

Resolves the website availability status. This tells whether the chatbox is seen as online or away by visitors.

The availability status is set to online if at least one operator can be seen as online (given his account availability settings).

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
status
enum[string]

Availability status

Values

  • online
  • away
  • offline
since
number

Timestamp since when the availability has been updated

  • GEThttps://api.crisp.chat/v1/website/website_id/availability/status
  • Tiersuserplugin
  • Scopeswebsite:availability