REST API Reference (V1)

Updated on October 17, 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
objectRequired

User identity verification challenge (used to double-authenticate deletion)

method
enum[string]Required

Verification method (whichever is more secure for the user account)

Values

  • password
  • token
  • google
secret
stringRequired

Secret value (for method)

  • 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_inbox_id}{&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_inbox_id
stringOptional

Whether to return only conversations categorized under provided inbox identifier

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

inbox_id
string

Inbox 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)

List Spam Conversations

GET
/v1/website/{website_id}/conversations/spams/{page_number}{?filter_type}

Lists spam conversations in website. Those are not conversation entities, but can be converted to conversations if a spam is later accepted as ham.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

The page number (paging in spam list)

filter_type
stringOptional

Filter by spam type (eg. email)

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

Spam identifier

type
enum[string]

Spam type

Values

  • email
reason
string

Reason for spam classification (if any)

metadata
object

Arbitrary metadata from message original

headers
object

Headers from message original (ie. if email)

timestamp
number

Timestamp of spam (when the spam was inserted)

  • GEThttps://api.crisp.chat/v1/website/website_id/conversations/spams/page_number
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Resolve Spam Conversation Content

GET
/v1/website/{website_id}/conversations/spam/{spam_id}/content

Resolves full content for spam conversation.

URI Parameters
website_id
stringRequired

The website identifier

spam_id
stringRequired

The spam identifier

Response Data
error
boolean
reason
string
data
object
spam_id
string

Spam identifier

type
enum[string]

Spam type

Values

  • email
reason
string

Reason for spam classification (if any)

metadata
object

Arbitrary metadata from message original

headers
object

Headers from message original (ie. if email)

content
string

Spam content

timestamp
number

Timestamp of spam (when the spam was inserted)

  • GEThttps://api.crisp.chat/v1/website/website_id/conversations/spam/spam_id/content
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Submit Spam Conversation Decision

POST
/v1/website/{website_id}/conversations/spam/{spam_id}/decision

Submits decision on spam conversation (this allows to accepts or rejects a spam). If rejected, a spam message will be gone forever. If accepted, it will get transformed into a regular conversation.

The decision acknowledgement is sent back asynchronously on the RTM Events channel, using the event namespace spam:decision.

URI Parameters
website_id
stringRequired

The website identifier

spam_id
stringRequired

The spam identifier

Request Body
action
enum[string]Required

Action to take on spam

Values

  • accept
  • reject
  • POSThttps://api.crisp.chat/v1/website/website_id/conversations/spam/spam_id/decision
  • Tiersuser
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

inbox_id
string

Inbox 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

silent
booleanOptional

Whether to notify the assigned operator or not

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

Update Conversation Inbox

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

Updates inbox used for conversation.

URI Parameters
website_id
stringRequired

The website identifier

session_id
stringRequired

The conversation session identifier

Request Body
inbox_id
stringOptional

Inbox identifier (or none)

  • PATCHhttps://api.crisp.chat/v1/website/website_id/conversation/session_id/inbox
  • Tiersuserplugin
  • Scopeswebsite:conversation:sessions
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

inbox_id
string

Inbox identifier for visitor (if any)

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
HTTP
Request
(loading)
Response
(loading)

List Website Operator Availabilities

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

Lists the availabilities for website operators. This maps the availability of each operator in the website.

URI Parameters
website_id
stringRequired

The website identifier

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

User identifier

type
enum[string]

Availability type

Values

  • online
  • away
  • offline
time
object
for
number

Seconds for which the availability is valid

since
number

Timestamp since when the availability has been updated

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

Operatorsin Website

List Website Operators

GET
/v1/website/{website_id}/operators/list

Lists all operator members of website.

URI Parameters
website_id
stringRequired

The website identifier

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

Member type (invite means the operator did not join yet, sandbox stands for a plugin developer from Crisp Marketplace)

Values

  • operator
  • invite
  • sandbox
details
object

Member details

user_id
string

User identifier (for operator and sandbox types only)

email
string

User email (for all types)

avatar
string

User avatar (for operator type only)

first_name
string

User first name (for operator and sandbox types only)

last_name
string

User last name (for operator and sandbox types only)

role
enum[string]

User role (for operator and invite types only)

Values

  • owner
  • member
title
string

User title (if any, for operator type only)

availability
enum[string]

User availability (for operator type only)

Values

  • online
  • away
  • offline
has_token
boolean

Whether operator has Two Factor Authentication enabled or not (for operator type only)

identifier
string

User invite identifier (for invite type only)

key
string

User invite key (for invite type only)

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

List Last Active Website Operators

GET
/v1/website/{website_id}/operators/active

Lists last active website operators, ie. operators who last replied to a visitor message.

URI Parameters
website_id
stringRequired

The website identifier

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

Operator user identifier

avatar
string

Operator avatar

nickname
string

Operator nickname

timestamp
number

Timestamp at which operator was last active

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

Flush Last Active Website Operators

DELETE
/v1/website/{website_id}/operators/active

Flushes the list of last active website operators, ie. operators who last replied to a visitor message.

URI Parameters
website_id
stringRequired

The website identifier

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

Send Email To Website Operators

PATCH
/v1/website/{website_id}/operators/email

Sends an email to target website operators. The email will be delivered to each operator account email address.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
recipient
enum[string]Required

Recipient type

Values

  • all
  • owners
  • members
  • user
user_id
stringOptional

Recipient user identifier (if recipient is user)

subject
stringRequired

Email subject

message
stringRequired

Email message body

target
objectOptional

Target button

label
stringRequired

Target button label

url
stringRequired

Target button URL

  • PATCHhttps://api.crisp.chat/v1/website/website_id/operators/email
  • Tiersuserplugin
  • Scopeswebsite:operators
HTTP
Request
(loading)
Response
(loading)

Operatorin Website

Get A Website Operator

GET
/v1/website/{website_id}/operator/{user_id}

Resolves a given website operator.

URI Parameters
website_id
stringRequired

The website identifier

user_id
stringRequired

The user identifier for operator

Response Data
error
boolean
reason
string
data
object
user_id
string

User identifier

email
string

User email

avatar
string

User avatar

first_name
string

User first name

last_name
string

User last name

role
enum[string]

User role

Values

  • owner
  • member
title
string

User title (if any)

availability
enum[string]

User availability

Values

  • online
  • away
  • offline
has_token
boolean

Whether operator has Two Factor Authentication enabled or not

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

Invite A Website Operator

POST
/v1/website/{website_id}/operator

Invites an email to join website as operator. The target email doesn't need to be a valid Crisp account, since Crisp will send an invite email to that email. The receiver is then prompted to click on a link to either join the website with an existing account, or create a new account on the fly.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
email
stringRequired

Operator email

role
enum[string]Required

Operator role

Values

  • owner
  • member
verify
objectRequired

User identity verification challenge (used to double-authenticate invite)

method
enum[string]Required

Verification method (whichever is more secure for the user account)

Values

  • password
  • token
  • google
secret
stringRequired

Secret value (for method)

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

Change Operator Membership

PATCH
/v1/website/{website_id}/operator/{user_id}

Changes the membership of an existing operator. Useful to downgrade or upgrade an operator from/to owner role, or change their title in the team.

URI Parameters
website_id
stringRequired

The website identifier

user_id
stringRequired

The user identifier for operator

Request Body
role
enum[string]Optional

Operator role

Values

  • owner
  • member
title
stringOptional

Operator title (if any)

  • PATCHhttps://api.crisp.chat/v1/website/website_id/operator/user_id
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)
DELETE
/v1/website/{website_id}/operator/{user_id}

Unlinks given operator from website. Note that the last operator in the website cannot be unlinked.

URI Parameters
website_id
stringRequired

The website identifier

user_id
stringRequired

The user identifier for operator

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

Helpdeskin Website

Check If Helpdesk Exists

HEAD
/v1/website/{website_id}/helpdesk

Checks if helpdesk exists for website (ie. if it has been initialized).

URI Parameters
website_id
stringRequired

The website identifier

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

Resolve Helpdesk

GET
/v1/website/{website_id}/helpdesk

Resolves helpdesk information for website.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
name
string

Name of the helpdesk

url
string

Public URL of the helpdesk

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

Initialize Helpdesk

POST
/v1/website/{website_id}/helpdesk

Initializes a new helpdesk for website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
name
stringRequired

Name of the helpdesk

domain_basic
stringRequired

Basic domain of the helpdesk (subdomain of default root domain)

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

Delete Helpdesk

DELETE
/v1/website/{website_id}/helpdesk

Deletes helpdesk for website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
verify
objectRequired

User identity verification challenge (used to double-authenticate deletion)

method
enum[string]Required

Verification method (whichever is more secure for the user account)

Values

  • password
  • token
  • google
secret
stringRequired

Secret value (for method)

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

List Helpdesk Locales

GET
/v1/website/{website_id}/helpdesk/locales/{page_number}

Lists locales for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

Page number for locales paging

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

Locale identifier

locale
string

Locale code for helpdesk (ISO 639-1)

url
string

Public URL of the helpdesk for locale

articles
number

Number of articles for locale

categories
number

Number of categories for locale

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

Add Helpdesk Locale

POST
/v1/website/{website_id}/helpdesk/locale

Adds a locale for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
locale
stringRequired

Locale code for helpdesk to add (ISO 639-1)

  • POSThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:locales
