Most API resources are protected with HTTP Basic authentication. You first need to login using your Crisp credentials to generate a permanent token keypair, that allows you to authenticate against the API for all further requests.

Those authentication keys are permanent (they never expire). Though, they get flushed when the account password is changed or if you generate too many of them, for security reasons. You can consider them safe for long-term purposes.

The utility will provide you with 2 keys: identifier and key; keep those keys private!

🔴 Important: Make sure to generate your token once, and use the same token keys in all your subsequent requests to the API. Do not generate too many tokens, as we may invalidate your older tokens to make room for newer tokens.

➡️ 2. Use Your Authentication Keys

Once you have your private authentication keys, you can use them to authenticate your HTTP requests to the API. You can do so by adding an Authorization header to all your HTTP calls. The Authorization header is formatted as such: Authorization: Basic BASE64(identifier:key) (replace BASE64(identifier:key) with your Base64 string).

Format your authentication string as such: identifier:key and encode it to Base64.

You may use a tool like an online Base64 Encoder to generate your Basic auth string (paste your identifier:key string to the ASCII Plain Text input and get your encoded string in the Base64 input).

To test if subsequent requests are authenticated, try sending a request to Check Session Validity. You will get a 200 OK response if authentication is valid.

If you are authenticating a plugin to the API, include the X-Crisp-Tier header in your HTTP requests, with the value plugin. No need to send it for regular user sessions, as user is the default value.

🔴 Important: If you login 25 times (or more) since a given token was created, this token will be expired. Crisp allows at any time no more than 25 active tokens for a given account. It expires previous tokens using a sliding window.

If your client gets rate-limited, you will start receiving 429 Too Many Requests HTTP errors in response to your requests. This can be global or per-route, based on how you triggered our rate-limiting systems.

Also, be aware that GET and HEAD routes, although rate-limited, are using a cache layer which allows you to hit a route more often that you usually should without triggering the API rate limiting system (once a cached response is served). You can see the cache status of a response via the Bloom-Status HTTP header (possible values: MISS, HIT, DIRECT, OFFLINE). If you’re curious, the cache layer is powered by Bloom, an open-source Crisp project.

The REST API comes along with a RTM Events API. RTM Events are sent on a WebSocket channel that you can open alongside your REST API channel, which allows you to receive asynchronous replies and events for some of your actions via the REST API.

You may subscribe to events by opening a Socket.IO connection to the WebSocket endpoint: https://app.relay.crisp.chat/

➡️ RTM Authentication

Once the connection is opened, you need both to authenticate and tell the server which events you’re interested in. Send a Socket.IOauthentication payload, with eg. the following data:

Headers

Body

Get Messages In Conversation

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.

error (boolean)

reason (string)

data (array[object])

session_id (string) - Session identifier

website_id (string) - Website identifier

type (enum[string]) - Message type

Members

text

note

file

animation

audio

picker

field

event

from (enum[string]) - Message sender

Members

user

operator

origin (enum[string]) - Message origin

Members

chat

email

urn:*

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

Headers

Body

Update Conversation Open State

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.

Headers

Body

Request Email Transcript For Conversation

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.

to (string, required) - Target user to send the transcript to

Members

user

operator

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

Initiate 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.

Body

Send Action To An Existing Browsing Session

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

Body

Debug An Existing Browsing Session

Debugs an existing browsing session. Used by LiveDebug™ to start or stop a debug session, as well as execute remote JavaScript on the user browser.

The debug stream is sent back asynchronously on the streaming channel, using either the event namespace app:browsing:debug:started, app:browsing:debug:stopped, app:browsing:debug:executed or app:browsing:debug:stream.

Body

Assist An Existing Browsing Session

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.

action (enum[string], required) - Assist action

Members

start

stop

heartbeat

mouse

scroll

click

mouse (object, optional) - Mouse position for assist cursor in browsing session (action must be mouse)

Initiate New 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.

Body

Transmit Signaling On Ongoing Call Session

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.

Body

Pinpoint Visitors On A Map

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.

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

Headers

Body

Invite A Website 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.

List Connect Websites Since

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, remote or update websites in use for the plugin.

Headers

Body

Generate Bucket URL

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

namespace (string, required) - Bucket namespace

Members

avatar

upload

website

campaign

helpdesk

status

processing

from (string, required) - File upload from

Members

website

operator

plugin

identifier (string, required) - Identifier for website or operator (depends on from value)