HTTP
Request
(loading)
Response
(loading)

Check If Helpdesk Locale Exists

HEAD
/v1/website/{website_id}/helpdesk/locale/{locale}

Checks if a helpdesk locale exists for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

  • HEADhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:locales
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Locale

GET
/v1/website/{website_id}/helpdesk/locale/{locale}

Resolves a locale for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

Response Data
error
boolean
reason
string
data
object
locale_id
string

Locale identifier

locale
string

Locale code for helpdesk (ISO 639-1)

url
string

Public URL of the helpdesk for locale

articles
number

Number of articles for locale

categories
number

Number of categories for locale

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

Delete Helpdesk Locale

DELETE
/v1/website/{website_id}/helpdesk/locale/{locale}

Deletes a locale for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

  • DELETEhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:locales
HTTP
Request
(loading)
Response
(loading)

List Helpdesk Locale Articles

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/articles/{page_number}{?order_visits}{&search_title}{&filter_category_id}{&filter_section_id}{&filter_status_published}{&filter_status_draft}{&filter_visibility_visible}{&filter_visibility_hidden}{&filter_date_start}{&filter_date_end}

Lists articles for a helpdesk locale in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

page_number
stringOptional

Page number for articles paging

order_visits
stringOptional

Whether to order articles by visits instead of default order (1 or 0)

search_title
stringOptional

Search by article title

filter_category_id
stringOptional

Filter by article category identifier (identifier or none)

filter_section_id
stringOptional

Filter by article section identifier (identifier or none, requires filter_category_id to be set as well)

filter_status_published
stringOptional

Filter by article published status (1 or 0)

filter_status_draft
stringOptional

Filter by article draft status (1 or 0)

filter_visibility_visible
stringOptional

Filter by article visible visibility (1 or 0)

filter_visibility_hidden
stringOptional

Filter by article hidden visibility (1 or 0)

filter_date_start
stringOptional

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

filter_date_end
stringOptional

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

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

Article identifier

title
string

Title of the article

status
enum[string]

Status of the article

Values

  • published
  • draft
visibility
enum[string]

Visibility of the article (if status is published)

Values

  • visible
  • hidden
featured
boolean

Whether the article is featured or not

visits
number

Number of times the article has been visited

order
number

Article ordering weight

url
string

Public URL of the article (if status is published)

category
object

Category of the article (if any)

category_id
string

Category identifier

name
string

Name of the category

color
string

Color of the category (hexadecimal color code, if any)

section
object

Section within the category (if any)

section_id
string

Section identifier

name
string

Name of the section

created_at
number

Article creation timestamp

updated_at
number

Article update timestamp

published_at
number

Article publication timestamp

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

Add A New Helpdesk Locale Article

POST
/v1/website/{website_id}/helpdesk/locale/{locale}/article

Adds a new locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

Request Body
title
stringRequired

Title of the article

  • POSThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Check If Helpdesk Locale Article Exists

HEAD
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}

Checks if a locale article exists for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

  • HEADhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Locale Article

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}

Resolves a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

Response Data
error
boolean
reason
string
data
object
article_id
string

Article identifier

title
string

Title of the article

description
string

Description of the article (if any)

content
string

Text content of the article

status
enum[string]

Status of the article

Values

  • published
  • draft
visibility
enum[string]

Visibility of the article (if status is published)

Values

  • visible
  • hidden
featured
boolean

Whether the article is featured or not

visits
number

Number of times the article has been visited

order
number

Article ordering weight

url
string

Public URL of the article (if status is published)

created_at
number

Article creation timestamp

updated_at
number

Article update timestamp

published_at
number

Article publication timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Save Helpdesk Locale Article

PUT
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}

Saves a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

Request Body
title
stringRequired

Title of the article

description
stringRequired

Description of the article (if any)

content
stringRequired

Text content of the article

featured
booleanRequired

Whether the article is featured or not

order
numberRequired

Article ordering weight

  • PUThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Update Helpdesk Locale Article

PATCH
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}

Updates a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

Request Body
title
stringOptional

Title of the article

description
stringOptional

Description of the article (if any)

content
stringOptional

Text content of the article

featured
booleanOptional

Whether the article is featured or not

order
numberOptional

Article ordering weight

  • PATCHhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Delete Helpdesk Locale Article

DELETE
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}

Deletes a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Locale Article Page

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/page

Resolves a locale article page information for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

Response Data
error
boolean
reason
string
data
object
title
string

Title of the article

url
string

Public URL of the article (if article status is published)

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/page
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Locale Article Category

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/category

Resolves a locale article category for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

Response Data
error
boolean
reason
string
data
object
category_id
string

Category identifier (if any)

section_id
string

Section identifier (if any)

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/category
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Update Helpdesk Locale Article Category

PATCH
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/category

Updates a locale article category for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

Request Body
category_id
stringRequired

Category identifier (can be blank)

section_id
stringOptional

Section identifier (can be blank)

  • PATCHhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/category
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

List Helpdesk Locale Article Alternates

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/alternates

Lists alternate locales on a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

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

Locale code for alternate

article_id
string

Article identifier for alternate

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/alternates
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Check If Helpdesk Locale Article Alternate Exists

HEAD
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/alternate/{locale_linked}

Checks if alternate locale exists on a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

locale_linked
stringRequired

The linked locale code

  • HEADhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/alternate/locale_linked
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Locale Article Alternate

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/alternate/{locale_linked}

Resolves alternate locale on a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

locale_linked
stringRequired

The linked locale code

Response Data
error
boolean
reason
string
data
object
locale
string

Locale code for alternate

article_id
string

Article identifier for alternate

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/alternate/locale_linked
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Save Helpdesk Locale Article Alternate

PUT
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/alternate/{locale_linked}

Saves alternate locale on a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

locale_linked
stringRequired

The linked locale code

Request Body
article_id
stringRequired

Article identifier to be linked for locale

  • PUThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/alternate/locale_linked
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Delete Helpdesk Locale Article Alternate

DELETE
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/alternate/{locale_linked}

Deletes alternate locale on a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

locale_linked
stringRequired

The linked locale code

  • DELETEhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/alternate/locale_linked
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Publish Helpdesk Locale Article

POST
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/publish

Publishes a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/publish
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

Unpublish Helpdesk Locale Article

POST
/v1/website/{website_id}/helpdesk/locale/{locale}/article/{article_id}/unpublish

Unpublishes a locale article for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

article_id
stringRequired

The article identifier

  • POSThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/article/article_id/unpublish
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:articles
HTTP
Request
(loading)
Response
(loading)

List Helpdesk Locale Categories

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/categories/{page_number}{?search_name}

Lists locale categories for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

page_number
stringOptional

Page number for categories paging

search_name
stringOptional

Search by category name

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

Category identifier

name
string

Name of the category

description
string

Description of the category (if any)

color
string

Color of the category (hexadecimal color code, if any)

image
string

Image URL of the category (if any)

order
number

Category ordering weight

url
string

Public URL of the category

articles
number

Number of articles in the category

sections
number

Number of sections in the category

created_at
number

Category creation timestamp

updated_at
number

Category update timestamp

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

Add Helpdesk Locale Category

POST
/v1/website/{website_id}/helpdesk/locale/{locale}/category

Adds a locale category for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

Request Body
name
stringRequired

Name of the category to add

  • POSThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Check If Helpdesk Locale Category Exists

HEAD
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}

Checks if a locale category exists for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

  • HEADhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Locale Category

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}

Resolves a locale category for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

Response Data
error
boolean
reason
string
data
object
category_id
string

Category identifier

name
string

Name of the category

description
string

Description of the category (if any)

color
string

Color of the category (hexadecimal color code, if any)

image
string

Image URL of the category (if any)

order
number

Category ordering weight

url
string

Public URL of the category

articles
number

Number of articles in the category

sections
number

Number of sections in the category

created_at
number

Category creation timestamp

updated_at
number

Category update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Save Helpdesk Locale Category

PUT
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}

Saves a locale category for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

Request Body
name
stringRequired

Name of the category

description
stringRequired

Description of the category (can be blank)

color
stringRequired

Color of the category (hexadecimal color code, can be blank)

image
stringRequired

Image URL of the category (can be blank)

order
numberRequired

Category ordering weight

  • PUThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Update Helpdesk Locale Category

PATCH
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}

Updates a locale category for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

Request Body
name
stringOptional

Name of the category

description
stringOptional

Description of the category (can be blank)

color
stringOptional

Color of the category (hexadecimal color code, can be blank)

image
stringOptional

Image URL of the category (can be blank)

order
numberOptional

Category ordering weight

  • PATCHhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Delete Helpdesk Locale Category

DELETE
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}

Deletes a locale category for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

List Helpdesk Locale Sections

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}/sections/{page_number}{?search_name}

Lists locale sections for helpdesk in website and category.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

page_number
stringOptional

Page number for sections paging

search_name
stringOptional

Search by section name

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

Section identifier

name
string

Name of the section

order
number

Section ordering weight

created_at
number

Section creation timestamp

updated_at
number

Section update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id/sections/page_number
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Add Helpdesk Locale Section

POST
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}/section

Adds a locale section for helpdesk in website and category.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

Request Body
name
stringRequired

Name of the section to add

  • POSThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id/section
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Check If Helpdesk Locale Section Exists

HEAD
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}/section/{section_id}

Checks if a locale section exists for helpdesk in website and category.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

section_id
stringRequired

The section identifier

  • HEADhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id/section/section_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Locale Section

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}/section/{section_id}

Resolves a locale section for helpdesk in website and category.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

section_id
stringRequired

The section identifier

Response Data
error
boolean
reason
string
data
object
section_id
string

Section identifier

name
string

Name of the section

order
number

Section ordering weight

created_at
number

Section creation timestamp

updated_at
number

Section update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id/section/section_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Save Helpdesk Locale Section

PUT
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}/section/{section_id}

Saves a locale section for helpdesk in website and category.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

section_id
stringRequired

The section identifier

Request Body
name
stringRequired

Name of the section

order
numberRequired

Section ordering weight

  • PUThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id/section/section_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Update Helpdesk Locale Section

PATCH
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}/section/{section_id}

Updates a locale section for helpdesk in website and category.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

section_id
stringRequired

The section identifier

Request Body
name
stringOptional

Name of the section

order
numberOptional

Section ordering weight

  • PATCHhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id/section/section_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Delete Helpdesk Locale Section

DELETE
/v1/website/{website_id}/helpdesk/locale/{locale}/category/{category_id}/section/{section_id}

Deletes a locale section for helpdesk in website and category.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

category_id
stringRequired

The category identifier

section_id
stringRequired

The section identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/category/category_id/section/section_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:categories
HTTP
Request
(loading)
Response
(loading)

Map Helpdesk Locale Feedback Ratings

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/feedback/ratings{?filter_date_start}{&filter_date_end}

Map locale feedback ratings for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

filter_date_start
stringOptional

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

filter_date_end
stringOptional

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

Response Data
error
boolean
reason
string
data
object
ratings
object

Ratings map

helpful
number

Number of helpful ratings left

unhelpful
number

Number of unhelpful ratings left

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/locale/locale/feedback/ratings
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:feedbacks
HTTP
Request
(loading)
Response
(loading)

List Helpdesk Locale Feedbacks

GET
/v1/website/{website_id}/helpdesk/locale/{locale}/feedback/list/{page_number}{?filter_date_start}{&filter_date_end}

Lists locale feedbacks for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

page_number
stringOptional

The page number (paging in feedbacks list)

filter_date_start
stringOptional

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

filter_date_end
stringOptional

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

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

Rating for feedback

Values

  • helpful
  • unhelpful
comment
string

Comment left for feedback (if any)

article
object

Article associated to feedback

article_id
string

Article identifier

title
string

Title of the article

url
string

Public URL of the article (if status is published)

session
object

Feedback author (if any)

session_id
string

Session identifier for feedback author

nickname
string

Nickname for feedback author

email
string

Email for feedback author

avatar
string

Avatar for feedback author

geolocation
object

Geolocation for feedback author

country
string

Country code

region
string

Region code

city
string

City name

coordinates
object

Location coordinates

latitude
number

Latitude coordinate

longitude
number

Longitude coordinate

assigned
object

Assigned operator (if any)

user_id
string

Operator user identifier

created_at
number

Feedback creation timestamp

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

Import External Helpdesk To Locale

POST
/v1/website/{website_id}/helpdesk/locale/{locale}/import

Imports a whole external helpdesk to Crisp, as a Crisp Helpdesk. The import crawler pipeline is asynchronous.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

Request Body
helpdesk_url
stringRequired

URL of the external helpdesk to import

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

Export Helpdesk Locale Articles

POST
/v1/website/{website_id}/helpdesk/locale/{locale}/export

Exports helpdesk articles for locale. The exported data is sent back to email to the requester user.

URI Parameters
website_id
stringRequired

The website identifier

locale
stringRequired

The locale code

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

List Helpdesk Redirections

GET
/v1/website/{website_id}/helpdesk/redirections/{page_number}

Lists redirections for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

Page number for redirections paging

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

Redirection identifier

path
string

Redirection source path

target
string

Redirection destination target path

created_at
number

Redirection creation timestamp

updated_at
number

Redirection update timestamp

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

Add Helpdesk Redirection

POST
/v1/website/{website_id}/helpdesk/redirection

Adds a redirection for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
path
stringRequired

Redirection source path

target
stringRequired

Redirection destination target path

  • POSThttps://api.crisp.chat/v1/website/website_id/helpdesk/redirection
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:redirections
HTTP
Request
(loading)
Response
(loading)

Check If Helpdesk Redirection Exists

HEAD
/v1/website/{website_id}/helpdesk/redirection/{redirection_id}

Checks if a helpdesk redirection exists for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

redirection_id
stringRequired

The redirection identifier

  • HEADhttps://api.crisp.chat/v1/website/website_id/helpdesk/redirection/redirection_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:redirections
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Redirection

GET
/v1/website/{website_id}/helpdesk/redirection/{redirection_id}

Resolves a redirection for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

redirection_id
stringRequired

The redirection identifier

Response Data
error
boolean
reason
string
data
object
redirection_id
string

Redirection identifier

path
string

Redirection source path

target
string

Redirection destination target path

created_at
number

Redirection creation timestamp

updated_at
number

Redirection update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/redirection/redirection_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:redirections
HTTP
Request
(loading)
Response
(loading)

Delete Helpdesk Redirection

DELETE
/v1/website/{website_id}/helpdesk/redirection/{redirection_id}

Deletes a redirection for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

redirection_id
stringRequired

The redirection identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/helpdesk/redirection/redirection_id
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:redirections
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Settings

GET
/v1/website/{website_id}/helpdesk/settings

Resolves settings for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
name
string

Name of the helpdesk

appearance
object

Appearance configuration of the helpdesk

logos
object

Logos of the helpdesk

header
string

Header logo URL (if any)

footer
string

Footer logo URL (if any)

banner
string

Banner image URL (if any)

behavior
object

Behavior configuration of the helpdesk

frequently_read
boolean

Whether to show frequently read articles on homepage or not

show_category_images
boolean

Whether to show category images on homepage or not

show_chatbox
boolean

Whether to show chatbox on helpdesk or not

ask_feedback
boolean

Whether to ask for user feedback at the end of articles or not

locale_picker
boolean

Whether to show a locale picker in header or not

refer_link
boolean

Whether to show a link to Crisp in the footer of the helpdesk or not

forbid_indexing
boolean

Whether to forbid search engine indexing of all helpdesk pages

status_health_dead
boolean

Whether to show status banner, when status page reports as dead (if Status Page plugin is used)

include
object

Include configuration for the helpdesk

html
string

Raw HTML include (if any)

access
object

Access restrictions for the helpdesk

password
string

Password requested to access the helpdesk (if any)

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

Save Helpdesk Settings

PATCH
/v1/website/{website_id}/helpdesk/settings

Saves settings for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
name
stringOptional

Name of the helpdesk

appearance
objectOptional

Appearance configuration of the helpdesk

logos
objectOptional

Logos of the helpdesk

header
stringOptional

Header logo URL (can be blank)

footer
stringOptional

Footer logo URL (can be blank)

banner
stringOptional

Banner image URL (can be blank)

behavior
objectOptional

Behavior configuration of the helpdesk

frequently_read
booleanOptional

Whether to show frequently read articles on homepage or not

show_category_images
booleanOptional

Whether to show category images on homepage or not

show_chatbox
booleanOptional

Whether to show chatbox on helpdesk or not

ask_feedback
booleanOptional

Whether to ask for user feedback at the end of articles or not

locale_picker
booleanOptional

Whether to show a locale picker in header or not

refer_link
booleanOptional

Whether to show a link to Crisp in the footer of the helpdesk or not

forbid_indexing
booleanOptional

Whether to forbid search engine indexing of all helpdesk pages

status_health_dead
booleanOptional

Whether to show status banner, when status page reports as dead (if Status Page plugin is used)

include
objectOptional

Include configuration for the helpdesk

html
stringOptional

Raw HTML include (if any)

access
objectOptional

Access restrictions for the helpdesk

password
stringOptional

Password requested to access the helpdesk (if any)

  • PATCHhttps://api.crisp.chat/v1/website/website_id/helpdesk/settings
  • Tiersuserplugin
  • Scopeswebsite:helpdesk:settings
HTTP
Request
(loading)
Response
(loading)

Resolve Helpdesk Domain

GET
/v1/website/{website_id}/helpdesk/domain

Resolves domain for helpdesk in website.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
root
string

Root domain for all helpdesks

basic
string

Basic domain (subdomain of provided root domain)

custom
string

Custom domain (fully qualified domain, if any)

verified
boolean

Whether in-use domain could lastly be verified or not (domain is re-validated periodically)

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

Request Helpdesk Domain Change

PATCH
/v1/website/{website_id}/helpdesk/domain

Requests a change in the domain used for helpdesk. The change will be propagated once all setup steps are fulfilled (see the setup route).

The domain validation result is sent back asynchronously on the RTM Events channel, using either event namespace website:validate:domain:valid or website:validate:domain:invalid (if the custom domain was changed and thus requires validation).

URI Parameters
website_id
stringRequired

The website identifier

Request Body
basic
stringOptional

Basic domain (subdomain of crisp.help)

custom
stringOptional

Custom domain (fully qualified domain, can be blank)

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

Generate Helpdesk Domain Setup Flow

GET
/v1/website/{website_id}/helpdesk/domain/setup{?custom}

Retrieves the domain setup flow for helpdesk. This will return the DNS records required for helpdesk domain setup.

URI Parameters
website_id
stringRequired

The website identifier

custom
stringOptional

Custom domain to use for setup

Response Data
error
boolean
reason
string
data
object
custom
string

Custom helpdesk domain to return setup for

setup
object

Setup flow for custom helpdesk domain

records
array[object]

DNS records for custom helpdesk domain

type
enum[string]

DNS record type

Values

  • a
  • aaaa
  • cname
  • mx
  • txt
  • srv
query
enum[string]

DNS query type (ie. record valid for query type)

Values

  • a
  • aaaa
  • cname
  • mx
  • txt
  • srv
name
string

DNS record name

value
string

DNS record value

  • GEThttps://api.crisp.chat/v1/website/website_id/helpdesk/domain/setup
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Campaignsin Website

List Campaigns

GET
/v1/website/{website_id}/campaigns/list/{page_number}{?search_name}{&filter_tag}{&filter_type_one_shot}{&filter_type_automated}{&filter_status_not_configured}{&filter_status_ready}{&filter_status_paused}{&filter_status_sending}{&filter_status_done}

Lists campaigns for website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

Page number for campaigns paging

search_name
stringOptional

Search by campaign name

filter_tag
stringOptional

Filter by campaign tag

filter_type_one_shot
stringOptional

Filter by campaign one-shot type (1 or 0)

filter_type_automated
stringOptional

Filter by campaign automated type (1 or 0)

filter_status_not_configured
stringOptional

Filter by campaign not configured status (1 or 0)

filter_status_ready
stringOptional

Filter by campaign ready status (1 or 0)

filter_status_paused
stringOptional

Filter by campaign paused status (1 or 0)

filter_status_sending
stringOptional

Filter by campaign sending status (1 or 0)

filter_status_done
stringOptional

Filter by campaign done status (1 or 0)

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

Campaign identifier

type
enum[string]

Campaign type

Values

  • one-shot
  • automated
format
enum[string]

Campaign format

Values

  • markdown
  • html
name
string

Campaign name

subject
string

Campaign subject

tag
string

Campaign tag (if any)

ready
boolean

Campaign ready state

dispatched
boolean

Campaign dispatched state

running
boolean

Campaign running state

progress
number

Campaign progress percentage (from 0 to 100)

targets
number

Number of targets (number of users the campaign reaches)

reached
number

Number of reached users (number of users who received the campaign message)

created_at
number

Campaign creation timestamp

updated_at
number

Campaign update timestamp

dispatched_at
number

Campaign dispatch timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/campaigns/list/page_number
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

List Campaign Tags

GET
/v1/website/{website_id}/campaigns/tags

Lists campaign tags for website.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
array[string]

Campaign tags

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

List Campaign Templates

GET
/v1/website/{website_id}/campaigns/templates/{page_number}{?search_name}{&filter_type_static}{&filter_type_custom}

Lists campaign templates for website.

URI Parameters
website_id
stringRequired

The website identifier

page_number
stringOptional

Page number for templates paging

search_name
stringOptional

Search by template name

filter_type_static
stringOptional

Filter by template static type (1 or 0)

filter_type_custom
stringOptional

Filter by template custom type (1 or 0)

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

Template identifier

type
enum[string]

Template type

Values

  • static
  • custom
name
string

Template name

format
enum[string]

Template format

Values

  • markdown
  • html
created_at
number

Template creation timestamp

updated_at
number

Template update timestamp

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

Create A New Campaign Template

POST
/v1/website/{website_id}/campaigns/template

Creates a new campaign template.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
name
stringRequired

Template name

format
enum[string]Required

Template format

Values

  • markdown
  • html
  • POSThttps://api.crisp.chat/v1/website/website_id/campaigns/template
  • Tiersuserplugin
  • Scopeswebsite:campaign:templates
HTTP
Request
(loading)
Response
(loading)

Check If Campaign Template Exists

HEAD
/v1/website/{website_id}/campaigns/template/{template_id}

Checks if given campaign template exists.

URI Parameters
website_id
stringRequired

The website identifier

template_id
stringRequired

The template identifier

  • HEADhttps://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
  • Tiersuserplugin
  • Scopeswebsite:campaign:templates
HTTP
Request
(loading)
Response
(loading)

Get A Campaign Template

GET
/v1/website/{website_id}/campaigns/template/{template_id}

Resolves campaign template information.

URI Parameters
website_id
stringRequired

The website identifier

template_id
stringRequired

The template identifier

Response Data
error
boolean
reason
string
data
object
template_id
string

Template identifier

type
enum[string]

Template type

Values

  • static
  • custom
name
string

Template name

format
enum[string]

Template format

Values

  • markdown
  • html
content
string

Template content

created_at
number

Template creation timestamp

updated_at
number

Template update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
  • Tiersuserplugin
  • Scopeswebsite:campaign:templates
HTTP
Request
(loading)
Response
(loading)

Save A Campaign Template

PUT
/v1/website/{website_id}/campaigns/template/{template_id}

Saves a campaign template in website, and overwrite previous template information.

URI Parameters
website_id
stringRequired

The website identifier

template_id
stringRequired

The template identifier

Request Body
name
stringRequired

Template name

format
enum[string]Required

Template format

Values

  • markdown
  • html
content
stringRequired

Template content

  • PUThttps://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
  • Tiersuserplugin
  • Scopeswebsite:campaign:templates
HTTP
Request
(loading)
Response
(loading)

Update A Campaign Template

PATCH
/v1/website/{website_id}/campaigns/template/{template_id}

Updates a campaign template in website, and save only changed fields.

URI Parameters
website_id
stringRequired

The website identifier

template_id
stringRequired

The template identifier

Request Body
name
stringOptional

Template name

format
enum[string]Optional

Template format

Values

  • markdown
  • html
content
stringOptional

Template content

  • PATCHhttps://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
  • Tiersuserplugin
  • Scopeswebsite:campaign:templates
HTTP
Request
(loading)
Response
(loading)

Remove A Campaign Template

DELETE
/v1/website/{website_id}/campaigns/template/{template_id}

Removes a campaign template in website.

URI Parameters
website_id
stringRequired

The website identifier

template_id
stringRequired

The template identifier

  • DELETEhttps://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
  • Tiersuserplugin
  • Scopeswebsite:campaign:templates
HTTP
Request
(loading)
Response
(loading)

Campaignin Website

Create A New Campaign

POST
/v1/website/{website_id}/campaign

Creates a new campaign.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
type
enum[string]Required

Campaign type

Values

  • one-shot
  • automated
name
stringRequired

Campaign name

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

Check If Campaign Exists

HEAD
/v1/website/{website_id}/campaign/{campaign_id}

Checks if given campaign exists.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

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

Get A Campaign

GET
/v1/website/{website_id}/campaign/{campaign_id}

Resolves campaign information.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

Response Data
error
boolean
reason
string
data
object
campaign_id
string

Campaign identifier

type
enum[string]

Campaign type

Values

  • one-shot
  • automated
format
enum[string]

Campaign format

Values

  • markdown
  • html
name
string

Campaign name

subject
string

Campaign subject

tag
string

Campaign tag (if any)

sender
object

Campaign sender

user_id
string

Sender user identifier (member of website)

recipients
object

Campaign recipients (if type is one-shot)

type
enum[string]

Recipient routing type

Values

  • all
  • segment
  • people
  • filter
segments
array[string]

Routing segments (if type is segment)

people
array[string]

Routing people (if type is people)

filter
array[object]

Routing filter (if type is filter)

model
enum[string]

Filter model

Values

  • people
criterion
string

Filter criterion (in model)

operator
enum[string]

Filter operator

Values

  • eq
  • neq
  • ex
  • nex
  • has
  • nhas
  • sw
  • ew
  • gte
  • lte
  • gt
  • lt
query
array[string]

Filter query terms

flow
object

Campaign flow (if type is automated)

launch_event
string

Event identifier that triggers automation flow (to run campaign for a user)

assert_filter
array[object]

Filter to assert when event is triggered (can be empty)

model
enum[string]

Filter model

Values

  • people
criterion
string

Filter criterion (in model)

operator
enum[string]

Filter operator

Values

  • eq
  • neq
  • ex
  • nex
  • has
  • nhas
  • sw
  • ew
  • gte
  • lte
  • gt
  • lt
query
array[string]

Filter query terms

assert_delay
number

Delay in minutes after which to process assertions (no delay by default)

deliver_once
boolean

Ensures campaign is delivered once at a maximum for a given user, or not

deliver_delay
number

Delivery delay in minutes (no delay by default)

message
string

Campaign message

options
object

Campaign options

deliver_to_chatbox
boolean

Whether to deliver message to chatbox or not

deliver_to_email
boolean

Whether to deliver message to email or not

sender_name_website
boolean

Whether to append website name after email sender name or not

sender_email_reply
boolean

Email address to use as a reply-to address for email campaigns

tracking
boolean

Whether to enable tracking or not

statistics
object

Campaign statistics

opened
number

Number of recipients who opened the campaign email

clicked
number

Number of recipients who clicked on a link in the campaign email

unsubscribed
number

Number of recipients who unsubscribed from the campaign email

ready
boolean

Campaign ready state

dispatched
boolean

Campaign dispatched state

running
boolean

Campaign running state

progress
number

Campaign progress percentage (from 0 to 100)

targets
number

Number of targets (number of users the campaign reaches)

reached
number

Number of reached users (number of users who received the campaign message)

created_at
number

Campaign creation timestamp

updated_at
number

Campaign update timestamp

dispatched_at
number

Campaign dispatch timestamp

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

Save A Campaign

PUT
/v1/website/{website_id}/campaign/{campaign_id}

Saves a campaign in website, and overwrite previous campaign information.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

Request Body
type
enum[string]Required

Campaign type

Values

  • one-shot
  • automated
format
enum[string]Required

Campaign format

Values

  • markdown
  • html
name
stringRequired

Campaign name

subject
stringRequired

Campaign subject

tag
stringOptional

Campaign tag (can be empty)

sender
objectRequired

Campaign sender

user_id
stringRequired

Sender user identifier (member of website)

recipients
objectRequired

Campaign recipients (if type is one-shot)

type
enum[string]Required

Recipient routing type

Values

  • all
  • segment
  • people
  • filter
segments
array[string]Optional

Routing segments (if type is segment)

people
array[string]Optional

Routing people (if type is people)

filter
array[object]Optional

Routing filter (if type is filter)

model
enum[string]Required

Filter model

Values

  • people
criterion
stringRequired

Filter criterion (in model)

operator
enum[string]Required

Filter operator

Values

  • eq
  • neq
  • ex
  • nex
  • has
  • nhas
  • sw
  • ew
  • gte
  • lte
  • gt
  • lt
query
array[string]Required

Filter query terms

flow
objectRequired

Campaign flow (if type is automated)

launch_event
stringRequired

Event identifier that triggers automation flow (to run campaign for a user)

assert_filter
array[object]Required

Filter to assert when event is triggered (can be empty)

model
enum[string]Required

Filter model

Values

  • people
criterion
stringRequired

Filter criterion (in model)

operator
enum[string]Required

Filter operator

Values

  • eq
  • neq
  • ex
  • nex
  • has
  • nhas
  • sw
  • ew
  • gte
  • lte
  • gt
  • lt
query
array[string]Required

Filter query terms

assert_delay
numberRequired

Delay in minutes after which to process assertions (no delay by default)

deliver_once
booleanRequired

Ensures campaign is delivered once at a maximum for a given user, or not

deliver_delay
numberRequired

Delivery delay in minutes (no delay by default)

message
stringRequired

Campaign message

options
objectOptional

Campaign options

deliver_to_chatbox
booleanRequired

Whether to deliver message to chatbox or not

deliver_to_email
booleanRequired

Whether to deliver message to email or not

sender_name_website
booleanRequired

Whether to append website name after email sender name or not

sender_email_reply
booleanRequired

Email address to use as a reply-to address for email campaigns

tracking
booleanRequired

Whether to enable tracking or not

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

Update A Campaign

PATCH
/v1/website/{website_id}/campaign/{campaign_id}

Updates a campaign in website, and save only changed fields.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

Request Body
type
enum[string]Optional

Campaign type

Values

  • one-shot
  • automated
format
enum[string]Optional

Campaign format

Values

  • markdown
  • html
name
stringOptional

Campaign name

subject
stringOptional

Campaign subject

tag
stringOptional

Campaign tag (can be empty)

sender
objectOptional

Campaign sender

user_id
stringRequired

Sender user identifier (member of website)

recipients
objectOptional

Campaign recipients (if type is one-shot)

type
enum[string]Required

Recipient routing type

Values

  • all
  • segment
  • people
  • filter
segments
array[string]Optional

Routing segments (if type is segment)

people
array[string]Optional

Routing people (if type is people)

filter
array[object]Optional

Routing filter (if type is filter)

model
enum[string]Required

Filter model

Values

  • people
criterion
stringRequired

Filter criterion (in model)

operator
enum[string]Required

Filter operator

Values

  • eq
  • neq
  • ex
  • nex
  • has
  • nhas
  • sw
  • ew
  • gte
  • lte
  • gt
  • lt
query
array[string]Required

Filter query terms

flow
objectOptional

Campaign flow (if type is automated)

launch_event
stringRequired

Event identifier that triggers automation flow (to run campaign for a user)

assert_filter
array[object]Required

Filter to assert when event is triggered (can be empty)

model
enum[string]Required

Filter model

Values

  • people
criterion
stringRequired

Filter criterion (in model)

operator
enum[string]Required

Filter operator

Values

  • eq
  • neq
  • ex
  • nex
  • has
  • nhas
  • sw
  • ew
  • gte
  • lte
  • gt
  • lt
query
array[string]Required

Filter query terms

assert_delay
numberRequired

Delay in minutes after which to process assertions (no delay by default)

deliver_once
booleanRequired

Ensures campaign is delivered once at a maximum for a given user, or not

deliver_delay
numberRequired

Delivery delay in minutes (no delay by default)

message
stringOptional

Campaign message

options
objectOptional

Campaign options

deliver_to_chatbox
booleanRequired

Whether to deliver message to chatbox or not

deliver_to_email
booleanRequired

Whether to deliver message to email or not

sender_name_website
booleanRequired

Whether to append website name after email sender name or not

sender_email_reply
booleanRequired

Email address to use as a reply-to address for email campaigns

tracking
booleanRequired

Whether to enable tracking or not

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

Remove A Campaign

DELETE
/v1/website/{website_id}/campaign/{campaign_id}

Removes a campaign in website.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

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

Dispatch A Campaign

POST
/v1/website/{website_id}/campaign/{campaign_id}/dispatch

Dispatches a ready campaign.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

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

Resume A Campaign

POST
/v1/website/{website_id}/campaign/{campaign_id}/resume

Resumes a paused and dispatched campaign.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

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

Pause A Campaign

POST
/v1/website/{website_id}/campaign/{campaign_id}/pause

Pauses a running and dispatched campaign.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

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

Test A Campaign

POST
/v1/website/{website_id}/campaign/{campaign_id}/test

Tests a ready campaign.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

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

List Campaign Recipients

GET
/v1/website/{website_id}/campaign/{campaign_id}/recipients/{page_number}

Lists campaigns recipients on a non-dispatched one-shot campaign for website. This can be used to preview the recipients the campaign will get delivered to.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

page_number
stringOptional

Page number for recipients paging

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

subscribed
boolean

Whether profile is subscribed to emails or not

  • GEThttps://api.crisp.chat/v1/website/website_id/campaign/campaign_id/recipients/page_number
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

List Campaign Statistics

GET
/v1/website/{website_id}/campaign/{campaign_id}/statistics/{action}/{page_number}

Lists campaigns statistics on action for website. This can be used to see who opened a sent campaign, clicked on a link or unsubscribed from the campaign.

URI Parameters
website_id
stringRequired

The website identifier

campaign_id
stringRequired

The campaign identifier

action
stringRequired

The statistics action (either clicked, opened or unsubscribed)

page_number
stringOptional

Page number for statistics paging

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

Profile associated to statistics point

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

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

data
object

Generic data associated to statistics (format depends on requested action)

created_at
number

Statistics create timestamp

updated_at
number

Statistics update timestamp

  • GEThttps://api.crisp.chat/v1/website/website_id/campaign/campaign_id/statistics/action/page_number
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Analyticsin Website

Generate Analytics

POST
/v1/website/{website_id}/analytics/generate

Generates analytics for given type and metric in website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
metric
enum[string]Required

Analytics metric

Values

  • conversation
  • conversation_assigned
  • conversation_shortcut
  • conversation_segment
  • helpdesk_read
  • helpdesk_search
  • visitor_visit
  • visitor_trigger
  • campaign_activity
  • campaign_sent
  • people_created
  • status_downtime
type
enum[string]Required

Analytics type (depends on metric value)

Values

  • total
  • unique
  • response_time
  • resolution_time
  • handle_time
  • messages
  • visitor_messages
  • operator_messages
  • rating
aggregator
enum[string]Optional

Analytics aggregator

Values

  • average
  • moving_average
  • median
  • minimum
  • maximum
  • sum
split_by
stringOptional

Split by key

filter
objectOptional

Filter options (generic, based on metric value)

date
objectRequired

Date parameters

from
stringRequired

Date from range (ISO 8601)

to
stringRequired

Date to range (ISO 8601)

split
enum[string]Required

Date split

Values

  • from
  • to
  • split
  • timezone
timezone
stringRequired

Date timezone (eg. Europe/Paris)

days
objectOptional

Date days

monday
objectOptional

Monday hour range

hour_from
stringRequired

Hour from range (eg. 11:30)

hour_to
stringRequired

Hour to range (eg. 14:00)

tuesday
objectOptional

Tuesday hour range

hour_from
stringRequired

Hour from range (eg. 11:30)

hour_to
stringRequired

Hour to range (eg. 14:00)

wednesday
objectOptional

Wednesday hour range

hour_from
stringRequired

Hour from range (eg. 11:30)

hour_to
stringRequired

Hour to range (eg. 14:00)

thursday
objectOptional

Thursday hour range

hour_from
stringRequired

Hour from range (eg. 11:30)

hour_to
stringRequired

Hour to range (eg. 14:00)

friday
objectOptional

Friday hour range

hour_from
stringRequired

Hour from range (eg. 11:30)

hour_to
stringRequired

Hour to range (eg. 14:00)

saturday
objectOptional

Saturday hour range

hour_from
stringRequired

Hour from range (eg. 11:30)

hour_to
stringRequired

Hour to range (eg. 14:00)

sunday
objectOptional

Sunday hour range

hour_from
stringRequired

Hour from range (eg. 11:30)

hour_to
stringRequired

Hour to range (eg. 14:00)

raw_export
booleanOptional

Whether to export data in raw format

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

Batchin Website

Batch Resolve Items

PATCH
/v1/website/{website_id}/batch/resolve

Resolves given (or all) items in website (conversations).

Request Body
inbox_id
stringOptional

Inbox identifier to resolve conversations for (or none)

sessions
array[string]Optional

List of session identifiers to resolve conversation for (if empty, resolve all)

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

Batch Read Items

PATCH
/v1/website/{website_id}/batch/read

Marks given (or all) items as read in website (conversations).

Request Body
inbox_id
stringOptional

Inbox identifier to resolve conversations for (or none)

sessions
array[string]Optional

List of session identifiers to read conversation for (if empty, read all)

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

Batch Remove Items

PATCH
/v1/website/{website_id}/batch/remove

Removes given items in website (conversations or people).

Request Body
inbox_id
stringOptional

Inbox identifier to resolve conversations for (or none)

sessions
array[string]Optional

List of session identifiers to remove conversation for

people
objectOptional

People removal aggregator

profiles
array[string]Optional

List of people identifiers to remove profile for

search
objectOptional

Search aggregator for profile removal

filter
array[object]Required

Search filter

model
enum[string]Required

Filter model

Values

  • people
criterion
stringRequired

Filter criterion (in model)

operator
enum[string]Required

Filter operator

Values

  • eq
  • neq
  • ex
  • nex
  • has
  • nhas
  • sw
  • ew
  • gte
  • lte
  • gt
  • lt
query
array[string]Required

Filter query terms

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

Settingsin Website

Get Website Settings

GET
/v1/website/{website_id}/settings

Resolves the current settings for a website.

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)

audit
object

Website auditing settings

log
boolean

Whether audit log is enabled or not

contact
object

Website contact information

email
string

Contact email (can be blank)

phone
string

Contact phone number (can be blank)

messenger
string

Contact handle on Messenger (can be blank)

telegram
string

Contact handle on Telegram (can be blank)

twitter
string

Contact handle on Twitter (can be blank)

whatsapp
string

Contact number on WhatsApp (can be blank)

instagram
string

Contact handle on Instagram (can be blank)

inbox
object

Inbox settings

lock_removal
boolean

Whether to prevent non-owner operators to remove data or not

force_operator_token
boolean

Whether to force operators to use Two Factor Authentication or not

emails
object

Emails settings

rating
boolean

Whether to ask users to rate support or not

transcript
boolean

Whether to notify users of transcript records for conversation or not

enrich
boolean

Whether to enable profile enrichment based on email or not

junk_filter
boolean

Whether to enable the junk filter or not

chatbox
object

Chatbox settings

tile
enum[string]

Which tile to use for messages view background in chatbox (set to blank value for none)

Values

  • default
  • shapes
  • 4-point-stars
  • anchors-away
  • autumn
  • aztec
  • bamboo
  • bank-note
  • bathroom-floor
  • bevel-circle
  • boxes
  • brick-wall
  • bubbles
  • cage
  • charlie-brown
  • church-on-sunday
  • circles-and-squares
  • circuit-board
  • connections
  • cork-screw
  • current
  • curtain
  • death-star
  • diagonal-lines
  • diagonal-stripes
  • dominos
  • endless-clouds
  • eyes
  • falling-triangles
  • fancy-rectangles
  • flipped-diamonds
  • floating-cogs
  • floor-tile
  • glamorous
  • graph-paper
  • groovy
  • happy-intersection
  • heavy-rain
  • hexagons
  • hideout
  • houndstooth
  • i-like-food
  • intersecting-circles
  • kiwi
  • leaf
  • line-in-motion
  • lips
  • lisbon
  • melt
  • moroccan
  • morphing-diamonds
  • overlapping-circles
  • overlapping-diamonds
  • overlapping-hexagons
  • parkay-floor
  • piano-man
  • pie-factory
  • pixel-dots
  • plus
  • polka-dots
  • rails
  • rain
  • random-shapes
  • rounded-plus-connected
  • signal
  • skulls
  • slanted-stars
  • squares-in-squares
  • squares
  • stamp-collection
  • steel-beams
  • stripes
  • temple
  • tic-tac-toe
  • tiny-checkers
  • volcano-lamp
  • wallpaper
  • wiggle
  • x-equals
  • yyy
  • zig-zag
wait_game
boolean

Whether to suggest user to play a wait game or not (if operators do not reply fast enough)

website_logo
boolean

Whether to show website logo in chatbox button or not

last_operator_face
boolean

Whether to show last operator face in chatbox button or not

ongoing_operator_face
boolean

Whether to show ongoing operator face in chatbox button or not

activity_metrics
boolean

Whether to show activity metrics in chatbox or not

operator_privacy
boolean

Whether to enable operator privacy options or not

availability_tooltip
boolean

Whether to show availability tooltip or not

hide_vacation
boolean

Whether to place website support in vacation or not (this hides the chatbox)

hide_on_away
boolean

Whether to hide chatbox on away or not

hide_on_mobile
boolean

Whether to hide chatbox on mobile devices or not

position_reverse
boolean

Whether reverse chatbox position or not

email_visitors
boolean

Whether to ask for visitor email or not

phone_visitors
boolean

Whether to ask for visitor phone or not

force_identify
boolean

Whether to force visitor to identify or not (requires at least email or phone ask enabled)

ignore_privacy
boolean

Whether to disable privacy filters and ignore user choices (eg. user Do Not Track value)

visitor_compose
boolean

Whether to show visitor compose preview or not (MagicType from visitor)

file_transfer
boolean

Whether to show the file upload tools in chatbox

overlay_search
boolean

Whether to show a button to search in all support resources via Crisp Overlay

overlay_mode
boolean

Whether to restrict the chatbox to show search via Crisp Overlay before the user can contact support

helpdesk_link
boolean

Whether to show a link to helpdesk in chatbox (if helpdesk is configured)

helpdesk_only
boolean

Whether to restrict the chatbox to show the helpdesk view only, and disable chat (if helpdesk is configured)

status_health_dead
boolean

Whether to show status banner, when status page reports as dead (if Status Page plugin is used)

check_domain
boolean

Whether to check website domain before creating sessions or not

color_theme
enum[string]

Which color theme to use

Values

  • default
  • amber
  • black
  • blue
  • blue_grey
  • light_blue
  • brown
  • cyan
  • green
  • light_green
  • grey
  • indigo
  • orange
  • deep_orange
  • pink
  • purple
  • deep_purple
  • red
  • teal
text_theme
enum[string]

Which text theme to use

Values

  • default
  • 1
  • 2
  • 3
  • 4
welcome_message
enum[string]

Which welcome message to display on chatbox open

Values

  • default
  • 1
  • 2
  • 3
  • 4
  • 5
locale
string

Which locale to enforce (can be blank for auto-detect, ISO 639-1)

allowed_pages
array[string]

Allowed pages (chatbox is visible only for those page URLs)

blocked_pages
array[string]

Blocked pages (chatbox is hidden for those page URLs)

blocked_countries
array[string]

Blocked countries (chatbox is hidden for those countries)

blocked_locales
array[string]

Blocked locales (chatbox is hidden for those locales, ISO 639-1)

blocked_ips
array[string]

Blocked IP addresses (chatbox is hidden for those IPs: IPv4 or IPv6, CIDR)

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

Update Website Settings

PATCH
/v1/website/{website_id}/settings

Updates the current settings for a website.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
name
stringOptional

Website name

domain
stringOptional

Website domain

logo
stringOptional

Website custom logo image URL (can be blank)

audit
objectOptional

Website auditing settings

log
booleanOptional

Whether audit log is enabled or not

contact
objectOptional

Website contact information

email
stringOptional

Contact email (can be blank)

phone
stringOptional

Contact phone number (can be blank)

messenger
stringOptional

Contact handle on Messenger (can be blank)

telegram
stringOptional

Contact handle on Telegram (can be blank)

twitter
stringOptional

Contact handle on Twitter (can be blank)

whatsapp
stringOptional

Contact number on WhatsApp (can be blank)

instagram
stringOptional

Contact handle on Instagram (can be blank)

inbox
objectOptional

Inbox settings

lock_removal
booleanOptional

Whether to prevent non-owner operators to remove data or not

force_operator_token
booleanOptional

Whether to force operators to use Two Factor Authentication or not

emails
objectOptional

Emails settings

rating
booleanOptional

Whether to ask users to rate support or not

transcript
booleanOptional

Whether to notify users of transcript records for conversation or not

enrich
booleanOptional

Whether to enable profile enrichment based on email or not

junk_filter
booleanOptional

Whether to enable the junk filter or not

chatbox
objectOptional

Chatbox settings

tile
enum[string]Optional

Which tile to use for messages view background in chatbox (set to blank value for none)

Values

  • default
  • shapes
  • 4-point-stars
  • anchors-away
  • autumn
  • aztec
  • bamboo
  • bank-note
  • bathroom-floor
  • bevel-circle
  • boxes
  • brick-wall
  • bubbles
  • cage
  • charlie-brown
  • church-on-sunday
  • circles-and-squares
  • circuit-board
  • connections
  • cork-screw
  • current
  • curtain
  • death-star
  • diagonal-lines
  • diagonal-stripes
  • dominos
  • endless-clouds
  • eyes
  • falling-triangles
  • fancy-rectangles
  • flipped-diamonds
  • floating-cogs
  • floor-tile
  • glamorous
  • graph-paper
  • groovy
  • happy-intersection
  • heavy-rain
  • hexagons
  • hideout
  • houndstooth
  • i-like-food
  • intersecting-circles
  • kiwi
  • leaf
  • line-in-motion
  • lips
  • lisbon
  • melt
  • moroccan
  • morphing-diamonds
  • overlapping-circles
  • overlapping-diamonds
  • overlapping-hexagons
  • parkay-floor
  • piano-man
  • pie-factory
  • pixel-dots
  • plus
  • polka-dots
  • rails
  • rain
  • random-shapes
  • rounded-plus-connected
  • signal
  • skulls
  • slanted-stars
  • squares-in-squares
  • squares
  • stamp-collection
  • steel-beams
  • stripes
  • temple
  • tic-tac-toe
  • tiny-checkers
  • volcano-lamp
  • wallpaper
  • wiggle
  • x-equals
  • yyy
  • zig-zag
wait_game
booleanOptional

Whether to suggest user to play a wait game or not (if operators do not reply fast enough)

website_logo
booleanOptional

Whether to show website logo in chatbox button or not

last_operator_face
booleanOptional

Whether to show last operator face in chatbox button or not

ongoing_operator_face
booleanOptional

Whether to show ongoing operator face in chatbox button or not

activity_metrics
booleanOptional

Whether to show activity metrics in chatbox or not

operator_privacy
booleanOptional

Whether to enable operator privacy options or not

availability_tooltip
booleanOptional

Whether to show availability tooltip or not

hide_vacation
booleanOptional

Whether to place website support in vacation or not (this hides the chatbox)

hide_on_away
booleanOptional

Whether to hide chatbox on away or not

hide_on_mobile
booleanOptional

Whether to hide chatbox on mobile devices or not

position_reverse
booleanOptional

Whether reverse chatbox position or not

email_visitors
booleanOptional

Whether to ask for visitor email or not

phone_visitors
booleanOptional

Whether to ask for visitor phone or not

force_identify
booleanOptional

Whether to force visitor to identify or not (requires at least email or phone ask enabled)

ignore_privacy
booleanOptional

Whether to disable privacy filters and ignore user choices (eg. user Do Not Track value)

visitor_compose
booleanOptional

Whether to show visitor compose preview or not (MagicType from visitor)

file_transfer
booleanOptional

Whether to show the file upload tools in chatbox

overlay_search
booleanOptional

Whether to show a button to search in all support resources via Crisp Overlay

overlay_mode
booleanOptional

Whether to restrict the chatbox to show search via Crisp Overlay before the user can contact support

helpdesk_link
booleanOptional

Whether to show a link to helpdesk in chatbox (if helpdesk is configured)

helpdesk_only
booleanOptional

Whether to restrict the chatbox to show the helpdesk view only, and disable chat (if helpdesk is configured)

status_health_dead
booleanOptional

Whether to show status banner, when status page reports as dead (if Status Page plugin is used)

check_domain
booleanOptional

Whether to check website domain before creating sessions or not

color_theme
enum[string]Optional

Which color theme to use

Values

  • default
  • amber
  • black
  • blue
  • blue_grey
  • light_blue
  • brown
  • cyan
  • green
  • light_green
  • grey
  • indigo
  • orange
  • deep_orange
  • pink
  • purple
  • deep_purple
  • red
  • teal
text_theme
enum[string]Optional

Which text theme to use

Values

  • default
  • 1
  • 2
  • 3
  • 4
welcome_message
enum[string]Optional

Which welcome message to display on chatbox open

Values

  • default
  • 1
  • 2
  • 3
  • 4
  • 5
locale
stringOptional

Which locale to enforce (can be blank for auto-detect, ISO 639-1)

allowed_pages
array[string]Optional

Allowed pages (chatbox is visible only for those page URLs)

blocked_pages
array[string]Optional

Blocked pages (chatbox is hidden for those page URLs)

blocked_countries
array[string]Optional

Blocked countries (chatbox is hidden for those countries)

blocked_locales
array[string]Optional

Blocked locales (chatbox is hidden for those locales, ISO 639-1)

blocked_ips
array[string]

Blocked IP addresses (chatbox is hidden for those IPs: IPv4 or IPv6, CIDR)

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

Verifyin Website

Get Verify Settings

GET
/v1/website/{website_id}/verify/settings

Resolves verify settings.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
enabled
boolean

Whether user verification is enabled or not

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

Update Verify Settings

PATCH
/v1/website/{website_id}/verify/settings

Updates verify settings.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
enabled
booleanRequired

Whether user verification is enabled or not

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

Get Verify Key

GET
/v1/website/{website_id}/verify/key

Resolves verify key. This key is to be used in the user backend to sign user data (eg. email) with an HMAC-SHA256 function.

URI Parameters
website_id
stringRequired

The website identifier

Response Data
error
boolean
reason
string
data
object
secret
string

Secret verify key (if any)

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

Roll Verify Key

POST
/v1/website/{website_id}/verify/key

Rolls verify key. This requests a new keypair to be generated. Previous key will be invalidated.

URI Parameters
website_id
stringRequired

The website identifier

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

Subscriptionin Plugin

List All Active Subscriptions

GET
/v1/plugins/subscription

Lists all active plugin subscriptions on all websites, linked to payment methods owned by the user, or from websites the user is member of.

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

Plugin identifier

urn
string

Plugin Uniform Resource Name

type
enum[string]

Plugin type

Values

  • internal
  • external
name
string

Plugin name

category
enum[string]

Plugin category

Values

  • feature
  • automation
  • cms
  • crm
  • marketing
  • messaging
  • teamwork
  • other
summary
string

Plugin summary

price
number

Plugin price (in platform-wide currency)

plans
array[object]

Plans the plugin is included in (if part of a plan)

id
string

Plan identifier

name
string

Plan name

price
number

Plan price (in platform-wide currency)

icon
string

Plugin icon URL (if any)

website_url
string

Website for the plugin (if any)

contact_url
string

Contact address for the plugin (if any)

terms_url
string

Terms of use for the plugin (if any)

privacy_url
string

Privacy policy for the plugin (if any)

help_url
string

Help article for the plugin (if any)

video_url
string

Explanatory video for the plugin (if any)

configurable
boolean

Whether the plugin can be configured or not

since
string

Datetime since when the plugin is available

active
boolean

Whether the plugin is active, or has been disabled (eg: due to failed renewal payment)

website_id
string

Website identifier on which plugin is active

card_id
string

Card identifier which is used to pay the plugin subscription

  • GEThttps://api.crisp.chat/v1/plugins/subscription
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

List Subscriptions For A Website

GET
/v1/plugins/subscription/{website_id}

Lists plugin subscriptions for given website.

URI Parameters
website_id
stringRequired

The website identifier

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

Plugin identifier

urn
string

Plugin Uniform Resource Name

type
enum[string]

Plugin type

Values

  • internal
  • external
name
string

Plugin name

category
enum[string]

Plugin category

Values

  • feature
  • automation
  • cms
  • crm
  • marketing
  • messaging
  • teamwork
  • other
summary
string

Plugin summary

price
number

Plugin price (in platform-wide currency)

plans
array[object]

Plans the plugin is included in (if part of a plan)

id
string

Plan identifier

name
string

Plan name

price
number

Plan price (in platform-wide currency)

icon
string

Plugin icon URL (if any)

website_url
string

Website for the plugin (if any)

contact_url
string

Contact address for the plugin (if any)

terms_url
string

Terms of use for the plugin (if any)

privacy_url
string

Privacy policy for the plugin (if any)

help_url
string

Help article for the plugin (if any)

video_url
string

Explanatory video for the plugin (if any)

configurable
boolean

Whether the plugin can be configured or not

since
string

Datetime since when the plugin is available

active
boolean

Whether the plugin is active, or has been disabled (eg: due to failed renewal payment)

website_id
string

Website identifier on which plugin is active

  • GEThttps://api.crisp.chat/v1/plugins/subscription/website_id
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)

Get Subscription Details

GET
/v1/plugins/subscription/{website_id}/{plugin_id}

Resolves details on a given subscription.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

Response Data
error
boolean
reason
string
data
object
id
string

Plugin identifier

urn
string

Plugin Uniform Resource Name

type
enum[string]

Plugin type

Values

  • internal
  • external
name
string

Plugin name

category
enum[string]

Plugin category

Values

  • feature
  • automation
  • cms
  • crm
  • marketing
  • messaging
  • teamwork
  • other
summary
string

Plugin summary

price
number

Plugin price (in platform-wide currency)

plans
array[object]

Plans the plugin is included in (if part of a plan)

id
string

Plan identifier

name
string

Plan name

price
number

Plan price (in platform-wide currency)

icon
string

Plugin icon URL (if any)

website_url
string

Website for the plugin (if any)

contact_url
string

Contact address for the plugin (if any)

terms_url
string

Terms of use for the plugin (if any)

privacy_url
string

Privacy policy for the plugin (if any)

help_url
string

Help article for the plugin (if any)

video_url
string

Explanatory video for the plugin (if any)

configurable
boolean

Whether the plugin can be configured or not

since
string

Datetime since when the plugin is available

active
boolean

Whether the plugin is active, or has been disabled (eg: due to failed renewal payment)

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

Subscribe Website To Plugin

POST
/v1/plugins/subscription/{website_id}

Subscribes a given website to a given plugin.

URI Parameters
website_id
stringRequired

The website identifier

Request Body
plugin_id
stringRequired

Plugin identifier to subscribe to

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

Unsubscribe Plugin From Website

DELETE
/v1/plugins/subscription/{website_id}/{plugin_id}

Unsubscribes a given plugin from a given website.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

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

Get Subscription Settings

GET
/v1/plugins/subscription/{website_id}/{plugin_id}/settings

Resolves plugin subscription settings. Used to read plugin configuration on a given website.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

Response Data
error
boolean
reason
string
data
object
plugin_id
string

Plugin identifier

website_id
string

Website identifier

token
string

Subscription secret token (used to authenticate against external configuration forms)

schema
object

Configuration schema (JSONSchema)

settings
object

Active configuration for subscription (format enforced by configuration schema)

settings_form_url
string

URL to external configuration form page (if any)

callback_url
string

URL to plugin authentication callback (if any)

  • GEThttps://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id/settings
  • Tiersuserplugin
HTTP
Request
(loading)
Response
(loading)

Save Subscription Settings

PUT
/v1/plugins/subscription/{website_id}/{plugin_id}/settings

Saves plugin subscription settings (overwrites existing settings). Used to configure a given plugin on a given website.

Submit a raw JSON object containing the bare settings object. The object format is plugin-specific, and is enforced by the configuration schema.

The settings save acknowledgement is sent back asynchronously on the RTM Events channel, using the event namespace plugin:settings:saved.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

  • PUThttps://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id/settings
  • Tiersuserplugin
HTTP
Request
(loading)
Response
(loading)

Update Subscription Settings

PATCH
/v1/plugins/subscription/{website_id}/{plugin_id}/settings

Updates plugin subscription settings (merges with existing settings). Used to configure a given plugin on a given website.

Submit a raw JSON object containing the bare settings object. The object format is plugin-specific, and is enforced by the configuration schema.

The settings save acknowledgement is sent back asynchronously on the RTM Events channel, using the event namespace plugin:settings:saved.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

  • PATCHhttps://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id/settings
  • Tiersuserplugin
HTTP
Request
(loading)
Response
(loading)

Get Plugin Usage Bills

GET
/v1/plugins/subscription/{website_id}/{plugin_id}/bill/usage

Acquires all non-settled (ie. open) usage bills for a subscribed plugin.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

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

Name of the billable item

units
number

Total units consumed

price
number

Price to charge per unit

  • GEThttps://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id/bill/usage
  • Tiersuserplugin
  • Scopesplugin:subscription:bill
HTTP
Request
(loading)
Response
(loading)

Report Plugin Usage To Bill

POST
/v1/plugins/subscription/{website_id}/{plugin_id}/bill/usage

Reports a billable usage for a website using a subscribed plugin. This billable usage will be invoiced to the user whenever they get charged for other Crisp subscriptions.

Note that once a bill is settled (ie. paid), reporting a new billable usage for a website will open up a new bill. The price per unit will be frozen on this new bill, meaning that you cannot change the price of an existing non-settled bill, only increment its units. If you need to change the price per unit, you will need to wait until the bill gets settled, and then open up a new bill with the new price.
URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

Request Body
name
stringRequired

Name of the billable item (eg. product name which will appear on user invoices)

units
numberRequired

Units consumed to add to the current bill (eg. 250 paid messages sent)

price
numberRequired

Price to charge per unit (eg. 0.10; only used when bill is created)

  • POSThttps://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id/bill/usage
  • Tiersplugin
  • Scopesplugin:subscription:bill
HTTP
Request
(loading)
Response
(loading)

Forward Plugin Payload To Channel

POST
/v1/plugins/subscription/{website_id}/{plugin_id}/channel

Forwards generic payload given generic namespace to plugin channel.

The generic payload is sent back asynchronously on the RTM Events channel, using the event namespace plugin:channel.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

Request Body
namespace
stringRequired

Generic namespace to forward

identifier
stringOptional

Tracking identifier associated with payload (if any)

payload
objectRequired

Generic payload to forward

  • POSThttps://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id/channel
  • Tiersuserplugin
HTTP
Request
(loading)
Response
(loading)

Dispatch Plugin Event

POST
/v1/plugins/subscription/{website_id}/{plugin_id}/event

Dispatches a generic data event for plugin, for use with Web Hooks.

The generic data is sent back asynchronously on the RTM Events channel, using the event namespace plugin:event.

URI Parameters
website_id
stringRequired

The website identifier

plugin_id
stringRequired

The plugin identifier

Request Body
name
stringRequired

Generic name to dispatch

data
objectRequired

Generic data to dispatch

  • POSThttps://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id/event
  • Tiersuserplugin
HTTP
Request
(loading)
Response
(loading)

Connect Accountin Plugin

⭐ Get Connect Account

GET
/v1/plugin/connect/account

Resolves the current plugin account information.

Response Data
error
boolean
reason
string
data
object
plugin_id
string

Plugin identifier

  • GEThttps://api.crisp.chat/v1/plugin/connect/account
  • Tiersplugin
HTTP
Request
(loading)
Response
(loading)

Connect Sessionin Plugin

⭐ Check Connect Session Validity

HEAD
/v1/plugin/connect/session

Checks whether the connected plugin session is valid or not.

  • HEADhttps://api.crisp.chat/v1/plugin/connect/session
  • Tiersplugin
HTTP
Request
(loading)
Response
(loading)

Connect Websitesin Plugin

⭐ List All Connect Websites

GET
/v1/plugin/connect/websites/all/{page_number}{?filter_configured}

Lists all websites linked to connected plugin.

URI Parameters
page_number
stringOptional

The page number (paging if many websites)

filter_configured
stringOptional

Restrict to configured plugins only (1 or 0)

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

Website identifier

token
string

Subscription secret token (used to authenticate against external configuration forms)

settings
object

Plugin settings for website

  • GEThttps://api.crisp.chat/v1/plugin/connect/websites/all/page_number
  • Tiersplugin
HTTP
Request
(loading)
Response
(loading)

List Connect Websites Since

GET
/v1/plugin/connect/websites/since{?date_since}{&filter_configured}

Lists the websites linked or unlinked or updated for connected plugin, since given date. This is basically a differential that allows you to either add, remove or update websites in use for the plugin.

URI Parameters
date_since
stringRequired

Date since when to proceed a differential response (ISO 8601)

filter_configured
stringOptional

Restrict to configured plugins only (1 or 0)

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

Website identifier

token
string

Subscription secret token (used to authenticate against external configuration forms)

settings
object

Plugin settings for website

difference
enum[string]

Difference action (what to do with the differential data)

Values

  • added
  • updated
  • removed
  • GEThttps://api.crisp.chat/v1/plugin/connect/websites/since
  • Tiersplugin
HTTP
Request
(loading)
Response
(loading)

Connect Endpointsin Plugin

⭐ Get Connect Endpoints

GET
/v1/plugin/connect/endpoints

Resolves the current plugin endpoints information.

Response Data
error
boolean
reason
string
data
object
socket
object

Socket endpoints

app
string

RTM API WebSocket endpoint URL

  • GEThttps://api.crisp.chat/v1/plugin/connect/endpoints
  • Tiersplugin
HTTP
Request
(loading)
Response
(loading)

URLin Bucket

Generate Bucket URL

POST
/v1/bucket/url/generate

Generates a bucket URL. The URL is signed, and lets you upload a file directly to it.

The signed bucket URL response is sent back asynchronously on the RTM Events channel, using either the event namespace bucket:url:avatar:generated, bucket:url:upload:generated, bucket:url:website:generated, bucket:url:helpdesk:generated, bucket:url:status:generated, bucket:url:campaign:generated or bucket:url:processing:generated (depending on the request namespace parameter).

Request Body
namespace
enum[string]Required

Bucket namespace

Values

  • avatar
  • upload
  • website
  • campaign
  • helpdesk
  • status
  • processing
id
stringRequired

Tracking ID, returned in asynchronous callback

file
objectRequired
name
stringRequired

File name

type
stringRequired

File MIME type

resource
objectOptional

File resource (ie. who owns the file)

type
enum[string]Required

Resource owner type

Values

  • website
  • session
  • operator
  • plugin
id
stringRequired

Resource owner identifier (for website, session, operator or plugin)

  • POSThttps://api.crisp.chat/v1/bucket/url/generate
  • Tiersuserplugin
  • Scopesbucket:url
HTTP
Request
(loading)
Response
(loading)

Animationin Media

List Animation Medias

GET
/v1/media/animation/list/{page_number}{?per_page}{?search_query}{&list_id}

Lists animation medias, given the search query and paging.

The animation media list is sent back asynchronously on the RTM Events channel, using the event namespace media:animation:listed.

URI Parameters
page_number
stringOptional

Page number for animation paging

per_page
stringOptional

Page size for animation paging (between 10 and 50, defaults to 10)

search_query
stringOptional

Search query (if not set, trending animations are listed)

list_id
stringOptional

List ID (used to stamp response payload)

Response Data
error
boolean
reason
string
data
object
  • GEThttps://api.crisp.chat/v1/media/animation/list/page_number
  • Tiersuser
HTTP
Request
(loading)
Response
(loading)