Crisp Platform - API Reference

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

πŸ“ Reference revision: 07/13/2018

Prerequisites

In order to access the Crisp API, there are some things you first need to know.

Read the sections below before you start using the Crisp API.

Libraries

Crisp maintains official API wrappers in popular languages.

They are useful if you need to quickly implement common API features in your backend or frontend app.

Authentication

Most API resources are protected with HTTP Basic authentication. You first need to authenticate using your Crisp credentials: both your email and password. Upon authentication, 2 permanent keys are returned, that allow you to authenticate against the API.

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

Now that the authentication overview is covered, let’s dive into it.

➑️ 1. Generate Your Authentication Keys

Authentication keys can be generated as explained below.

πŸ”΄ Important: Be sure to login once, and re-use the same authentication keys (same identifier + key) in all your subsequent requests to the API. Do not generate new tokens from your code for every new request to the API (you will be heavily rate-limited; that will induce HTTP failures for some of your API calls).

  1. Submit a login request with your account email and password (see: Create A New Session)

  2. The API returns 2 keys: identifier and key; keep those keys private!

Use the following cURL command in your terminal to generate your private API authentication keys:

curl -H "Content-Type: application/json" -X POST -d '{"email":"YOUR_ACCOUNT_EMAIL","password":"YOUR_ACCOUNT_PASSWORD"}' https://api.crisp.chat/v1/user/session/login

You can now extract your private identifier and key from the login response.

➑️ 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.

Rate Limits

To ensure resiliency against DOS and enforce a fair-use policy, the Crisp API has a multi-level rate-limit (based on client IP and user identifier, if authenticated).

  1. Edge rate limit (a very permissive rate limit on Crisp edge load balancers; you should not hit against this limit very often)

  2. Global rate limit (a permissive, API-wide rate limit that limits the total amount of requests a given IP and user identifier can submit to the API)

  3. Per-route rate limit (a more restrictive, per-route rate limit based on user identifier if authenticated, or client IP)

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.

πŸ”€ RTM Events

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.IO authentication payload, with eg. the following data:

{
  // Replace 'identifier' + 'key' with relevant values
  // Same credentials are used for REST authentication
  "username": "identifier",
  "password": "key",

  "events": [
    // List of events to subscribe to, eg:
    "message:send",
    "message:received",
    "message:updated"
  ],

  "rooms": [
    // List of rooms (website IDs of yours) to subscribe to, eg:
    "8c842203-7ed8-4e29-a608-7cf78a7d2fcc"
  ]
}

➑️ RTM Namespaces

Available RTM event namespaces are listed below. Make sure to subscribe to the ones you need to receive in the RTM authentication request, otherwise you won’t get them.

Session Events

  • session:update_availability β€” Session availability changed (eg. online to offline)

  • session:update_verify β€” Session verification status changed

  • session:request:initiated β€” Session has been initiated (conversation started)

  • session:set_email β€” Email has been set for session

  • session:set_phone β€” Phone has been set for session

  • session:set_address β€” Address has been set for session

  • session:set_avatar β€” Avatar has been set for session

  • session:set_nickname β€” Nickname has been set for session

  • session:set_data β€” User data has been set for session

  • session:sync:pages β€” A page was just browsed by user on session

  • session:sync:events β€” A live event was just pushed from user on session

  • session:sync:capabilities β€” User device just advertised its capabilities on session (eg. browser support for calls)

  • session:sync:geolocation β€” Current geolocation was just pushed for session

  • session:sync:system β€” Current device system was just pushed for session

  • session:sync:network β€” Current device network was just pushed for session

  • session:sync:timezone β€” Current device timezone was just pushed for session

  • session:sync:locales β€” Current device locales was just pushed for session

  • session:set_state β€” Session state changed (eg. to resolved)

  • session:set_block β€” Session was just blocked or unblocked

  • session:set_segments β€” Session segments have been added

  • session:set_opened β€” Conversation has been opened by an operator (viewed by)

  • session:set_closed β€” Conversation has been closed by a viewing operator

  • session:set_mentions β€” An operator mentioned another operator

  • session:set_routing β€” A routing identifier was set on conversation

  • session:removed β€” Session has been removed

Message Events

  • message:updated β€” Message has been updated

  • message:send β€” Message has been sent (from visitor)

  • message:received β€” Message has been received (from operator)

  • message:compose:send β€” A message is being composed (MagicType from visitor)

  • message:compose:receive β€” A message is being composed (MagicType from operator)

  • message:acknowledge:read:send β€” Messages sent by visitor were read by an operator

  • message:acknowledge:read:received β€” Messages sent by operators were read by visitor

  • message:acknowledge:delivered β€” Visitor client acknowledged delivery of an operator message

  • message:notify:unread:send β€” Messages sent by visitor were not read in due time by an operator

  • message:notify:unread:received β€” Messages sent by operators were not read in due time by visitor

People Events

  • people:profile:created β€” A people profile was created

  • people:profile:removed β€” A people profile was removed

  • people:bind:session β€” A people profile was bound to session

  • people:sync:profile β€” A people profile was updated for session

  • people:import:progress β€” People batch import is progressing

  • people:import:done β€” People batch import is done

Campaign Events

  • campaign:progress β€” Campaign sending is progressing (eg. campaign is 10% sent)

  • campaign:dispatched β€” Campaign was dispatched

  • campaign:running β€” Campaign is running, sending is ongoing

Browsing Events

  • browsing:request:initiated β€” MagicBrowse request initiated by visitor browser

  • browsing:request:rejected β€” MagicBrowse request rejected by visitor browser (eg. browser has privacy settings)

Call Events

  • call:request:initiated β€” Call was initiated (accepted by user)

  • call:request:rejected β€” Call was rejected (declined by user)

Service Events

  • service:translate:processed β€” A text has been translated

Website Events

  • website:update_visitors_count β€” Website visitor counter changed (eg. a visitor came online)

  • website:update_operators_availability β€” Website operator availability changed (eg. operator went online)

  • website:users:available β€” Website availability changed (eg. support went offline)

  • website:validate:domain:valid β€” Website domain records could be validated

  • website:validate:domain:invalid β€” Website domain records could not be validated

Bucket Events

  • bucket:url:upload:generated β€” An upload URL was generated for a file upload (signed URL, usable once)

  • bucket:url:avatar:generated β€” An upload URL was generated for an avatar upload (signed URL, usable once)

  • bucket:url:website:generated β€” An upload URL was generated for a website upload (signed URL, usable once)

  • bucket:url:campaign:generated β€” An upload URL was generated for a campaign file upload (signed URL, usable once)

  • bucket:url:helpdesk:generated β€” An upload URL was generated for a helpdesk file upload (signed URL, usable once)

  • bucket:url:status:generated β€” An upload URL was generated for a status file upload (signed URL, usable once)

  • bucket:url:processing:generated β€” An upload URL was generated for a processing/import upload (signed URL, usable once)

Media Events

  • media:animation:listed β€” Requested animation/GIF list is being returned

Email Events

  • email:subscribe β€” An user subscribed or unsubscribed to emails

  • email:track:view β€” An user viewed an email

Billing Events

  • billing:link:redirect β€” The billing link is pointing user to a specific URL to continue the process

Plugin Events

  • plugin:channel β€” Generic channel for plugins

  • plugin:event β€” Generic event for plugins

  • plugin:settings:saved β€” Plugin settings saved

An example of code implementing RTM Events can be found in our Golang go-crisp-api library events.go file.

🚨 Security Reports

If you find any security hole in the Crisp API, you are more than welcome to report it directly to security@crisp.chat.

⚠️ You must encrypt your email using the following GPG public key: GPG:8AD28DC5.

πŸ‘ After we fix it, we will discuss about any bounty we can give you for the help.

🀝 Disclosures: Hely Shah, John Gracey, Haq Khokhar, Sylvain Kerkour.

Email

Manages Crisp emails.

Email Subscription

Manages email subscriptions. Used to subscribe or unsubscribe from Crisp notification emails.

GET https://api.crisp.chat/v1/email/email_hash/subscription/key?website_id=
RequestsGet Subscription Status
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "subscribed": true
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "email_not_found",
  "data": {}
}

Get Subscription Status
GET/email/{email_hash}/subscription/{key}{?website_id}

Resolves current subscription status (subscribed or unsubscribed).

  • error (boolean)

  • reason (string)

  • data (object)

    • subscribed (boolean) - Whether email is subscribed or not
URI Parameters
HideShow
email_hash
string (required) 

Email secure hash

key
string (required) 

Private security for given email

website_id
string (optional) 

Website identifier for email


PATCH https://api.crisp.chat/v1/email/email_hash/subscription/key?website_id=
RequestsUpdate Subscription
Headers
Content-Type: application/json
Body
{
  "subscribed": true
}
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "email_not_found",
  "data": {}
}

Update Subscription Status
PATCH/email/{email_hash}/subscription/{key}{?website_id}

Updates current subscription status (subscribe or unsubscribe).

  • subscribed (boolean, required) - Whether to subscribe email or not
URI Parameters
HideShow
email_hash
string (required) 

Email secure hash

key
string (required) 

Private security for given email

website_id
string (optional) 

Website identifier for email


Bucket

Manages Crisp buckets.

Bucket URL

Manages bucket URL operations. Used to handle file uploads.

POST https://api.crisp.chat/v1/bucket/url/generate
RequestsRequest Avatar Upload URL
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "namespace": "avatar",
  "from": "website",
  "identifier": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
  "id": "b1a2",
  "file": {
    "name": "Logo.jpg",
    "type": "image/jpeg"
  }
}
Responses202403404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

Generate Bucket URL
POST/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).

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

  • id (string, required) - Tracking ID, returned in asynchronous callback

  • file (object, required)

    • name (string, required) - File name
    • type (string, required) - File MIME type

Media

Manages Crisp medias.

Media Animation

Manages media animation operations. Used to look for animations.

GET https://api.crisp.chat/v1/media/animation/list/page_number?search_query=&list_id=
RequestsLists Animation Medias
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses202
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}

List Animation Medias
GET/media/animation/list/{page_number}{?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
HideShow
page_number
number (optional) 

Page number for animation paging

search_query
string (optional) 

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

list_id
number (optional) 

List ID (used to stamp response payload)


User

Manages Crisp users (operators).

User Availability

Manages user availability, as seen by the Crisp Platform.

GET https://api.crisp.chat/v1/user/availability
RequestsGet User Availability
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "type": "away",
    "time": {
      "for": null,
      "since": 1468434872510
    }
  }
}

Get User Availability
GET/user/availability

Resolves the current user availability. Useful to check if a Crisp app is currently connected to the account.

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • type (enum[string]) - Availability type
      • Members
        • online
        • away
        • offline
    • time (object)
      • for (number) - Seconds for which the availability is valid
      • since (number) - Timestamp since when the availability has been updated

PATCH https://api.crisp.chat/v1/user/availability
RequestsUpdate User Availability
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "type": "online",
  "time": {
    "for": 3600
  }
}
Responses202
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}

Update User Availability
PATCH/user/availability

Updates the advertised user availability, for a defined period of time after which to automatically expire.

  • type (enum[string], required) - Availability type

    • Members
      • online
      • away
      • offline
  • time (object, required)

    • for (number, required) - Seconds for which the availability is valid

GET https://api.crisp.chat/v1/user/availability/status
RequestsGet User Availability Status
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "status": "online"
  }
}

Get User Availability Status
GET/user/availability/status

Resolves the current user availability status. It differs from the raw user availability (the raw availability only tells if the user is connected on a Crisp app).

The availability status, however, tells whether the user is seen as online or offline by visitors (given his schedule and presence options).

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • status (enum[string]) - Availability status
      • Members
        • online
        • away
        • offline

User Account Base

Manages operator user accounts (base).

GET https://api.crisp.chat/v1/user/account
RequestsGet User Account
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b"
  }
}

Get User Account
GET/user/account

Resolves the current user account information.

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier

POST https://api.crisp.chat/v1/user/account
RequestsCreate User Account
Headers
Content-Type: application/json
Body
{
  "email": "valerian@crisp.chat",
  "password": "MySuper$ecurePassword",
  "first_name": "Valerian",
  "last_name": "Saliou",
  "signature": "aBefdsS"
}
Responses201400400400409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "created",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_email",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_password",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_signature",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "exists",
  "data": {}
}

Create User Account
POST/user/account

Creates a new Crisp user account (operator account).

  • email (string, required) - User email

  • password (string, required) - User password (at least 4 characters)

  • first_name (string, required) - User first name

  • last_name (string, required) - User last name

  • signature (string, required) - Registration unique signature

  • affiliates_id (string, optional) - Affiliates tracking identifier (if any)

  • locale (string, optional) - User locale (if any)


DELETE https://api.crisp.chat/v1/user/account
RequestsDelete User Account
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200412412
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_membership_left",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_card_left",
  "data": {}
}

Delete User Account
DELETE/user/account

Deletes user account.


User Account Billing

Manages billing information for user.

GET https://api.crisp.chat/v1/user/account/billing
RequestsList All Billing Methods
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200428
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "cards": [
      {
        "card_id": "b5be332d-bf2b-464f-9710-27a1573740f7",
        "name_on_card": "Valerian Saliou",
        "address": "42 Mission St, San Francisco, CA",
        "country": "US",
        "information": "Company name: Crisp IM SARL",
        "tax_identifier": null,
        "currency": "USD",
        "card_number_preview": "XXXX XXXX XXXX 5879",
        "card_country": "US",
        "card_provider": "mastercard",
        "expiration_date": "2018-12-01T05:00:00.000Z",
        "added_date": "2016-06-13T06:24:30.000Z",
        "is_valid": true,
        "is_expired": false,
        "linked_websites": [
          {
            "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
            "name": "Crisp",
            "domain": "crisp.chat"
          }
        ]
      }
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_customer",
  "data": {}
}

List All Billing Methods
GET/user/account/billing

Resolves the saved billing details (payment methods).

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • cards (array[object]) - Active payment methods
      • card_id (string) - Card identifier
      • name_on_card (string) - Name on card
      • address (string) - Address for cardholder
      • country (string) - Country code for cardholder
      • information (string) - Information on cardholder
      • tax_identifier (string) - Tax identification number for cardholder (eg. European VAT number)
      • currency (string) - Currency in use for billing for cardholder
      • card_number_preview (string) - Secure preview of card number (the Crisp Platform only retains this mangled number)
      • card_country (string) - Country code for card
      • card_provider (enum[string]) - Provider for card
        • Members
          • default
          • mastercard
          • visa
          • amex
          • dinersclub
          • discover
          • unionpay
          • jcb
          • visaelectron
          • maestro
          • forbrugsforeningen
          • dankort
          • paypal
      • expiration_date (string) - Date when the card expires
      • added_date (string) - Date when the card was added
      • is_valid (boolean) - Whether card is valid or not
      • is_expired (boolean) - Whether card is expired or not
      • linked_websites (array[object]) - Websites using this card as payment method
        • website_id (string) - Website identifier
        • name (string) - Name of website
        • domain (string) - Domain of website

POST https://api.crisp.chat/v1/user/account/billing
RequestsAdd Credit Card
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "name_on_card": "Valerian Saliou",
  "address": "42 Mission St, San Francisco, CA",
  "country": "US",
  "card_number": "1234567898765432",
  "security_code": "666",
  "expiration_date": {
    "month": "01",
    "year": "2017"
  }
}
Responses201400400400409428
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {
    "card_id": "b5be332d-bf2b-464f-9710-27a1573740f7"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_card_number",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_security_code",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_expiration_date",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_exists",
  "data": {
    "card_id": "b5be332d-bf2b-464f-9710-27a1573740f7"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_customer",
  "data": {}
}

Add New Billing Method
POST/user/account/billing

Adds a payment method (credit card) to the user account.

  • name_on_card (string, required) - Name on card

  • address (string, required) - Address for cardholder

  • country (string, required) - Country code for cardholder

  • information (string, optional) - Information on cardholder

  • tax_identifier (string, optional) - Tax identification number for cardholder (eg. European VAT number)

  • card_number (string, required) - Card number

  • security_code (string, required) - Card CVC

  • expiration_date (object, required) - Date when the card expires

    • month (string, required) - Month of expiration (if 1 digit, prepend it with a zero)
    • year (string, required) - Year of expiration

GET https://api.crisp.chat/v1/user/account/billing/card_id
RequestsGet A Billing Method
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404428
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "card_id": "b5be332d-bf2b-464f-9710-27a1573740f7",
    "name_on_card": "Baptiste Jamin",
    "address": "42 Mission St, San Francisco, CA",
    "country": "US",
    "information": "Company name: Crisp IM SARL",
    "tax_identifier": null,
    "currency": "USD",
    "card_number_preview": "XXXX XXXX XXXX 5879",
    "card_country": "US",
    "card_provider": "mastercard",
    "expiration_date": "2016-12-31T23:00:00.000Z",
    "added_date": "2016-07-08T10:16:02.000Z",
    "is_valid": true,
    "is_expired": false,
    "linked_websites": [
      {
        "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
        "name": "Crisp Development",
        "domain": "crisp.chat"
      }
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_customer",
  "data": {}
}

Get A Billing Method
GET/user/account/billing/{card_id}

Acquires information about a saved billing method (eg: credit card).

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • card_id (string) - Card identifier
    • name_on_card (string) - Name on card
    • address (string) - Address for cardholder
    • country (string) - Country code for cardholder
    • information (string) - Information on cardholder
    • tax_identifier (string) - Tax identification number for cardholder (eg. European VAT number)
    • currency (string) - Currency in use for billing for cardholder
    • card_number_preview (string) - Secure preview of card number (the Crisp Platform only retains this mangled number)
    • card_country (string) - Country code for card
    • card_provider (enum[string]) - Provider for card
      • Members
        • default
        • mastercard
        • visa
        • amex
        • dinersclub
        • discover
        • unionpay
        • jcb
        • visaelectron
        • maestro
        • forbrugsforeningen
        • dankort
        • paypal
    • expiration_date (string) - Date when the card expires
    • added_date (string) - Date when the card was added
    • is_valid (boolean) - Whether card is valid or not
    • is_expired (boolean) - Whether card is expired or not
    • linked_websites (array[object]) - Websites using this card as payment method
      • website_id (string) - Website identifier
      • name (string) - Name of website
      • domain (string) - Domain of website
URI Parameters
HideShow
card_id
string (required) 

The card identifier


PATCH https://api.crisp.chat/v1/user/account/billing/card_id
RequestsUpdate A Billing Method
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "address": "42 Mission St, San Francisco, CA"
}
Responses200404428
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "updated",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_customer",
  "data": {}
}

Update A Billing Method
PATCH/user/account/billing/{card_id}

Updates billing method information (eg: credit card).

  • name_on_card (string, optional) - Name on card

  • address (string, optional) - Address for cardholder

  • country (string, optional) - Country code for cardholder

  • information (string, optional) - Information on cardholder

  • tax_identifier (string, optional) - Tax identification number for cardholder (eg. European VAT number)

URI Parameters
HideShow
card_id
string (required) 

The card identifier


DELETE https://api.crisp.chat/v1/user/account/billing/card_id
RequestsRemove A Billing Method
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404428
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "removed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_customer",
  "data": {}
}

Remove A Billing Method
DELETE/user/account/billing/{card_id}

Deletes a saved billing method.

URI Parameters
HideShow
card_id
string (required) 

The card identifier


GET https://api.crisp.chat/v1/user/account/billing/card_id/invoices/page_number
RequestsList Invoices For Billing Method
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200206404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "results": [
      {
        "invoice_id": "b6d44fd2-903d-440d-b73a-a520df59ed92",
        "bill_id": "INV-58B7-16",
        "date": "2016-07-07T18:03:00.000Z",
        "payment": {
          "is_paid": false,
          "number_retries": 3
        },
        "invoice": {
          "id": "b6d44fd2-903d-440d-b73a-a520df59ed92",
          "currency": "USD",
          "due": {
            "total": 5,
            "parts": [
              {
                "id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
                "name": "Crisp",
                "domain": "crisp.chat",
                "plugins": [
                  {
                    "id": "12a1a9b5-588d-4a5f-9007-4cce1093ef3a",
                    "name": "Email Redirect",
                    "price": 5
                  }
                ]
              }
            ]
          }
        },
        "receipt": null
      }
    ],
    "paging": {
      "range": [
        1,
        1
      ],
      "per_page": 10,
      "total": 1
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "results": [
      {
        "invoice_id": "b6d44fd2-903d-440d-b73a-a520df59ed92",
        "bill_id": "INV-58B7-16",
        "date": "2016-07-07T18:03:00.000Z",
        "payment": {
          "is_paid": false,
          "number_retries": 3
        },
        "invoice": {
          "id": "b6d44fd2-903d-440d-b73a-a520df59ed92",
          "currency": "USD",
          "due": {
            "total": 5,
            "parts": [
              {
                "id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
                "name": "Crisp",
                "domain": "crisp.chat",
                "plugins": [
                  {
                    "id": "12a1a9b5-588d-4a5f-9007-4cce1093ef3a",
                    "name": "Email Redirect",
                    "price": 5
                  }
                ]
              }
            ]
          }
        },
        "receipt": null
      }
    ],
    "paging": {
      "range": [
        1,
        1
      ],
      "per_page": 10,
      "total": 5
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "no_invoice_available",
  "data": {}
}

List Invoices For Billing Method
GET/user/account/billing/{card_id}/invoices/{page_number}

Lists saved invoices for billing method.

  • error (boolean)

  • reason (string)

  • data (object)

    • results (array[object]) - List of invoices
      • invoice_id (string) - Invoice identifier (reference invoice number)
      • bill_id (string) - Bill identifier (lawful invoice number)
      • date (string) - Date at which invoice was emitted
      • payment (object)
        • is_paid (boolean) - Whether invoice is paid or not
        • number_retries (number) - Number of times payment was retried (if failed)
      • invoice (object)
        • id (string) - Invoice identifier
        • currency (string) - Invoice currency
        • due (object) - Due amount details
          • total (number) - Total due as part of this invoice (in specified currency)
          • parts (array[object]) - Contents of the invoice (per-website)
            • id (string) - Website identifier
            • name (string) - Name of the website
            • domain (string) - Domain of the website
            • plugins (array[object]) - Plugins paid for the website
              • id (string) - Plugin identifier
              • name (string) - Plugin name
              • price (number) - Plugin individual price
      • receipt (string) - Invoice payment receipt document URL (can be blank)
    • paging (object) - Paging details
      • range (array[number]) - Range of items returned
      • per_page (number) - Number of items per page
      • total (number) - Total number of items
URI Parameters
HideShow
card_id
string (required) 

The card identifier (set value to all to get all invoices)

page_number
number (optional) 

The page number (paging if many invoices)


GET https://api.crisp.chat/v1/user/account/billing/card_id/invoice/invoice_id
RequestsGet An Invoice For Billing Method
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "invoice_id": "b6d44fd2-903d-440d-b73a-a520df59ed92",
    "bill_id": "INV-58B7-16",
    "date": "2016-07-07T18:03:00.000Z",
    "payment": {
      "is_paid": false,
      "number_retries": 3
    },
    "invoice": {
      "id": "b6d44fd2-903d-440d-b73a-a520df59ed92",
      "currency": "USD",
      "due": {
        "total": 5,
        "parts": [
          {
            "id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
            "name": "Crisp",
            "domain": "crisp.chat",
            "plugins": [
              {
                "id": "12a1a9b5-588d-4a5f-9007-4cce1093ef3a",
                "name": "Email Redirect",
                "price": 5
              }
            ]
          }
        ]
      }
    },
    "receipt": null
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invoice_not_found",
  "data": {}
}

Get An Invoice For Billing Method
GET/user/account/billing/{card_id}/invoice/{invoice_id}

Gets given saved invoice for billing method.

  • error (boolean)

  • reason (string)

  • data (object)

    • invoice_id (string) - Invoice identifier (reference invoice number)
    • bill_id (string) - Bill identifier (lawful invoice number)
    • date (string) - Date at which invoice was emitted
    • payment (object)
      • is_paid (boolean) - Whether invoice is paid or not
      • number_retries (number) - Number of times payment was retried (if failed)
    • invoice (object)
      • id (string) - Invoice identifier
      • currency (string) - Invoice currency
      • due (object) - Due amount details
        • total (number) - Total due as part of this invoice (in specified currency)
        • parts (array[object]) - Contents of the invoice (per-website)
          • id (string) - Website identifier
          • name (string) - Name of the website
          • domain (string) - Domain of the website
          • plugins (array[object]) - Plugins paid for the website
            • id (string) - Plugin identifier
            • name (string) - Plugin name
            • price (number) - Plugin individual price
    • receipt (string) - Invoice payment receipt document URL (can be blank)
URI Parameters
HideShow
card_id
string (required) 

The card identifier (set value to all to get on all cards)

invoice_id
string (required) 

The invoice identifier


POST https://api.crisp.chat/v1/user/account/billing/link
RequestsLink To PayPal
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "service": "paypal"
}
Responses202
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}

Link To An External Billing Method
POST/user/account/billing/link

Links to an external billing method. Used to for services which need an external approval (eg: PayPal), and that cannot be added directly via a simple form submit.

A link to open to continue linking to the service will be dispatched to the user via the realtime socket interface (the response is asynchronous, as Crisp needs to request data to external APIs, eg: PayPal API). The response uses the event namespace billing:link:redirect

  • service (enum[string], required) - Service to be linked
    • Members
      • paypal

POST https://api.crisp.chat/v1/user/account/billing/link/card_id
RequestsFinish Card Link
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{}
Responses200404423428
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "linked",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_card_link",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_customer",
  "data": {}
}

Finish Linking External Billing Method
POST/user/account/billing/link/{card_id}

Finishes the link process to an external billing method. Used to mark the card link as valid.

This is used after the card link redirect, to validate card authorization, eg: with PayPal pre-approved payments.

URI Parameters
HideShow
card_id
string (required) 

The card identifier


DELETE https://api.crisp.chat/v1/user/account/billing/link/card_id
RequestsFinish Card Unlink
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404423428
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "unlinked",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_card_link",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_customer",
  "data": {}
}

Finish Unlinking External Billing Method
DELETE/user/account/billing/link/{card_id}

Finishes the unlink process to an external billing method. Used to cancel the link process and remove the card.

This is used after the card link redirect, to mark card authorization as rejected, eg: with PayPal pre-approved payments.

URI Parameters
HideShow
card_id
string (required) 

The card identifier


User Account Notification

Manages notification settings for user.

GET https://api.crisp.chat/v1/user/account/notification
RequestsGet Notification Settings
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "disabled": false,
    "messages_online": true,
    "messages_offline": true,
    "messages_unread": true,
    "messages_transcript": false,
    "messages_rating": true,
    "billing_invoice": false,
    "visitor_browsing": false,
    "sounds": true
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "notification_not_found",
  "data": {}
}

Get Notification Settings
GET/user/account/notification

Resolves the user notification settings.

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • disabled (boolean) - Whether notifications are disabled or not
    • messages_online (boolean) - Whether to notify of incoming messages when user is online (in-app notifications)
    • messages_offline (boolean) - Whether to notify of incoming messages when user is offline (push notifications)
    • messages_unread (boolean) - Whether to notify of unread messages for conversations (email notifications)
    • messages_transcript (boolean) - Whether to notify of transcript records for conversations (email notifications)
    • messages_rating (boolean) - Whether to notify of user ratings for conversations (email notifications)
    • billing_invoice (boolean) - Whether to notify of invoice payments (email notifications)
    • visitor_browsing (boolean) - Whether to notify of new visitors on website (push notifications)
    • sounds (boolean) - Whether to play sounds for incoming events (in-app)

PATCH https://api.crisp.chat/v1/user/account/notification
RequestsUpdate Notification Settings
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "disabled": false,
  "messages_online": true,
  "messages_offline": true,
  "messages_unread": true,
  "messages_transcript": false,
  "messages_rating": true,
  "billing_invoice": false,
  "visitor_browsing": false,
  "sounds": true
}
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "notification_not_found",
  "data": {}
}

Update Notification Settings
PATCH/user/account/notification

Updates the user notification settings.

  • disabled (boolean, optional) - Whether notifications are disabled or not

  • messages_online (boolean, optional) - Whether to notify of incoming messages when user is online (in-app notifications)

  • messages_offline (boolean, optional) - Whether to notify of incoming messages when user is offline (push notifications)

  • messages_unread (boolean, optional) - Whether to notify of unread messages for conversations (email notifications)

  • messages_transcript (boolean, optional) - Whether to notify of transcript records for conversations (email notifications)

  • messages_rating (boolean, optional) - Whether to notify of user ratings for conversations (email notifications)

  • billing_invoice (boolean, optional) - Whether to notify of invoice payments (email notifications)

  • visitor_browsing (boolean, optional) - Whether to notify of new visitors on website (push notifications)

  • sounds (boolean, optional) - Whether to play sounds for incoming events (in-app)


POST https://api.crisp.chat/v1/user/account/notification/provider
RequestsAdd Notification Provider
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "notification_id": "8285c027-1a50-48df-a70f-c8b08955fe4f"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {}
}

Add A Notification Provider
POST/user/account/notification/provider

Adds a notification provider. Used to subscribe to push notifications from Crisp for authenticated account (eg: Google Cloud Messaging, Apple Push Notification and more).

  • notification_id (string, required) - Notification identifier (key from GCM, APN or other service)

DELETE https://api.crisp.chat/v1/user/account/notification/provider/notification_id
RequestsDelete Notification Provider
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "removed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "provider_not_found",
  "data": {}
}

Delete A Notification Provider
DELETE/user/account/notification/provider/{notification_id}

Deletes a notification provider. Used to invalidate an existing notification provider (eg. a Crisp mobile app unsubscribes from notifications).

URI Parameters
HideShow
notification_id
string (required) 

The notification provider identifier


User Account Websites

Manages websites linked to user.

GET https://api.crisp.chat/v1/user/account/websites
RequestsList Websites
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "name": "Crisp",
      "domain": "crisp.chat",
      "logo": "https://storage.crisp.chat/users/avatar/website/8c842203-7ed8-4e29-a608-7cf78a7d2fcc/ed9f8379-852b-4ee6-bf72-65edb0401be9.jpg",
      "members": [
        "4e734085-ddbb-451f-bfb7-906ef9200793",
        "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b"
      ],
      "count": 0,
      "assigned": 0
    }
  ]
}

List Websites
GET/user/account/websites

Lists the websites linked to user.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • id (string) - Website identifier
    • name (string) - Website name
    • domain (string) - Website domain
    • logo (string) - Website custom logo image URL (can be blank)
    • members (array[string]) - Website operators (user identifiers)
    • count (number) - Number of unread messages for website
    • assigned (number) - Number of pending assigned messages for website

User Account Profile

Manages user profile.

GET https://api.crisp.chat/v1/user/account/profile
RequestsGet Profile
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "avatar": null,
    "email": "valerian@crisp.chat",
    "phone": null,
    "first_name": "Valerian",
    "last_name": "Saliou",
    "locale": "en"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "profile_not_found",
  "data": {}
}

Get Profile
GET/user/account/profile

Resolves user profile data.

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • avatar (string) - Custom avatar image URL (can be blank)
    • email (string) - User email
    • phone (string) - User phone number (if any)
    • first_name (string) - User first name
    • last_name (string) - User last name
    • locale (string) - User locale (ISO 639-1)

PATCH https://api.crisp.chat/v1/user/account/profile
RequestsUpdate Profile
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "first_name": "Valerian",
  "last_name": "Saliou",
  "email": "valerian@crisp.chat",
  "phone": null,
  "password": "MyNewSuperSecurePassword",
  "avatar": null,
  "locale": null
}
Responses200400404409412
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_password",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "profile_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "email_not_available",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "phone_required",
  "data": {}
}

Update Profile
PATCH/user/account/profile

Updates user profile data.

  • first_name (string, optional) - User first name

  • last_name (string, optional) - User last name

  • email (string, optional) - User email

  • phone (string, optional) - User phone number

  • password (string, optional) - User password (do not set it if you don’t need to update password)

  • avatar (string, optional) - Custom avatar image URL

  • locale (string, optional) - User locale (ISO 639-1)


User Account Token

Manages user token.

HEAD https://api.crisp.chat/v1/user/account/token
RequestsCheck Token
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Account Token Is Configured
HEAD/user/account/token

Checks if account token is configured.


PUT https://api.crisp.chat/v1/user/account/token
RequestsConfigure Token
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "secret": "EU5EGPRKJJNS6PZFKNQVQOLMMQRVOZKWIVHSMN2BNFIEYXJVMFQQ"
}
Responses200409412
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "configured",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "token_already_configured",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "phone_required",
  "data": {}
}

Configure Account Token
PUT/user/account/token

Configures account token, with the provided token secret key.

  • secret (string, required) - Secret key for token (Base32-encoded)

DELETE https://api.crisp.chat/v1/user/account/token
RequestsUnconfigure Token
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "unconfigured",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "token_not_configured",
  "data": {}
}

Unconfigure Account Token
DELETE/user/account/token

Unconfigures account token.

URI Parameters
HideShow
website_id
string (required) 

The website identifier


POST https://api.crisp.chat/v1/user/account/token/generate
RequestsGenerate Token
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{}
Responses200
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "generated",
  "data": {
    "secret": "IYZGCVCGOZ5SM33RHE7CYTS3LIYFK3R7IMQVCT2YHZXTYTTWOJJQ"
  }
}

Generate Account Token
POST/user/account/token/generate

Generates a new account token secret key, to be sent upon configuration.

  • error (boolean)

  • reason (string)

  • data (object)

    • secret (string) - Generated secret key for token (Base32-encoded)

HEAD https://api.crisp.chat/v1/user/account/token/verify
RequestsVerify Token
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200403
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Verify Account Token
HEAD/user/account/token/verify

Verifies provided token against provided secret key. This can be used in TOTP configuration flows to validate the secret key before configuring it.

URI Parameters
HideShow
token
string (required) 

The token to be verified

secret
string (required) 

The secret key to verify against


User Account Recover

Manages account recovery.

GET https://api.crisp.chat/v1/user/account/recover/recover_identifier/recover_key
RequestsGet Recovery Details
Headers
Content-Type: application/json
Responses200400404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "valid",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_recover_key",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "recover_not_found",
  "data": {}
}

Get Recovery Details
GET/user/account/recover/{recover_identifier}/{recover_key}

Gets details on a recovery keypair. Useful to check validity of recovery keypair.

  • error (boolean)

  • reason (string)

  • data (object)

URI Parameters
HideShow
recover_identifier
string (required) 

The recovery identifier

recover_key
string (required) 

The recovery key


PUT https://api.crisp.chat/v1/user/account/recover/recover_identifier/recover_key
RequestsSend Recovery Password
Headers
Content-Type: application/json
Responses200400400404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "recovered",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_recover_key",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_password",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "recover_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "profile_not_found",
  "data": {}
}

Send Recovery Password
PUT/user/account/recover/{recover_identifier}/{recover_key}

Submits new password and recover account.

  • password (string, required) - User password (at least 4 characters)
URI Parameters
HideShow
recover_identifier
string (required) 

The recovery identifier

recover_key
string (required) 

The recovery key


DELETE https://api.crisp.chat/v1/user/account/recover/recover_identifier/recover_key
RequestsDelete Recovery Keypair
Headers
Content-Type: application/json
Responses200400404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_recover_key",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "recover_not_found",
  "data": {}
}

Delete Recovery Keypair
DELETE/user/account/recover/{recover_identifier}/{recover_key}

Deletes a recovery keypair. Useful to invalidate keys if you ignore recovery and never use the keys to recover password.

URI Parameters
HideShow
recover_identifier
string (required) 

The recovery identifier

recover_key
string (required) 

The recovery key


User Account Schedule

Manages account schedule settings.

GET https://api.crisp.chat/v1/user/account/schedule
RequestsGet Schedule Settings
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "65693ca4-fb8f-4424-a779-5f65770c0ecc",
    "enabled": true,
    "presence": true,
    "stealth": false,
    "offset": -120,
    "days": {
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": true,
      "friday": true,
      "saturday": true,
      "sunday": false
    },
    "hours": [
      {
        "from": "08:30",
        "to": "12:30"
      },
      {
        "from": "14:30",
        "to": "18:30"
      }
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "schedule_not_found",
  "data": {}
}

Get Schedule Settings
GET/user/account/schedule

Gets user schedule settings. Those settings are used by Crisp to automatically schedule when user will be seen online or offline by website visitors.

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • enabled (boolean) - Whether schedule is enabled or not
    • presence (boolean) - Whether to consider user online if using an app
    • stealth (boolean) - Whether stealth mode is enabled or not (offline mode forced)
    • offset (number) - User timezone offset in seconds (UTC+2 is -120)
    • days (object) - Schedule days
      • monday (boolean) - Consider Monday on schedule
      • tuesday (boolean) - Consider Tuesday on schedule
      • wednesday (boolean) - Consider Wednesday on schedule
      • thursday (boolean) - Consider Thursday on schedule
      • friday (boolean) - Consider Friday on schedule
      • saturday (boolean) - Consider Saturday on schedule
      • sunday (boolean) - Consider Sunday on schedule
    • hours (array[object]) - Schedule hours
      • from (string) - Hour from which to consider on schedule (24:00 format)
      • to (string) - Hour up to which to consider on schedule (24:00 format)

PATCH https://api.crisp.chat/v1/user/account/schedule
RequestsUpdate Schedule Settings
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "enabled": true,
  "presence": true,
  "stealth": false,
  "offset": -120,
  "days": {
    "monday": true,
    "sunday": false
  },
  "hours": [
    {
      "from": "08:30",
      "to": "12:30"
    },
    {
      "from": "14:30",
      "to": "18:30"
    }
  ]
}
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "schedule_not_found",
  "data": {}
}

Update Schedule Settings
PATCH/user/account/schedule

Updates user schedule settings.

  • enabled (boolean, optional) - Whether schedule is enabled or not

  • presence (boolean, optional) - Whether to consider user online if using an app

  • stealth (boolean, optional) - Whether stealth mode is enabled or not (offline mode forced)

  • offset (number, optional) - User timezone offset in seconds (UTC+2 is -120)

  • days (object, optional) - Schedule days

    • monday (boolean, optional) - Consider Monday on schedule
    • tuesday (boolean, optional) - Consider Tuesday on schedule
    • wednesday (boolean, optional) - Consider Wednesday on schedule
    • thursday (boolean, optional) - Consider Thursday on schedule
    • friday (boolean, optional) - Consider Friday on schedule
    • saturday (boolean, optional) - Consider Saturday on schedule
    • sunday (boolean, optional) - Consider Sunday on schedule
  • hours (array[object], optional) - Schedule hours

    • from (string, optional) - Hour from which to consider on schedule (24:00 format)
    • to (string, optional) - Hour up to which to consider on schedule (24:00 format)

User Session

Manages API sessions.

HEAD https://api.crisp.chat/v1/user/session
RequestsCheck Session Validity
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200401
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check Session Validity
HEAD/user/session

Checks whether the user is logged in or not, and whether his session is valid or not.


POST https://api.crisp.chat/v1/user/session/login
RequestsLogin To Account
Headers
Content-Type: application/json
Body
{
  "email": "valerian@crisp.chat",
  "password": "MySuperSecurePassword"
}
Responses200401423424
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "session_created",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "identifier": "1d4f5781-5fcc-4f90-8e7a-21b5242eaad7",
    "key": "43d1717200a93337526daeb1123462a54fd018c37bd5216ddf1557b4773ee9b9"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "rejected",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "token_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "cannot_extend",
  "data": {}
}

Create A New Session
POST/user/session/login

Logins to user account and create a new session.

  • email (string, required) - User email

  • password (string, required) - User password

  • extend (enum[string], optional) - Where to extend login to (eg. send TOTP code as SMS by extending on phone)

    • Members
      • phone
  • token (string, optional) - User token (6 digits TOTP, if any required)

  • ephemeral (boolean, optional) - Whether to open an ephemeral session or not (expires after a few hours)


POST https://api.crisp.chat/v1/user/session/logout
RequestsLogout From Account
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{}
Responses200
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "session_deleted",
  "data": {}
}

Destroy A Session
POST/user/session/logout

Logouts from user account and destroys current session.


POST https://api.crisp.chat/v1/user/session/recover
RequestsAsk For Recover Email
Headers
Content-Type: application/json
Body
{
  "email": "valerian@crisp.chat"
}
Responses200404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "email_sent",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "account_not_found",
  "data": {}
}

Recover A Session
POST/user/session/recover

Recovers an user account from which we are locked out. A password recovery email is sent.

  • email (string, required) - User email

User Statistics

Manages statistics related to user.

GET https://api.crisp.chat/v1/user/stats/unread
RequestsCount Total Unread Messages
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "unread": 20,
    "assigned": 7
  }
}

Count Total Unread Messages
GET/user/stats/unread

Counts the total number of unread messages, cross-website.

  • error (boolean)

  • reason (string)

  • data (object)

    • user_id (string) - User identifier
    • unread (number) - Number of unread messages for user
    • assigned (number) - Number of pending assigned messages for user

Website

Manages Crisp websites.

Website Base

Manages websites.

HEAD https://api.crisp.chat/v1/website?domain=
RequestsCheck If Website Exists
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200404
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Website Exists
HEAD/website{?domain}

Checks if given website exists (by domain).

URI Parameters
HideShow
website_id
string (required) 

The website identifier

domain
string (required) 

The website domain to check against


POST https://api.crisp.chat/v1/website
RequestsCreate Website
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "name": "Acme, Inc.",
  "domain": "acme-inc.com"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {
    "website_id": "e2efddb0-d1ce-47fd-99f5-d3a5b69f1def"
  }
}

Create Website
POST/website

Creates a new website.

  • name (string, required) - Website name

  • domain (string, required) - Website domain


GET https://api.crisp.chat/v1/website/website_id
RequestsGet Website Information
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
    "name": "Crisp",
    "domain": "crisp.chat",
    "logo": "https://storage.crisp.chat/users/avatar/website/8c842203-7ed8-4e29-a608-7cf78a7d2fcc/b6c2948d-b061-405e-91a9-2fdf855d1cc0.png"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get A Website
GET/website/{website_id}

Resolves an existing website information.

  • 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)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


DELETE https://api.crisp.chat/v1/website/website_id
RequestsDelete A Website
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200403403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Delete A Website
DELETE/website/{website_id}

Deletes an existing website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Batch

Proceeds batch operations on website.

PATCH https://api.crisp.chat/v1/website/batch/resolve
RequestsResolve All Conversations
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{}
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Batch Resolve Items
PATCH/website/batch/resolve

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

  • sessions (array[string], optional) - List of session identifiers to resolve conversation for (if empty, resolve all)

PATCH https://api.crisp.chat/v1/website/batch/read
RequestsRead All Conversations
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{}
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "read",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Batch Read Items
PATCH/website/batch/read

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

  • sessions (array[string], optional) - List of session identifiers to read conversation for (if empty, read all)

PATCH https://api.crisp.chat/v1/website/batch/remove
RequestsRemove Given ConversationsRemove Given People
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "sessions": [
    "session_19e5240f-0a8d-461e-a661-a3123fc6eec9",
    "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881"
  ]
}
Responses200403403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "removed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "removal_not_permitted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "people": {
    "profiles": [
      "eee8759d-52db-48e5-982d-3426e3566ce0"
    ]
  }
}
Responses200403403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "removed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "removal_not_permitted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Batch Remove Items
PATCH/website/batch/remove

Removes given items in website (conversations or people).

  • sessions (array[string], optional) - List of session identifiers to remove conversation for

  • people (array[string], optional) - People removal aggregator

    • profiles (array[string], optional) - List of people identifiers to remove profile for
    • search (object, optional) - Search aggregator for profile removal
      • filter (array[object], required) - Search filter
        • model (enum[string], required) - Filter model
          • Members
            • people
        • criterion (string, required) - Filter criterion (in model)
        • operator (enum[string], required) - Filter operator
          • Members
            • eq
            • neq
            • ex
            • nex
            • has
            • nhas
            • sw
            • ew
            • gte
            • lte
            • gt
            • lt
        • query (array[string, number, boolean], required) - Filter query terms
      • operator (enum[string], required) - Search operator
        • Members
          • and
          • or

Website Billing

Manages website billing information.

GET https://api.crisp.chat/v1/website/website_id/billing
RequestsGet Website Billing
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "card_id": "b5be332d-bf2b-464f-9710-27a1573740f7",
    "name_on_card": "Valerian Saliou",
    "address": "42 Mission St, San Francisco, CA",
    "country": "US",
    "information": "Company name: Crisp IM SARL",
    "tax_identifier": null,
    "currency": "USD",
    "card_number_preview": "XXXX XXXX XXXX 5879",
    "card_country": "US",
    "card_provider": "mastercard",
    "expiration_date": "2016-12-31T23:00:00.000Z",
    "added_date": "2016-07-08T10:16:02.000Z",
    "is_valid": true,
    "is_expired": false,
    "linked_websites": [
      {
        "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
        "name": "Crisp",
        "domain": "crisp.chat"
      }
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "no_billing_card",
  "data": {}
}

Get Website Billing
GET/website/{website_id}/billing

Resolves website billing information (payment method linked to website).

  • card_id (string) - Card identifier

  • name_on_card (string) - Name on card

  • address (string) - Address for cardholder

  • country (string) - Country code for cardholder

  • information (string) - Information on cardholder

  • tax_identifier (string) - Tax identification number for cardholder (eg. European VAT number)

  • currency (string) - Currency in use for billing for cardholder

  • card_number_preview (string) - Secure preview of card number (the Crisp Platform only retains this mangled number)

  • card_country (string) - Country code for card

  • card_provider (enum[string]) - Provider for card

    • Members
      • default
      • mastercard
      • visa
      • amex
      • dinersclub
      • discover
      • unionpay
      • jcb
      • visaelectron
      • maestro
      • forbrugsforeningen
      • dankort
      • paypal
  • expiration_date (string) - Date when the card expires

  • added_date (string) - Date when the card was added

  • is_valid (boolean) - Whether card is valid or not

  • is_expired (boolean) - Whether card is expired or not

  • linked_websites (array[object]) - Websites using this card as payment method

    • website_id (string) - Website identifier
    • name (string) - Name of website
    • domain (string) - Domain of website
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/billing
RequestsLink Card to Website
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "card_id": "b5be332d-bf2b-464f-9710-27a1573740f7"
}
Responses200403403404409424424
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "linked",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_card_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "card_link_exists",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_card_invalid",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_card_expired",
  "data": {}
}

Update Website Billing
PATCH/website/{website_id}/billing

Updates website billing information (payment method linked to website).

  • card_id (string, required) - Card identifier to link to website
URI Parameters
HideShow
website_id
string (required) 

The website identifier


DELETE https://api.crisp.chat/v1/website/website_id/billing/card_id
RequestsUnlink Website Billing
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200403403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "unlinked",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "no_billing_card",
  "data": {}
}

Unlink Website Billing
DELETE/website/{website_id}/billing/{card_id}

Unlink website billing information (payment method linked to website).

URI Parameters
HideShow
website_id
string (required) 

The website identifier

card_id
string (required) 

The card identifier


Website Availability

Manages website availability operations.

GET https://api.crisp.chat/v1/website/website_id/availability/status
RequestsGet Website Availability Status
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "status": "online",
    "since": 1495877133091
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Get Website Availability Status
GET/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).

  • error (boolean)

  • reason (string)

  • data (object)

    • status (enum[string]) - Availability status
      • Members
        • online
        • away
        • offline
    • since (number) - Timestamp since when the availability has been updated
URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/availability/operators
RequestsList Availabilities
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "user_id": "a4c32c68-be91-4e29-8a05-976e93abbe3f",
      "type": "online",
      "time": {
        "for": 40,
        "since": 1479999493561
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Website Operator Availabilities
GET/website/{website_id}/availability/operators

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

  • error (boolean)

  • reason (string)

  • data (array[object])

    • user_id (string) - User identifier
    • type (enum[string]) - Availability type
      • Members
        • online
        • away
        • offline
    • time (object)
      • for (number) - Seconds for which the availability is valid
      • since (number) - Timestamp since when the availability has been updated
URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Channel

Manages website channel operations.

GET https://api.crisp.chat/v1/website/website_id/channel/email
RequestsGet Website Email
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "email": "w.f0f413d6c2d4b800@crisp.email"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Get Website Email Channel
GET/website/{website_id}/channel/email

Resolves the website email channel values. The returned values are static (they do not change), as long as you do not re-configure the email channel domain. The returned email can be used to receive email messages in the Crisp inbox.

  • error (boolean)

  • reason (string)

  • data (object)

    • email (string) - Website inbound email (if available)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/channel/email/domain
RequestsGet Website Email
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "root": "on.crisp.email",
    "basic": "valerian",
    "custom": null,
    "verified": true
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Get Website Email Channel Domain
GET/website/{website_id}/channel/email/domain

Resolves domain for website email channel.

  • error (boolean)

  • reason (string)

  • data (object)

    • root (string) - Root domain for email domain
    • 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)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/channel/email/domain
RequestsChange Email Channel Domain
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "custom": "valeriansaliou.name"
}
Responses202402403403404406409409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "domain_restricted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "domain_taken",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "root_domain_conflict",
  "data": {}
}

Request Website Email Channel Domain Change
PATCH/website/{website_id}/channel/email/domain

Requests a change in the email channel domain used to send and receive emails. 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.

  • basic (string, optional) - Basic domain (subdomain of on.crisp.email)

  • custom (string, optional) - Custom domain (fully qualified domain, can be blank)

URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/channel/email/setup?domain=
RequestsGet Website Email
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "generated",
  "data": {
    "domain": "valeriansaliou.name",
    "setup": {
      "records": [
        {
          "type": "txt",
          "query": "txt",
          "name": "valeriansaliou.name",
          "value": "crisp-website-id=04ed9a29-ccda-4f46-b2f3-b151d2d90fa7"
        },
        {
          "type": "txt",
          "query": "txt",
          "name": "valeriansaliou.name",
          "value": "v=spf1 redirect=_spf.crisp.email"
        },
        {
          "type": "cname",
          "query": "txt",
          "name": "_dmarc.valeriansaliou.name",
          "value": "_dmarc.crisp.email"
        },
        {
          "type": "cname",
          "query": "txt",
          "name": "crisp._domainkey.valeriansaliou.name",
          "value": "crisp._domainkey.crisp.email"
        },
        {
          "type": "mx",
          "query": "mx",
          "name": "valeriansaliou.name",
          "value": "1 inbound.crisp.email"
        }
      ]
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Generate Website Email Channel Setup Flow
GET/website/{website_id}/channel/email/setup{?domain}

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

  • error (boolean)

  • reason (string)

  • data (object)

    • domain (string) - Mailer domain to return setup for
    • setup (object) - Setup flow for mailer domain
      • records (array[object]) - DNS records for mailer domain
        • type (enum[string]) - DNS record type
          • Members
            • a
            • aaaa
            • cname
            • mx
            • txt
            • srv
        • query (enum[string]) - DNS query type (ie. record valid for query type)
          • Members
            • a
            • aaaa
            • cname
            • mx
            • txt
            • srv
        • name (string) - DNS record name
        • value (string) - DNS record value
URI Parameters
HideShow
website_id
string (required) 

The website identifier

domain
string (optional) 

Domain to use for setup


GET https://api.crisp.chat/v1/website/website_id/channel/email/relay
RequestsGet Email Channel Relay
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404412
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "status": "active",
    "smtp": {
      "username": null,
      "server": "smtp.acme-inc.com",
      "port": 587
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "custom_domain_not_configured",
  "data": {}
}

Get Website Email Channel Relay
GET/website/{website_id}/channel/email/relay

Resolves the website email channel relay store. If any SMTP relay is configured, the outbound emails will be routed using specified SMTP server.

This route requires a custom email channel domain to be configured.

  • error (boolean)

  • reason (string)

  • data (object)

    • status (enum[string]) - SMTP relay connection status (from last delivered email)
      • Members
        • inactive
        • active
        • failed
    • smtp (object) - SMTP relay server credentials (if any)
      • username (string) - SMTP server username (if any)
      • server (string) - SMTP server host
      • port (number) - SMTP server port
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/channel/email/relay
RequestsChange Email Channel Relay
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "smtp": {
    "username": null,
    "password": null,
    "server": "smtp.acme-inc.com",
    "port": 587
  }
}
Responses202402403403404404412
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "custom_domain_not_configured",
  "data": {}
}

Request Website Email Channel Relay Change
PATCH/website/{website_id}/channel/email/relay

Requests a change in the email channel relay store (which is used to deliver emails). The change will be propagated once the provided SMTP credentials are verified.

This route requires a custom email channel domain to be configured.

  • smtp (object, required) - SMTP relay server credentials (can be blank)
    • username (string, required) - SMTP server username (can be blank)
    • password (string, required) - SMTP server password (can be blank)
    • server (string, required) - SMTP server host
    • port (number, required) - SMTP server port
URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Contracts

Manages all website contracts.

GET https://api.crisp.chat/v1/website/website_id/contracts
RequestsList Website Contracts
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "id": "cf0beb57-d140-4de6-b0ba-eb76df8251af",
      "title": "GDPR Data Processing Agreement",
      "contract_url": "https://storage.crisp.chat/public/documents/gdpr_dpa_contract.pdf",
      "agreement_url": null,
      "description": "DPA contract for the European Union General Data Protection Regulation."
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Website Contracts
GET/website/{website_id}/contracts

Lists all contracts agreed or not for website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • id (string) - Contract identifier
    • title (string) - Contract title
    • contract_url (string) - Contract URL (baseline non-agreed contract)
    • agreement_url (string) - Contract agreement URL (agreed contract, if any)
    • description (string) - Contract description
URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Contract

Manages agreed website contract.

HEAD https://api.crisp.chat/v1/website/website_id/contract/
RequestsCheck If Agreed Contract Exists
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Agreed Website Contract Exists
HEAD/website/{website_id}/contract/

Checks if an agreed contract exists for website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/contract/
RequestsResolve Agreed Contract
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "id": "cf0beb57-d140-4de6-b0ba-eb76df8251af",
    "title": "GDPR Data Processing Agreement",
    "contract_url": "https://storage.crisp.chat/public/documents/gdpr_dpa_contract.pdf",
    "agreement_url": "https://storage.crisp.chat/users/contracts/7ed140fd-995d-4d0b-b7f5-de29876fd433/b05d2460-1aa3-4e84-9d35-2fe4222ef115.pdf",
    "description": "DPA contract for the European Union General Data Protection Regulation."
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "contract_not_agreed",
  "data": {}
}

Resolve Agreed Website Contract
GET/website/{website_id}/contract/

Resolves an agreed contract for website.

  • error (boolean)

  • reason (string)

  • data (object)

    • id (string) - Contract identifier
    • title (string) - Contract title
    • contract_url (string) - Contract URL (baseline non-agreed contract)
    • agreement_url (string) - Contract agreement URL (agreed contract, if any)
    • description (string) - Contract description
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PUT https://api.crisp.chat/v1/website/website_id/contract/
RequestsAgree To Contract
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403403404404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "contract_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "contract_already_agreed",
  "data": {}
}

Agree To Website Contract
PUT/website/{website_id}/contract/

Agrees to a contract for website.

  • agreement_url (string, required) - Contract agreement URL (agreed contract)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


DELETE https://api.crisp.chat/v1/website/website_id/contract/
RequestsDelete Agreed Contract
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "contract_not_agreed",
  "data": {}
}

Delete Agreed Website Contract
DELETE/website/{website_id}/contract/

Deletes an agreed contract for website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Operators

Manages multiple website operators.

GET https://api.crisp.chat/v1/website/website_id/operators/list
RequestsList Website Operators
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "type": "operator",
      "details": {
        "user_id": "a53c456f-286a-490c-8793-d2a651838137",
        "email": "baptiste@crisp.chat",
        "first_name": "Baptiste",
        "last_name": "Jamin",
        "role": "member",
        "availability": "away",
        "has_token": false
      }
    },
    {
      "type": "operator",
      "details": {
        "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
        "email": "valerian@crisp.chat",
        "first_name": "Valerian",
        "last_name": "Saliou",
        "role": "owner",
        "availability": "online",
        "has_token": true
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "operators_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Website Operators
GET/website/{website_id}/operators/list

Lists all operator members of website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • type (enum[string]) - Member type
      • Members
        • operator
        • invite
    • details (object) - Member details
      • 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
        • Members
          • owner
          • member
      • availability (enum[string]) - User availability
        • Members
          • online
          • away
          • offline
      • has_token (boolean) - Whether operator has Two Factor Authentication enabled or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/operators/active
RequestsList Last Active Website Operators
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "user_id": "a53c456f-286a-490c-8793-d2a651838137",
      "avatar": null,
      "nickname": "Baptiste",
      "timestamp": 1486797010264
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Last Active Website Operators
GET/website/{website_id}/operators/active

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

  • 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
URI Parameters
HideShow
website_id
string (required) 

The website identifier


DELETE https://api.crisp.chat/v1/website/website_id/operators/active
RequestsFlush Last Active Website Operators
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "flushed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Flush Last Active Website Operators
DELETE/website/{website_id}/operators/active

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

URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/operators/email
RequestsSend Email To Operators
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "recipient": "owners",
  "subject": "Plugin limits reached",
  "message": "Hi, you've reached the Slack plugin limits. Please contact our support team."
}
Responses202403404404412
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "no_recipient_found",
  "data": {}
}

Send Email To Website Operators
PATCH/website/{website_id}/operators/email

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

  • recipient (enum[string], required) - Recipient type

    • Members
      • all
      • owners
      • members
      • user
  • user_id (string, optional) - Recipient user identifier (if recipient is user)

  • subject (string, required) - Email subject

  • message (string, required) - Email message body

  • target (object, optional) - Target button

    • label (string, required) - Target button label
    • url (string, required) - Target button URL
URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Operator

Manages a single website operator.

GET https://api.crisp.chat/v1/website/website_id/operator/user_id
RequestsGet A Website Operator
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b",
    "email": "valerian@crisp.chat",
    "first_name": "Valerian",
    "last_name": "Saliou",
    "role": "owner",
    "availability": "online",
    "has_token": true
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "operator_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Get A Website Operator
GET/website/{website_id}/operator/{user_id}

Resolves a given website operator.

  • 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
      • Members
        • owner
        • member
    • availability (enum[string]) - User availability
      • Members
        • online
        • away
        • offline
    • has_token (boolean) - Whether operator has Two Factor Authentication enabled or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier

user_id
string (required) 

The user identifier for operator


POST https://api.crisp.chat/v1/website/website_id/operator
RequestsInvite Operator
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "email": "julien@crisp.chat",
  "role": "member"
}
Responses202403403404409409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "invited",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "operator_exists",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invite_exists",
  "data": {}
}

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

  • email (string, required) - Operator email

  • role (enum[string], required) - Operator role

    • Members
      • owner
      • member
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/operator/user_id
RequestsChange Operator Role
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "role": "owner"
}
Responses200403403403404404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "updated",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "last_owner",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "operator_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_owner",
  "data": {}
}

Change Operator Role
PATCH/website/{website_id}/operator/{user_id}

Changes the role of an existing operator. Useful to downgrade or upgrade an operator from/to owner role.

  • role (enum[string], required) - Operator role
    • Members
      • owner
      • member
URI Parameters
HideShow
website_id
string (required) 

The website identifier

user_id
string (required) 

The user identifier for operator


DELETE https://api.crisp.chat/v1/website/website_id/operator/user_id
RequestsUnlink Operator From Website
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200403403403403404404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "unlinked",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_self_user",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "last_owner",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "operator_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "billing_owner",
  "data": {}
}

Unlink Operator From Website
DELETE/website/{website_id}/operator/{user_id}

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

URI Parameters
HideShow
website_id
string (required) 

The website identifier

user_id
string (required) 

The user identifier for operator


Website Invite

Manages website membership invites. Used to redeem invites.

GET https://api.crisp.chat/v1/website/website_id/invite/invite_identifier/invite_key
RequestsGet Invite Details
Headers
Content-Type: application/json
Responses200400404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "valid",
  "data": {
    "email": "julien@crisp.chat",
    "role": "member"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_invite_key",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invite_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Get Invite Details
GET/website/{website_id}/invite/{invite_identifier}/{invite_key}

Gets details on a invite keypair. Useful to check validity of invite keypair.

  • error (boolean)

  • reason (string)

  • data (object)

    • email (string) - Invite email (doesn’t need to match when redeeming later)
    • role (string) - Invite role
URI Parameters
HideShow
website_id
string (required) 

The website identifier

invite_identifier
string (required) 

The invite identifier

invite_key
string (required) 

The invite key


PUT https://api.crisp.chat/v1/website/website_id/invite/invite_identifier/invite_key
RequestsRedeem Invite
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Responses200400402404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "redeemed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_invite_key",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invite_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Redeem Invite
PUT/website/{website_id}/invite/{invite_identifier}/{invite_key}

Redeems invite and join the website as operator.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

invite_identifier
string (required) 

The invite identifier

invite_key
string (required) 

The invite key


DELETE https://api.crisp.chat/v1/website/website_id/invite/invite_identifier/invite_key
RequestsDelete Invite Keypair
Headers
Content-Type: application/json
Responses200400404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_invite_key",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invite_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Delete Invite Keypair
DELETE/website/{website_id}/invite/{invite_identifier}/{invite_key}

Deletes an invite keypair. Useful to invalidate keys if you ignore invite and never use the keys to redeem invite.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

invite_identifier
string (required) 

The invite identifier

invite_key
string (required) 

The invite key


Website Rating

Manages website ratings. Used for people to rate websites.

GET https://api.crisp.chat/v1/website/website_id/rating/session/session_id
RequestsGet Session Rating
Headers
Content-Type: application/json
Responses200404404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolve",
  "data": {
    "stars": 4,
    "role": "Good support.",
    "created_at": 1482845836236
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "rating_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_rating_disabled",
  "data": {}
}

Resolve Session Rating
GET/website/{website_id}/rating/session/{session_id}

Gets a session rating for website. Used to retrieve rating details from a given session.

  • error (boolean)

  • reason (string)

  • data (object)

    • stars (number) - Number of stars for rating, from 1 to 5
    • comment (string) - Comment for rating
    • created_at (number) - Rating creation timestamp
URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The session identifier


PUT https://api.crisp.chat/v1/website/website_id/rating/session/session_id
RequestsSubmit Session Rating
Headers
Content-Type: application/json
Body
{
  "stars": 4,
  "comment": "Good support."
}
Responses201404409423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "rating_exists",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_rating_disabled",
  "data": {}
}

Submit Session Rating
PUT/website/{website_id}/rating/session/{session_id}

Submits a session rating for website. Used for session users to publish their own website rating.

  • stars (number, required) - Number of stars for rating, from 1 to 5

  • comment (string, optional) - Comment for rating

URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The session identifier


DELETE https://api.crisp.chat/v1/website/website_id/rating/session/session_id
RequestsDelete Session Rating
Headers
Content-Type: application/json
Responses200404404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "rating_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_rating_disabled",
  "data": {}
}

Delete Session Rating
DELETE/website/{website_id}/rating/session/{session_id}

Deletes a session rating for website. Used for session users to revoke their own website rating.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The session identifier


Website Routing

Manages website routing.

GET https://api.crisp.chat/v1/website/website_id/routing/settings
RequestsGet Routing Settings
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "assign": true,
    "reprocess_rules": false
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get Website Routing Settings
GET/website/{website_id}/routing/settings

Resolves the routing settings for a website.

  • error (boolean)

  • reason (string)

  • data (object)

    • assign (boolean) - Routing assign status (ie. whether to enable rules or not)
    • reprocess_rules (boolean) - Whether to reprocess rules periodically on new messages (if conversation has already an assigned operator)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/routing/settings
RequestsUpdate Website Routing
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "assign": true,
  "reprocess_rules": false
}
Responses200402403403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Update Website Routing Settings
PATCH/website/{website_id}/routing/settings

Updates the routing settings for a website.

  • assign (boolean, optional) - Routing assign status (ie. whether to enable rules or not)

  • reprocess_rules (boolean, optional) - Whether to reprocess rules periodically on new messages (if conversation has already an assigned operator)

URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/routing/rules
RequestsGet Routing Rules
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "rules": [
      {
        "name": "Chat Message",
        "conditions": [
          {
            "model": "session",
            "criterion": "segments",
            "operator": "eq",
            "query": [
              "chat"
            ]
          }
        ],
        "assign": [
          "a4c32c68-be91-4e29-8a05-976e93abbe3f"
        ]
      }
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List Website Routing Rules
GET/website/{website_id}/routing/rules

Lists the routing rules for a website.

  • error (boolean)

  • reason (string)

  • data (object)

    • rules (array[object]) - Routing rules
      • name (string) - Rule name
      • conditions (array[object]) - Routing conditions filter
        • model (enum[string]) - Filter model
          • Members
            • session
        • criterion (string) - Filter criterion (in model)
        • operator (enum[string]) - Filter operator
          • Members
            • eq
            • neq
        • query (array[string]) - Filter query terms
      • assign (array[string]) - User identifiers of operators to be assigned
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PUT https://api.crisp.chat/v1/website/website_id/routing/rules
RequestsUpdate Website Routing
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "rules": [
    {
      "name": "Chat Message",
      "conditions": [
        {
          "model": "session",
          "criterion": "segments",
          "operator": "eq",
          "query": [
            "chat"
          ]
        }
      ],
      "assign": [
        "a4c32c68-be91-4e29-8a05-976e93abbe3f"
      ]
    }
  ]
}
Responses200402403403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Save Website Routing Rules
PUT/website/{website_id}/routing/rules

Saves the routing rules for a website.

  • rules (array[object], required) - Routing rules
    • name (string, required) - Rule name
    • conditions (array[object], required) - Routing conditions filter
      • model (enum[string], required) - Filter model
        • Members
          • session
      • criterion (string, required) - Filter criterion (in model)
      • operator (enum[string], required) - Filter operator
        • Members
          • eq
          • neq
      • query (array[string], required) - Filter query terms
    • assign (array[string], required) - User identifiers of operators to be assigned
URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Settings

Manages the website settings.

GET https://api.crisp.chat/v1/website/website_id/settings
RequestsGet Website Settings
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
    "name": "Crisp",
    "domain": "crisp.chat",
    "logo": "https://storage.crisp.chat/users/avatar/website/8c842203-7ed8-4e29-a608-7cf78a7d2fcc/b6c2948d-b061-405e-91a9-2fdf855d1cc0.png",
    "contact": {
      "email": "contact@crisp.chat",
      "phone": "+33630138382",
      "messenger": null,
      "telegram": null,
      "twitter": "crisp-im"
    },
    "inbox": {
      "lock_removal": false
    },
    "emails": {
      "rating": true,
      "transcript": true,
      "enrich": true,
      "junk_filter": true
    },
    "chatbox": {
      "tile": "default",
      "wait_game": false,
      "last_operator_face": false,
      "ongoing_operator_face": true,
      "activity_metrics": true,
      "operator_privacy": false,
      "availability_tooltip": true,
      "hide_vacation": false,
      "hide_on_away": false,
      "hide_on_mobile": false,
      "position_reverse": false,
      "email_visitors": false,
      "phone_visitors": false,
      "force_identify": false,
      "ignore_privacy": false,
      "file_transfer": true,
      "helpdesk_link": true,
      "status_health_dead": true,
      "check_domain": false,
      "color_theme": "blue",
      "text_theme": "default",
      "welcome_message": "default",
      "locale": "en",
      "allowed_pages": [],
      "blocked_pages": [
        "/status/*/",
        "docs.crisp.chat/*/",
        "crisp.chat/terms/",
        "https://crisp.chat/privacy/"
      ],
      "blocked_countries": [
        "IT"
      ],
      "blocked_locales": [
        "fa",
        "he"
      ],
      "blocked_ips": [
        "8.8.8.8",
        "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
        "192.168.1.1/24"
      ]
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get Website Settings
GET/website/{website_id}/settings

Resolves the current settings for a website.

  • 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)
    • 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)
    • inbox (object) - Inbox settings
      • lock_removal (boolean) - Whether to prevent non-owner operators to remove data 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)
        • Members
          • 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)
      • 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)
      • file_transfer (boolean) - Whether to show the file upload tools in chatbox
      • helpdesk_link (boolean) - Whether to show a link to helpdesk in chatbox (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 (string) - Which color theme to use
        • Members
          • 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 (string) - Which text theme to use
        • Members
          • default
          • 1
          • 2
          • 3
          • 4
      • welcome_message (string) - Which welcome message to display on chatbox open
        • Members
          • 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)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/settings
RequestsUpdate Website Settings
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "name": "Crisp",
  "domain": "crisp.chat",
  "logo": "https://storage.crisp.chat/users/avatar/website/8c842203-7ed8-4e29-a608-7cf78a7d2fcc/b6c2948d-b061-405e-91a9-2fdf855d1cc0.png",
  "contact": {
    "email": "contact@crisp.chat",
    "phone": "+33630138382"
  },
  "inbox": {
    "lock_removal": false
  },
  "emails": {
    "rating": true,
    "transcript": true,
    "enrich": true,
    "junk_filter": true
  },
  "chatbox": {
    "tile": "default",
    "wait_game": false,
    "last_operator_face": false,
    "ongoing_operator_face": true,
    "activity_metrics": true,
    "operator_privacy": false,
    "availability_tooltip": true,
    "hide_vacation": false,
    "hide_on_away": false,
    "hide_on_mobile": false,
    "position_reverse": false,
    "email_visitors": false,
    "phone_visitors": false,
    "force_identify": false,
    "ignore_privacy": false,
    "file_transfer": true,
    "helpdesk_link": true,
    "status_health_dead": true,
    "check_domain": false,
    "color_theme": "blue",
    "text_theme": "default",
    "welcome_message": "default",
    "locale": "en",
    "allowed_pages": [],
    "blocked_pages": [
      "status/*/",
      "docs.crisp.chat/*",
      "crisp.chat/terms/",
      "https://crisp.chat/privacy/"
    ],
    "blocked_countries": [
      "IT"
    ],
    "blocked_locales": [
      "fa",
      "he"
    ],
    "blocked_ips": [
      "8.8.8.8",
      "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
      "192.168.1.1/24"
    ]
  }
}
Responses200403403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Update Website Settings
PATCH/website/{website_id}/settings

Updates the current settings for a website.

  • name (string, optional) - Website name

  • domain (string, optional) - Website domain

  • logo (string, optional) - Website custom logo image URL (can be blank)

  • contact (object, optional) - Website contact information

    • email (string, optional) - Contact email (can be blank)
    • phone (string, optional) - Contact phone number (can be blank)
    • messenger (string, optional) - Contact handle on Messenger (can be blank)
    • telegram (string, optional) - Contact handle on Telegram (can be blank)
    • twitter (string, optional) - Contact handle on Twitter (can be blank)
  • inbox (object, optional) - Inbox settings

    • lock_removal (boolean, optional) - Whether to prevent non-owner operators to remove data or not
  • emails (object, optional) - Emails settings

    • rating (boolean, optional) - Whether to ask users to rate support or not
    • transcript (boolean, optional) - Whether to notify users of transcript records for conversation or not
    • enrich (boolean, optional) - Whether to enable profile enrichment based on email or not
    • junk_filter (boolean, optional) - Whether to enable the junk filter or not
  • chatbox (object, optional) - Chatbox settings

    • tile (enum[string], optional) - Which tile to use for messages view background in chatbox (set to blank value for none)
      • Members
        • 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, optional) - Whether to suggest user to play a wait game or not (if operators do not reply fast enough)
    • last_operator_face (boolean, optional) - Whether to show last operator face in chatbox button or not
    • ongoing_operator_face (boolean, optional) - Whether to show ongoing operator face in chatbox button or not
    • activity_metrics (boolean, optional) - Whether to show activity metrics in chatbox or not
    • operator_privacy (boolean, optional) - Whether to enable operator privacy options or not
    • availability_tooltip (boolean, optional) - Whether to show availability tooltip or not
    • hide_vacation (boolean, optional) - Whether to place website support in vacation or not (this hides the chatbox)
    • hide_on_away (boolean, optional) - Whether to hide chatbox on away or not
    • hide_on_mobile (boolean, optional) - Whether to hide chatbox on mobile devices or not
    • position_reverse (boolean, optional) - Whether reverse chatbox position or not
    • email_visitors (boolean, optional) - Whether to ask for visitor email or not
    • phone_visitors (boolean, optional) - Whether to ask for visitor phone or not
    • force_identify (boolean, optional) - Whether to force visitor to identify or not (requires at least email or phone ask enabled)
    • ignore_privacy (boolean, optional) - Whether to disable privacy filters and ignore user choices (eg. user Do Not Track value)
    • file_transfer (boolean, optional) - Whether to show the file upload tools in chatbox
    • helpdesk_link (boolean, optional) - Whether to show a link to helpdesk in chatbox (if helpdesk is configured)
    • status_health_dead (boolean, optional) - Whether to show status banner, when status page reports as dead (if Status Page plugin is used)
    • check_domain (boolean, optional) - Whether to check website domain before creating sessions or not
    • color_theme (string, optional) - Which color theme to use
      • Members
        • 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 (string, optional) - Which text theme to use
      • Members
        • default
        • 1
        • 2
        • 3
        • 4
    • welcome_message (string, optional) - Which welcome message to display on chatbox open
      • Members
        • default
        • 1
        • 2
        • 3
        • 4
        • 5
    • locale (string, optional) - 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)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website States

Manages website states.

GET https://api.crisp.chat/v1/website/website_id/states
RequestsRequest Website States
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses202403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Request Website States
GET/website/{website_id}/states

Requests website states to be pushed to clients connected to realtime socket. States are both current operator message compose details and currently opened conversations (from online operators).

The state responses are sent back asynchronously on the RTM Events channel.

  • error (boolean)

  • reason (string)

  • data (object)

URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Service

Manages website services.

GET https://api.crisp.chat/v1/website/website_id/service/translate
RequestsTranslate A Text
  • Authenticated Tiers: user
Headers
Content-Type: application/json
Body
{
  "id": "aZejd12",
  "locale": {
    "from": "en",
    "to": "fr"
  },
  "text": "Hello world!"
}
Responses202402403404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

Request Translation Service
GET/website/{website_id}/service/translate

Requests a translation service (eg. translate a text message).

The translated result is sent back asynchronously on the RTM Events channel, using the event namespace service:translate:processed.

  • id (string, required) - Tracking ID, returned in asynchronous callback

  • locale (object, required) - Source and destination locales for translation

    • from (string, required) - Source locale (ISO 639-1)
    • to (string, required) - Destination locale (ISO 639-1)
  • text (string, required) - Source text to translate

URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Hooks

Manages multiple website hooks.

GET https://api.crisp.chat/v1/website/website_id/hooks/page_number
RequestsList Hooks
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "hook_id": "fcab2ba9-88f6-467a-ba90-65e1adddde5d",
      "label": "Exchanged messages",
      "target": "https://hooks.crisp.chat/messages?key=331de770",
      "status": "active",
      "events": [
        "message:send",
        "message:received"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "hook_id": "fcab2ba9-88f6-467a-ba90-65e1adddde5d",
      "label": "Exchanged messages",
      "target": "https://hooks.crisp.chat/messages?key=331de770",
      "status": "active",
      "events": [
        "message:send",
        "message:received"
      ]
    },
    {
      "hook_id": "877fe1c2-5460-43ce-8341-1527d63237c8",
      "label": "Email collector",
      "target": "https://hooks.crisp.chat/emails?key=331de770",
      "status": "failed",
      "events": [
        "session:set_email"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Hooks
GET/website/{website_id}/hooks/{page_number}

Lists hooks for website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • hook_id (string) - Hook identifier
    • label (string) - Hook label
    • target (string) - Hook target URL
    • status (enum[string]) - Hook status (from last sent event)
      • Members
        • inactive
        • active
        • failed
    • events (array[enum[string]]) - Hook event namespaces (to receive on target)
      • Members
        • message:updated
        • message:send
        • message:received
        • message:acknowledge:read:send
        • message:acknowledge:read:received
        • session:set_email
        • session:set_phone
        • session:set_address
        • session:set_data
        • session:set_avatar
        • session:set_nickname
        • session:set_state
        • session:set_block
        • session:set_segments
        • session:removed
        • session:sync:geolocation
        • session:sync:system
        • session:sync:network
        • session:sync:timezone
        • session:sync:locales
        • session:sync:events
        • people:profile:created
        • people:profile:removed
        • people:bind:session
        • people:sync:profile
        • campaign:progress
        • campaign:dispatched
        • campaign:running
        • email:subscribe
        • email:track:view
        • plugin:event
URI Parameters
HideShow
website_id
string (required) 

The website identifier

page_number
number (optional) 

Page number for hooks paging


Website Hook

Manages a single website hook.

POST https://api.crisp.chat/v1/website/website_id/hook
RequestsCreate A New Hook
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "label": "Exchanged messages",
  "target": "https://hooks.crisp.chat/messages?key=331de770",
  "events": [
    "message:send",
    "message:received"
  ]
}
Responses201403404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {
    "hook_id": "fcab2ba9-88f6-467a-ba90-65e1adddde5d"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "too_many_hooks",
  "data": {}
}

Create A New Hook
POST/website/{website_id}/hook

Creates a new hook.

  • label (string, required) - Hook label

  • target (string, required) - Hook target URL

  • events (array[enum[string]], required) - Hook event namespaces (to receive on target)

    • Members
      • message:updated
      • message:send
      • message:received
      • message:acknowledge:read:send
      • message:acknowledge:read:received
      • session:set_email
      • session:set_phone
      • session:set_address
      • session:set_data
      • session:set_avatar
      • session:set_nickname
      • session:set_state
      • session:set_block
      • session:set_segments
      • session:removed
      • session:sync:geolocation
      • session:sync:system
      • session:sync:network
      • session:sync:timezone
      • session:sync:locales
      • session:sync:events
      • people:profile:created
      • people:profile:removed
      • people:bind:session
      • people:sync:profile
      • campaign:progress
      • campaign:dispatched
      • campaign:running
      • email:subscribe
      • email:track:view
      • plugin:event
URI Parameters
HideShow
website_id
string (required) 

The website identifier


HEAD https://api.crisp.chat/v1/website/website_id/hook/hook_id
RequestsCheck If Hook Exists
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Hook Exists
HEAD/website/{website_id}/hook/{hook_id}

Checks if given hook exists.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

hook_id
string (required) 

The hook identifier


GET https://api.crisp.chat/v1/website/website_id/hook/hook_id
RequestsGet A Hook
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "hook_id": "fcab2ba9-88f6-467a-ba90-65e1adddde5d",
    "label": "Exchanged messages",
    "target": "https://hooks.crisp.chat/messages?key=331de770",
    "status": "active",
    "events": [
      "message:send",
      "message:received"
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "hook_not_found",
  "data": {}
}

Get A Hook
GET/website/{website_id}/hook/{hook_id}

Resolves hook information.

  • error (boolean)

  • reason (string)

  • data (object)

    • hook_id (string) - Hook identifier
    • label (string) - Hook label
    • target (string) - Hook target URL
    • status (enum[string]) - Hook status (from last sent event)
      • Members
        • inactive
        • active
        • failed
    • events (array[enum[string]]) - Hook event namespaces (to receive on target)
      • Members
        • message:updated
        • message:send
        • message:received
        • message:acknowledge:read:send
        • message:acknowledge:read:received
        • session:set_email
        • session:set_phone
        • session:set_address
        • session:set_data
        • session:set_avatar
        • session:set_nickname
        • session:set_state
        • session:set_block
        • session:set_segments
        • session:removed
        • session:sync:geolocation
        • session:sync:system
        • session:sync:network
        • session:sync:timezone
        • session:sync:locales
        • session:sync:events
        • people:profile:created
        • people:profile:removed
        • people:bind:session
        • people:sync:profile
        • campaign:progress
        • campaign:dispatched
        • campaign:running
        • email:subscribe
        • email:track:view
        • plugin:event
URI Parameters
HideShow
website_id
string (required) 

The website identifier

hook_id
string (required) 

The hook identifier


PUT https://api.crisp.chat/v1/website/website_id/hook/hook_id
RequestsSave A Hook
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "label": "Exchanged messages",
  "target": "https://hooks.crisp.chat/messages?key=331de770",
  "events": [
    "message:send",
    "message:received"
  ]
}
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "hook_not_found",
  "data": {}
}

Save A Hook
PUT/website/{website_id}/hook/{hook_id}

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

  • label (string, required) - Hook label

  • target (string, required) - Hook target URL

  • events (array[enum[string]], required) - Hook event namespaces (to receive on target)

    • Members
      • message:updated
      • message:send
      • message:received
      • message:acknowledge:read:send
      • message:acknowledge:read:received
      • session:set_email
      • session:set_phone
      • session:set_address
      • session:set_data
      • session:set_avatar
      • session:set_nickname
      • session:set_state
      • session:set_block
      • session:set_segments
      • session:removed
      • session:sync:geolocation
      • session:sync:system
      • session:sync:network
      • session:sync:timezone
      • session:sync:locales
      • session:sync:events
      • people:profile:created
      • people:profile:removed
      • people:bind:session
      • people:sync:profile
      • campaign:progress
      • campaign:dispatched
      • campaign:running
      • email:subscribe
      • email:track:view
      • plugin:event
URI Parameters
HideShow
website_id
string (required) 

The website identifier

hook_id
string (required) 

The hook identifier


PATCH https://api.crisp.chat/v1/website/website_id/hook/hook_id
RequestsUpdate A Hook
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "label": "Exchanged messages"
}
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "updated",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "hook_not_found",
  "data": {}
}

Update A Hook
PATCH/website/{website_id}/hook/{hook_id}

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

  • label (string, optional) - Hook label

  • target (string, optional) - Hook target URL

  • events (array[enum[string]], optional) - Hook event namespaces (to receive on target)

    • Members
      • message:updated
      • message:send
      • message:received
      • message:acknowledge:read:send
      • message:acknowledge:read:received
      • session:set_email
      • session:set_phone
      • session:set_address
      • session:set_data
      • session:set_avatar
      • session:set_nickname
      • session:set_state
      • session:set_block
      • session:set_segments
      • session:removed
      • session:sync:geolocation
      • session:sync:system
      • session:sync:network
      • session:sync:timezone
      • session:sync:locales
      • session:sync:events
      • people:profile:created
      • people:profile:removed
      • people:bind:session
      • people:sync:profile
      • campaign:progress
      • campaign:dispatched
      • campaign:running
      • email:subscribe
      • email:track:view
      • plugin:event
URI Parameters
HideShow
website_id
string (required) 

The website identifier

hook_id
string (required) 

The hook identifier


DELETE https://api.crisp.chat/v1/website/website_id/hook/hook_id
RequestsRemove A Hook
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "hook_not_found",
  "data": {}
}

Remove A Hook
DELETE/website/{website_id}/hook/{hook_id}

Removes a hook in website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

hook_id
string (required) 

The hook identifier


Website Verify

Manages a single website verify status.

GET https://api.crisp.chat/v1/website/website_id/verify/settings
RequestsGet Verify Settings
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "enabled": true
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Get Verify Settings
GET/website/{website_id}/verify/settings

Resolves verify settings.

  • error (boolean)

  • reason (string)

  • data (object)

    • enabled (boolean) - Whether user verification is enabled or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/verify/settings
RequestsUpdate Verify Settings
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "enabled": true
}
Responses200201402403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "initialized",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Update Verify Settings
PATCH/website/{website_id}/verify/settings

Updates verify settings.

  • enabled (boolean, required) - Whether user verification is enabled or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/verify/key
RequestsGet Verify Key
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "secret": "0fd72e0ff53b274293029fd1f3f40c92"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "verify_disabled",
  "data": {}
}

Get Verify Key
GET/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.

  • error (boolean)

  • reason (string)

  • data (object)

    • secret (string) - Secret verify key (if any)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


POST https://api.crisp.chat/v1/website/website_id/verify/key
RequestsRoll Verify Key
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{}
Responses202402403404423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "requested",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "verify_disabled",
  "data": {}
}

Roll Verify Key
POST/website/{website_id}/verify/key

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

URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Shortcuts

Manages multiple website shortcuts.

GET https://api.crisp.chat/v1/website/website_id/shortcuts/list/page_number?search_query=&search_tag=
RequestsList Shortcuts
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "shortcut_id": "279b6290-ba14-4c09-9b53-c406914eea67",
      "bang": "!hello",
      "text": "Hello there, do you need help?",
      "tag": "greetings",
      "disabled": false
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "shortcut_id": "279b6290-ba14-4c09-9b53-c406914eea67",
      "bang": "!hello",
      "text": "Hello there, do you need help?",
      "tag": "greetings",
      "disabled": false
    },
    {
      "shortcut_id": "620d04b8-3848-4e29-bfd5-46c86bfba86c",
      "bang": "!ok",
      "text": "Okay, thank you :)",
      "tag": null,
      "disabled": false
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Shortcuts
GET/website/{website_id}/shortcuts/list/{page_number}{?search_query}{&search_tag}

Lists shortcuts for website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • shortcut_id (string) - Shortcut identifier
    • bang (string) - Shortcut bang
    • text (string) - Shortcut text
    • tag (string) - Shortcut tag
    • disabled (boolean) - Whether shortcut is disabled or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier

page_number
number (optional) 

Page number for shortcuts paging

search_query
string (optional) 

Search query in all shortcuts

search_tag
string (optional) 

Restrict search to tag


GET https://api.crisp.chat/v1/website/website_id/shortcuts/tags
RequestsList Tags
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    "greetings",
    "product",
    "billing"
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Shortcut Tags
GET/website/{website_id}/shortcuts/tags

Lists shortcut tags for website.

  • error (boolean)

  • reason (string)

  • data (array[string]) - Shortcut tags

URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Shortcut

Manages a single website shortcut.

POST https://api.crisp.chat/v1/website/website_id/shortcut
RequestsCreate A New Shortcut
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "bang": "!hello",
  "text": "Hello there, do you need help?",
  "tag": "greetings",
  "disabled": false
}
Responses201402403404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {
    "shortcut_id": "e73491ec-ae7d-48ae-8363-136fea2bb29b"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "shortcut_exists",
  "data": {}
}

Create A New Shortcut
POST/website/{website_id}/shortcut

Creates a new shortcut.

  • bang (string, required) - Shortcut bang

  • text (string, required) - Shortcut text

  • tag (string, optional) - Shortcut tag

  • disabled (boolean, optional) - Whether shortcut is disabled or not

URI Parameters
HideShow
website_id
string (required) 

The website identifier


HEAD https://api.crisp.chat/v1/website/website_id/shortcut/shortcut_id
RequestsCheck If Shortcut Exists
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Shortcut Exists
HEAD/website/{website_id}/shortcut/{shortcut_id}

Checks if given shortcut exists.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

shortcut_id
string (required) 

The shortcut identifier


GET https://api.crisp.chat/v1/website/website_id/shortcut/shortcut_id
RequestsGet A Shortcut
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "shortcut_id": "279b6290-ba14-4c09-9b53-c406914eea67",
    "bang": "!hello",
    "text": "Hello there, do you need help?",
    "tag": "greetings",
    "disabled": false
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "shortcut_not_found",
  "data": {}
}

Get A Shortcut
GET/website/{website_id}/shortcut/{shortcut_id}

Resolves shortcut information.

  • error (boolean)

  • reason (string)

  • data (object)

    • shortcut_id (string) - Shortcut identifier
    • bang (string) - Shortcut bang
    • text (string) - Shortcut text
    • tag (string) - Shortcut tag
    • disabled (boolean) - Whether shortcut is disabled or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier

shortcut_id
string (required) 

The shortcut identifier


PUT https://api.crisp.chat/v1/website/website_id/shortcut/shortcut_id
RequestsSave A Shortcut
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "bang": "!hello",
  "text": "Hello there!",
  "tag": "greetings",
  "disabled": true
}
Responses200402403404404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "shortcut_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "shortcut_bang_exists",
  "data": {}
}

Save A Shortcut
PUT/website/{website_id}/shortcut/{shortcut_id}

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

  • bang (string, required) - Shortcut bang

  • text (string, required) - Shortcut text

  • tag (string, optional) - Shortcut tag

  • disabled (boolean, optional) - Whether shortcut is disabled or not

URI Parameters
HideShow
website_id
string (required) 

The website identifier

shortcut_id
string (required) 

The shortcut identifier


PATCH https://api.crisp.chat/v1/website/website_id/shortcut/shortcut_id
RequestsUpdate A Shortcut
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "disabled": true
}
Responses200402403404404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "updated",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "shortcut_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "shortcut_bang_exists",
  "data": {}
}

Update A Shortcut
PATCH/website/{website_id}/shortcut/{shortcut_id}

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

  • bang (string, optional) - Shortcut bang

  • text (string, optional) - Shortcut text

  • tag (string, optional) - Shortcut tag

  • disabled (boolean, optional) - Whether shortcut is disabled or not

URI Parameters
HideShow
website_id
string (required) 

The website identifier

shortcut_id
string (required) 

The shortcut identifier


DELETE https://api.crisp.chat/v1/website/website_id/shortcut/shortcut_id
RequestsRemove A Shortcut
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200402403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "shortcut_not_found",
  "data": {}
}

Remove A Shortcut
DELETE/website/{website_id}/shortcut/{shortcut_id}

Removes a shortcut in website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

shortcut_id
string (required) 

The shortcut identifier


Website Campaigns

Manages multiple website campaigns.

GET https://api.crisp.chat/v1/website/website_id/campaigns/list/page_number?search_name=&filter_type_one_shot=&filter_type_automated=&filter_status_not_configured=&filter_status_ready=&filter_status_paused=&filter_status_sending=&filter_status_done=
RequestsList Campaigns
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "campaign_id": "819ef0d4-927a-4432-8444-0749a6c33ac1",
      "type": "one-shot",
      "format": "markdown",
      "name": "Merry Christmas!",
      "ready": true,
      "dispatched": true,
      "running": false,
      "progress": 100,
      "targets": 1243,
      "reached": 1243,
      "created_at": 1482845836236,
      "updated_at": 1482845836236,
      "dispatched_at": 1482845836236
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "campaign_id": "819ef0d4-927a-4432-8444-0749a6c33ac1",
      "type": "one-shot",
      "format": "markdown",
      "name": "Merry Christmas!",
      "ready": true,
      "dispatched": true,
      "running": false,
      "progress": 100,
      "targets": 1243,
      "reached": 1243,
      "created_at": 1482845836236,
      "updated_at": 1482845836236,
      "dispatched_at": 1482845836236
    },
    {
      "campaign_id": "15750df8-c041-4985-964b-74796bf52d0f",
      "type": "one-shot",
      "format": "markdown",
      "name": "Our New Product",
      "ready": true,
      "dispatched": false,
      "running": false,
      "progress": 0,
      "targets": 10218,
      "reached": 0,
      "created_at": 1482845662931,
      "updated_at": 1482846057833,
      "dispatched_at": 1482845820338
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Campaigns
GET/website/{website_id}/campaigns/list/{page_number}{?search_name}{&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.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • campaign_id (string) - Campaign identifier
    • type (enum[string]) - Campaign type
      • Members
        • one-shot
        • automated
    • format (enum[string]) - Campaign format
      • Members
        • markdown
        • html
    • name (string) - Campaign name
    • 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
URI Parameters
HideShow
website_id
string (required) 

The website identifier

page_number
number (optional) 

Page number for campaigns paging

search_name
string (optional) 

Search by campaign name

filter_type_one_shot
string (optional) 

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

filter_type_automated
string (optional) 

Filter by campaign automated type (1 or 0)

filter_status_not_configured
string (optional) 

Filter by campaign not configured status (1 or 0)

filter_status_ready
string (optional) 

Filter by campaign ready status (1 or 0)

filter_status_paused
string (optional) 

Filter by campaign paused status (1 or 0)

filter_status_sending
string (optional) 

Filter by campaign sending status (1 or 0)

filter_status_done
string (optional) 

Filter by campaign done status (1 or 0)


GET https://api.crisp.chat/v1/website/website_id/campaigns/templates/page_number
RequestsList Templates
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "template_id": "4b132cbf-9786-4a24-b04c-963d02e671bf",
      "name": "HTML Template",
      "format": "html",
      "created_at": 1526652030686,
      "updated_at": 1526652315224
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "template_id": "4b132cbf-9786-4a24-b04c-963d02e671bf",
      "name": "HTML Template",
      "format": "html",
      "created_at": 1526652030686,
      "updated_at": 1526652315224
    },
    {
      "template_id": "67394479-f014-4521-a62e-421f6fdc2bc1",
      "name": "Markdown Template",
      "format": "markdown",
      "created_at": 1526650988979,
      "updated_at": 1526652026590
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

List Campaign Templates
GET/website/{website_id}/campaigns/templates/{page_number}

Lists campaign templates for website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • template_id (string) - Template identifier
    • name (string) - Template name
    • format (enum[string]) - Template format
      • Members
        • markdown
        • html
    • created_at (number) - Template creation timestamp
    • updated_at (number) - Template update timestamp
URI Parameters
HideShow
website_id
string (required) 

The website identifier

page_number
number (optional) 

Page number for templates paging


POST https://api.crisp.chat/v1/website/website_id/campaigns/template
RequestsCreate A New Template
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "name": "HTML Template",
  "format": "html"
}
Responses201403404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {
    "template_id": "4b132cbf-9786-4a24-b04c-963d02e671bf"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_exists",
  "data": {}
}

Create A New Campaign Template
POST/website/{website_id}/campaigns/template

Creates a new campaign template.

  • name (string, required) - Template name

  • format (enum[string], required) - Template format

    • Members
      • markdown
      • html
URI Parameters
HideShow
website_id
string (required) 

The website identifier


HEAD https://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
RequestsCheck If Template Exists
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Campaign Template Exists
HEAD/website/{website_id}/campaigns/template/{template_id}

Checks if given campaign template exists.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

template_id
string (required) 

The template identifier


GET https://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
RequestsGet A Template
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "template_id": "4b132cbf-9786-4a24-b04c-963d02e671bf",
    "name": "HTML Template",
    "format": "html",
    "content": "<html><body><a href=\"{{url.unsubscribe}}\"></a></body></html>",
    "created_at": 1526652030686,
    "updated_at": 1526652315224
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_not_found",
  "data": {}
}

Get A Campaign Template
GET/website/{website_id}/campaigns/template/{template_id}

Resolves campaign template information.

  • error (boolean)

  • reason (string)

  • data (object)

    • template_id (string) - Template identifier
    • name (string) - Template name
    • format (enum[string]) - Template format
      • Members
        • markdown
        • html
    • content (string) - Template content
    • created_at (number) - Template creation timestamp
    • updated_at (number) - Template update timestamp
URI Parameters
HideShow
website_id
string (required) 

The website identifier

template_id
string (required) 

The template identifier


PUT https://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
RequestsSave A Template
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "name": "HTML Template",
  "content": "<html><body><a href=\"{{url.unsubscribe}}\"></a></body></html>"
}
Responses200400400403404404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_html_invalid_code",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_html_no_unsubscribe",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_name_exists",
  "data": {}
}

Save A Campaign Template
PUT/website/{website_id}/campaigns/template/{template_id}

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

  • name (string, required) - Template name

  • content (string, required) - Template content

URI Parameters
HideShow
website_id
string (required) 

The website identifier

template_id
string (required) 

The template identifier


PATCH https://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
RequestsUpdate A Template
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "content": "<html><body><a href=\"{{url.unsubscribe}}\"></a></body></html>"
}
Responses200400400403404404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "updated",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_html_invalid_code",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_html_no_unsubscribe",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_name_exists",
  "data": {}
}

Update A Campaign Template
PATCH/website/{website_id}/campaigns/template/{template_id}

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

  • name (string, optional) - Template name

  • content (string, optional) - Template content

URI Parameters
HideShow
website_id
string (required) 

The website identifier

template_id
string (required) 

The template identifier


DELETE https://api.crisp.chat/v1/website/website_id/campaigns/template/template_id
RequestsRemove A Template
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "template_not_found",
  "data": {}
}

Remove A Campaign Template
DELETE/website/{website_id}/campaigns/template/{template_id}

Removes a campaign template in website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

template_id
string (required) 

The template identifier


Website Campaign

Manages a single website campaign.

POST https://api.crisp.chat/v1/website/website_id/campaign
RequestsCreate A New Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "one-shot",
  "name": "Welcome!"
}
Responses201403404404409
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {
    "campaign_id": "5cc093b4-ee95-4327-be14-3f1cf6b84ae2"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_exists",
  "data": {}
}

Create A New Campaign
POST/website/{website_id}/campaign

Creates a new campaign.

  • type (enum[string], required) - Campaign type

    • Members
      • one-shot
      • automated
  • name (string, required) - Campaign name

URI Parameters
HideShow
website_id
string (required) 

The website identifier


HEAD https://api.crisp.chat/v1/website/website_id/campaign/campaign_id
RequestsCheck If Campaign Exists
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Campaign Exists
HEAD/website/{website_id}/campaign/{campaign_id}

Checks if given campaign exists.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


GET https://api.crisp.chat/v1/website/website_id/campaign/campaign_id
RequestsGet A Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "campaign_id": "5cc093b4-ee95-4327-be14-3f1cf6b84ae2",
    "type": "one-shot",
    "format": "markdown",
    "name": "Welcome!",
    "sender": {
      "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b"
    },
    "recipients": {
      "type": "all"
    },
    "message": "*Hey there*, welcome on Crisp!",
    "options": {
      "deliver_to_email": true,
      "deliver_to_chatbox": true,
      "tracking": true
    },
    "statistics": {
      "opened": 42,
      "clicked": 23
    },
    "ready": true,
    "dispatched": true,
    "running": true,
    "progress": 50,
    "targets": 1243,
    "reached": 630,
    "created_at": 1482848102359,
    "updated_at": 1482848102359,
    "dispatched_at": 1482848102359
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}

Get A Campaign
GET/website/{website_id}/campaign/{campaign_id}

Resolves campaign information.

  • error (boolean)

  • reason (string)

  • data (object)

    • campaign_id (string) - Campaign identifier
    • type (enum[string]) - Campaign type
      • Members
        • one-shot
        • automated
    • format (enum[string]) - Campaign format
      • Members
        • markdown
        • html
    • name (string) - Campaign name
    • 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
        • Members
          • 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
          • Members
            • people
        • criterion (string) - Filter criterion (in model)
        • operator (enum[string]) - Filter operator
          • Members
            • eq
            • neq
            • ex
            • nex
            • has
            • nhas
            • sw
            • ew
            • gte
            • lte
            • gt
            • lt
        • query (array[string, number, boolean]) - Filter query terms
    • flow (object) - Campaign flow (if type is automated)
      • launch_event (string) - Event identifier that triggers automation flow (to run campaign for an user)
      • assert_filter (array[object]) - Filter to assert when event is triggered (can be empty)
        • model (enum[string]) - Filter model
          • Members
            • people
        • criterion (string) - Filter criterion (in model)
        • operator (enum[string]) - Filter operator
          • Members
            • eq
            • neq
            • ex
            • nex
            • has
            • nhas
            • sw
            • ew
            • gte
            • lte
            • gt
            • lt
        • query (array[string, number, boolean]) - 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
      • 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
    • 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
URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


PUT https://api.crisp.chat/v1/website/website_id/campaign/campaign_id
RequestsSave A Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "one-shot",
  "format": "markdown",
  "name": "Welcome!",
  "sender": {
    "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b"
  },
  "recipients": {
    "type": "all"
  },
  "message": "*Hey there*, welcome on Crisp!",
  "options": {
    "deliver_to_chatbox": true,
    "deliver_to_email": true,
    "tracking": true
  }
}
Responses200400400403404404404404409422423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_html_invalid_code",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_html_no_unsubscribe",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "sender_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_name_exists",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_format_incompatible",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_locked",
  "data": {}
}

Save A Campaign
PUT/website/{website_id}/campaign/{campaign_id}

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

  • type (enum[string], required) - Campaign type

    • Members
      • one-shot
      • automated
  • format (enum[string], required) - Campaign format

    • Members
      • markdown
      • html
  • name (string, required) - Campaign name

  • sender (object, required) - Campaign sender

    • user_id (string, required) - Sender user identifier (member of website)
  • recipients (object, required) - Campaign recipients (if type is one-shot)

    • type (enum[string], required) - Recipient routing type
      • Members
        • 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
        • Members
          • people
      • criterion (string, required) - Filter criterion (in model)
      • operator (enum[string], required) - Filter operator
        • Members
          • eq
          • neq
          • ex
          • nex
          • has
          • nhas
          • sw
          • ew
          • gte
          • lte
          • gt
          • lt
      • query (array[string, number, boolean], required) - Filter query terms
  • flow (object, required) - Campaign flow (if type is automated)

    • launch_event (string, required) - Event identifier that triggers automation flow (to run campaign for an user)
    • assert_filter (array[object], required) - Filter to assert when event is triggered (can be empty)
      • model (enum[string], required) - Filter model
        • Members
          • people
      • criterion (string, required) - Filter criterion (in model)
      • operator (enum[string], required) - Filter operator
        • Members
          • eq
          • neq
          • ex
          • nex
          • has
          • nhas
          • sw
          • ew
          • gte
          • lte
          • gt
          • lt
      • query (array[string, number, boolean], required) - Filter query terms
    • assert_delay (number, required) - Delay in minutes after which to process assertions (no delay by default)
    • deliver_once (boolean, required) - Ensures campaign is delivered once at a maximum for a given user, or not
    • deliver_delay (number, required) - Delivery delay in minutes (no delay by default)
  • message (string, required) - Campaign message

  • options (object, optional) - Campaign options

    • deliver_to_chatbox (boolean, optional) - Whether to deliver message to chatbox or not
    • deliver_to_email (boolean, optional) - Whether to deliver message to email or not
    • tracking (boolean, optional) - Whether to enable tracking or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


PATCH https://api.crisp.chat/v1/website/website_id/campaign/campaign_id
RequestsUpdate A Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "message": "*Hey there*, welcome on Crisp folks!"
}
Responses200400400403404404404404409422423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "updated",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_html_invalid_code",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_html_no_unsubscribe",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "sender_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_name_exists",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_format_incompatible",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_locked",
  "data": {}
}

Update A Campaign
PATCH/website/{website_id}/campaign/{campaign_id}

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

  • type (enum[string], optional) - Campaign type

    • Members
      • one-shot
      • automated
  • format (enum[string], optional) - Campaign format

    • Members
      • markdown
      • html
  • name (string, optional) - Campaign name

  • sender (object, optional) - Campaign sender

    • user_id (string, required) - Sender user identifier (member of website)
  • recipients (object, optional) - Campaign recipients (if type is one-shot)

    • type (enum[string], required) - Recipient routing type
      • Members
        • 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
        • Members
          • people
      • criterion (string, required) - Filter criterion (in model)
      • operator (enum[string], required) - Filter operator
        • Members
          • eq
          • neq
          • ex
          • nex
          • has
          • nhas
          • sw
          • ew
          • gte
          • lte
          • gt
          • lt
      • query (array[string, number, boolean], required) - Filter query terms
  • flow (object, optional) - Campaign flow (if type is automated)

    • launch_event (string, required) - Event identifier that triggers automation flow (to run campaign for an user)
    • assert_filter (array[object], required) - Filter to assert when event is triggered (can be empty)
      • model (enum[string], required) - Filter model
        • Members
          • people
      • criterion (string, required) - Filter criterion (in model)
      • operator (enum[string], required) - Filter operator
        • Members
          • eq
          • neq
          • ex
          • nex
          • has
          • nhas
          • sw
          • ew
          • gte
          • lte
          • gt
          • lt
      • query (array[string, number, boolean], required) - Filter query terms
    • assert_delay (number, required) - Delay in minutes after which to process assertions (no delay by default)
    • deliver_once (boolean, required) - Ensures campaign is delivered once at a maximum for a given user, or not
    • deliver_delay (number, required) - Delivery delay in minutes (no delay by default)
  • message (string, optional) - Campaign message

  • options (object, optional) - Campaign options

    • deliver_to_chatbox (boolean, required) - Whether to deliver message to chatbox or not
    • deliver_to_email (boolean, required) - Whether to deliver message to email or not
    • tracking (boolean, required) - Whether to enable tracking or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


DELETE https://api.crisp.chat/v1/website/website_id/campaign/campaign_id
RequestsRemove A Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}

Remove A Campaign
DELETE/website/{website_id}/campaign/{campaign_id}

Removes a campaign in website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


POST https://api.crisp.chat/v1/website/website_id/campaign/campaign_id/dispatch
RequestsDispatch A Campaign
Headers
Content-Type: application/json
Body
+ Authenticated Tiers: `user` `plugin`
Responses202402403404404404404410412412412423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "sender_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_already_dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_ready",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "custom_domain_not_configured",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_recipients_limited",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_slot_unavailable",
  "data": {}
}

Dispatch A Campaign
POST/website/{website_id}/campaign/{campaign_id}/dispatch

Dispatches a ready campaign.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


POST https://api.crisp.chat/v1/website/website_id/campaign/campaign_id/resume
RequestsResume A Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses202402403404404404404404410412412423
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resumed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_already_running",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_finished",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "custom_domain_not_configured",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_recipients_limited",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_slot_unavailable",
  "data": {}
}

Resume A Campaign
POST/website/{website_id}/campaign/{campaign_id}/resume

Resumes a paused and dispatched campaign.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


POST https://api.crisp.chat/v1/website/website_id/campaign/campaign_id/pause
RequestsPause A Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses202403404404404404404410
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "paused",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_running",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_finished",
  "data": {}
}

Pause A Campaign
POST/website/{website_id}/campaign/{campaign_id}/pause

Pauses a running and dispatched campaign.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


POST https://api.crisp.chat/v1/website/website_id/campaign/campaign_id/test
RequestsTest A Campaign
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses202403404404404404412412
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "tested",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "sender_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_ready",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "email_not_available",
  "data": {}
}

Test A Campaign
POST/website/{website_id}/campaign/{campaign_id}/test

Tests a ready campaign.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier


GET https://api.crisp.chat/v1/website/website_id/campaign/campaign_id/statistics/action/page_number
RequestsList Campaign Statistics
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206400403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "profile": {
        "people_id": "3adc5e9a-f6c6-4a6d-afb8-65723b462584",
        "email": "julien@crisp.chat",
        "person": {
          "nickname": "Julien Le Coupanec",
          "avatar": "https://image.enrichdata.com/person/avatar/782b7301625165519220a8f8710beebab8d3428e.jpg",
          "geolocation": {
            "country": "GB",
            "region": "ENG",
            "city": "London",
            "coordinates": {
              "latitude": 51.5142,
              "longitude": -0.0931
            }
          }
        }
      },
      "data": {
        "link_url": "https://app.crisp.chat/"
      },
      "created_at": 1524669312140,
      "updated_at": 1524669312140
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "profile": {
        "people_id": "3adc5e9a-f6c6-4a6d-afb8-65723b462584",
        "email": "julien@crisp.chat",
        "person": {
          "nickname": "Julien Le Coupanec",
          "avatar": "https://image.enrichdata.com/person/avatar/782b7301625165519220a8f8710beebab8d3428e.jpg",
          "geolocation": {
            "country": "GB",
            "region": "ENG",
            "city": "London",
            "coordinates": {
              "latitude": 51.5142,
              "longitude": -0.0931
            }
          }
        }
      },
      "data": {
        "link_url": "https://app.crisp.chat/"
      },
      "created_at": 1524669312140,
      "updated_at": 1524669312140
    },
    {
      "profile": {
        "people_id": "a59773ee-d936-4432-8171-1e6063ecba1b",
        "email": "valerian@crisp.chat",
        "person": {
          "nickname": "Valerian Saliou",
          "avatar": "https://image.enrichdata.com/person/avatar/7d47b5be7e31885719e6587eb49fd50403045c80.jpg",
          "geolocation": {
            "country": "GB",
            "region": "ENG",
            "city": "London",
            "coordinates": {
              "latitude": 51.5142,
              "longitude": -0.0931
            }
          }
        }
      },
      "data": {
        "link_url": "https://app.crisp.chat/"
      },
      "created_at": 1524669188363,
      "updated_at": 1524669188363
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_statistics",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "campaign_not_found",
  "data": {}
}

List Campaign Statistics
GET/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, or clicked on a link from the campaign.

  • 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
URI Parameters
HideShow
website_id
string (required) 

The website identifier

campaign_id
string (required) 

The campaign identifier

action
string (required) 

The statistics action (either clicked or opened)

page_number
number (optional) 

Page number for statistics paging


Website Visitors

Manages multiple website visitors.

GET https://api.crisp.chat/v1/website/website_id/visitors/count
RequestsCount Visitors
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "counted",
  "data": {
    "count": 42,
    "active": 7
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Count Visitors
GET/website/{website_id}/visitors/count

Counts visitors currently on website.

  • 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)
URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/visitors/list/page_number
RequestsList Visitors
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "session_id": "session_19e5240f-0a8d-461e-a661-a3123fc6eec9",
      "nickname": "Valerian",
      "email": "valerian@crisp.chat",
      "avatar": "https://image.enrichdata.com/person/avatar/7d47b5be7e31885719e6587eb49fd50403045c80.jpg",
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2683.0 Safari/537.36",
      "initiated": true,
      "active": true,
      "last_page": {
        "page_title": "Acme Inc. | Marketplace",
        "page_url": "https://shop.acme-inc.com/"
      },
      "geolocation": {
        "country": "US",
        "region": "CA",
        "city": "San Francisco",
        "coordinates": {
          "latitude": 37.7749,
          "longitude": -122.4194
        }
      },
      "timezone": -120,
      "capabilities": [
        "browsing",
        "call"
      ],
      "locales": [
        "en-US",
        "en",
        "fr"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "session_id": "session_19e5240f-0a8d-461e-a661-a3123fc6eec9",
      "nickname": "Valerian",
      "email": "valerian@crisp.chat",
      "avatar": "https://image.enrichdata.com/person/avatar/7d47b5be7e31885719e6587eb49fd50403045c80.jpg",
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2683.0 Safari/537.36",
      "initiated": true,
      "active": true,
      "last_page": {
        "page_title": "Acme Inc. | Marketplace",
        "page_url": "https://shop.acme-inc.com/"
      },
      "geolocation": {
        "country": "US",
        "region": "CA",
        "city": "San Francisco",
        "coordinates": {
          "latitude": 37.7749,
          "longitude": -122.4194
        }
      },
      "timezone": -120,
      "capabilities": [
        "browsing",
        "call"
      ],
      "locales": [
        "en-US",
        "en",
        "fr"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List Visitors
GET/website/{website_id}/visitors/list/{page_number}

Lists visitors currently on website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • session_id (string) - Session identifier for visitor
    • nickname (string) - Nickname for visitor
    • email (string) - Email for visitor
    • avatar (string) - Avatar for visitor
    • useragent (string) - Useragent as advertised by visitor browser
    • initiated (boolean) - Whether session is initiated or not
    • active (boolean) - Whether the user is actively browsing or not
    • last_page (object) - Last page browsed by visitor
      • page_title (string) - Last page title
      • page_url (string) - Last page URL
    • geolocation (object) - Geolocation for visitor
      • country (string) - Country code
      • region (string) - Region code
      • city (string) - City name
      • coordinates (object) - Location coordinates
        • latitude (number) - Latitude coordinate
        • longitude (number) - Longitude coordinate
    • timezone (number) - Visitor timezone offset (UTC)
    • capabilities (array[enum[string]]) - Capabilities of the visitor device
      • Members
        • browsing
        • call
    • locales (array[string]) - Locales supported by visitor (ISO 639-1)
URI Parameters
HideShow
website_id
string (required) 

The website identifier

page_number
number (optional) 

Page number for conversations paging


GET https://api.crisp.chat/v1/website/website_id/visitors/map?center_latitude=&center_longitude=&center_radius=
RequestsMap Visitors
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200400400400402403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "mapped",
  "data": [
    {
      "visitors": {
        "count": 73,
        "threshold": 99,
        "sessions": [
          {
            "session_id": "session_19e5240f-0a8d-461e-a661-a3123fc6eec9",
            "nickname": "Valerian",
            "email": "valerian@crisp.chat",
            "avatar": "https://image.enrichdata.com/person/avatar/7d47b5be7e31885719e6587eb49fd50403045c80.jpg",
            "initiated": true,
            "active": true,
            "last_page": {
              "page_title": "Acme Inc. | Marketplace",
              "page_url": "https://shop.acme-inc.com/"
            },
            "timezone": -120,
            "capabilities": [
              "browsing",
              "call"
            ],
            "locales": [
              "en-US",
              "en",
              "fr"
            ]
          }
        ]
      },
      "geolocation": {
        "country": "US",
        "region": "CA",
        "city": "San Francisco",
        "coordinates": {
          "latitude": 37.7749,
          "longitude": -122.4194
        }
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_longitude",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_latitude",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_radius",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Pinpoint Visitors On A Map
GET/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.

  • 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
          • Members
            • 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
URI Parameters
HideShow
website_id
string (required) 

The website identifier

center_latitude
number (optional) 

Area center point latitude

center_longitude
number (optional) 

Area center point longitude

center_radius
number (optional) 

Area radius (in kilometers)


GET https://api.crisp.chat/v1/website/website_id/visitors/blocked
RequestsCount Blocked Visitors
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "rule": "ip",
      "blocked": 13
    },
    {
      "rule": "email",
      "blocked": 2
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Count Blocked Visitors
GET/website/{website_id}/visitors/blocked

Counts all blocked visitors on website, by rule list.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • rule (string) - Rule name
      • Members
        • ip
        • email
    • blocked (number) - Number of blocked visitors for rule
URI Parameters
HideShow
website_id
string (required) 

The website identifier


GET https://api.crisp.chat/v1/website/website_id/visitors/blocked/block_rule
RequestsCount Blocked Visitors
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "rule": "ip",
    "blocked": 13
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "rule_not_found",
  "data": {}
}

Count Blocked Visitors In Rule
GET/website/{website_id}/visitors/blocked/{block_rule}

Counts all blocked visitors in rule list on website.

  • error (boolean)

  • reason (string)

  • data (object)

    • rule (string) - Rule name
      • Members
        • ip
        • email
    • blocked (number) - Number of blocked visitors for rule
URI Parameters
HideShow
website_id
string (required) 

The website identifier

block_rule
string (required) 

The block rule (ip or email)


DELETE https://api.crisp.chat/v1/website/website_id/visitors/blocked/block_rule
RequestsClear Blocked Visitors
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "website_member_role_not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "rule_not_found",
  "data": {}
}

Clear Blocked Visitors In Rule
DELETE/website/{website_id}/visitors/blocked/{block_rule}

Clears all blocked visitors in rule list on website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

block_rule
string (required) 

The block rule (ip or email)


Website Setup

Manages the website setup.

GET https://api.crisp.chat/v1/website/website_id/setup
RequestsGet Website Setup
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "disabled": true,
    "states": {
      "chatbox": {
        "done": false,
        "trial": 0
      },
      "messenger": {
        "done": false,
        "trial": 0
      },
      "email": {
        "done": false,
        "trial": 0
      },
      "slack": {
        "done": false,
        "trial": 0
      },
      "autoresponder": {
        "done": false,
        "trial": 0
      },
      "helpdesk": {
        "done": false,
        "trial": 0
      },
      "status": {
        "done": false,
        "trial": 0
      }
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get Website Setup
GET/website/{website_id}/setup

Resolves the setup state for a website.

  • error (boolean)

  • reason (string)

  • data (object)

    • disabled (boolean) - Whether setup flow is disabled or not
    • states (object) - Setup states
      • chatbox (object) - Setup state for chatbox
        • done (boolean) - Whether chatbox setup is done or not
        • trial (number) - Trial days added for chatbox setup
      • messenger (object) - Setup state for Messenger
        • done (boolean) - Whether Messenger setup is done or not
        • trial (number) - Trial days added for Messenger setup
      • email (object) - Setup state for email
        • done (boolean) - Whether email setup is done or not
        • trial (number) - Trial days added for email setup
      • slack (object) - Setup state for Slack
        • done (boolean) - Whether Slack setup is done or not
        • trial (number) - Trial days added for Slack setup
      • autoresponder (object) - Setup state for Auto-Responder
        • done (boolean) - Whether Auto-Responder setup is done or not
        • trial (number) - Trial days added for Auto-Responder setup
      • helpdesk (object) - Setup state for Helpdesk
        • done (boolean) - Whether Helpdesk setup is done or not
        • trial (number) - Trial days added for Helpdesk setup
      • status (object) - Setup state for Status Page
        • done (boolean) - Whether Status Page setup is done or not
        • trial (number) - Trial days added for Status Page setup
URI Parameters
HideShow
website_id
string (required) 

The website identifier


PATCH https://api.crisp.chat/v1/website/website_id/setup
RequestsUpdate Website Setup
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "disabled": true
}
Responses200403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "saved",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Update Website Setup
PATCH/website/{website_id}/setup

Updates the setup state for a website.

  • disabled (boolean, optional) - Whether setup flow is disabled or not
URI Parameters
HideShow
website_id
string (required) 

The website identifier


Website Conversations

Manages multiple website conversations.

GET https://api.crisp.chat/v1/website/website_id/conversations/page_number?search_query=&search_type=&include_empty=&filter_unread=&filter_not_resolved=&filter_mention=&filter_assigned=&filter_unassigned=&order_date_created=&order_date_updated=
RequestsList Conversations
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206402403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "session_id": "session_aaea8e1d-d6e3-4238-9252-d8c2e5579f5c",
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "people_id": "0cb89450-34fb-4d51-8905-040c1d14a594",
      "status": 1,
      "state": "unresolved",
      "is_verified": false,
      "is_blocked": false,
      "availability": "offline",
      "active": {
        "now": false
      },
      "last_message": "All right, thanks.",
      "mentions": [],
      "updated_at": 1468401603070,
      "created_at": 1468341857826,
      "unread": {
        "operator": 0,
        "visitor": 1
      },
      "assigned": {
        "user_id": "a4c32c68-be91-4e29-8a05-976e93abbe3f"
      },
      "meta": {
        "nickname": "Dan Boy",
        "email": "dan.boy@acme-inc.com",
        "ip": "104.236.186.68",
        "avatar": null,
        "device": {
          "capabilities": [
            "call"
          ],
          "geolocation": {
            "country": "US",
            "region": "CA",
            "city": "San Francisco",
            "coordinates": {
              "latitude": 37.7749,
              "longitude": -122.4194
            }
          },
          "system": {
            "os": {
              "version": "10.11.5",
              "name": "Mac OS"
            },
            "engine": {
              "name": "WebKit",
              "version": "537.36"
            },
            "browser": {
              "major": "51",
              "version": "51.0.2683.0",
              "name": "Chrome"
            },
            "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2683.0 Safari/537.36"
          },
          "timezone": -120,
          "locales": [
            "en",
            "fr"
          ]
        },
        "segments": [
          "customer",
          "friend"
        ]
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "session_id": "session_aaea8e1d-d6e3-4238-9252-d8c2e5579f5c",
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "people_id": "0cb89450-34fb-4d51-8905-040c1d14a594",
      "status": 1,
      "state": "unresolved",
      "is_verified": false,
      "is_blocked": false,
      "availability": "offline",
      "active": {
        "now": false
      },
      "last_message": "All right, thanks.",
      "mentions": [],
      "updated_at": 1468401603070,
      "created_at": 1468341857826,
      "unread": {
        "operator": 0,
        "visitor": 1
      },
      "assigned": {
        "user_id": "a4c32c68-be91-4e29-8a05-976e93abbe3f"
      },
      "meta": {
        "nickname": "Dan Boy",
        "email": "dan.boy@acme-inc.com",
        "ip": "104.236.186.68",
        "avatar": null,
        "device": {
          "capabilities": [
            "call"
          ],
          "geolocation": {
            "country": "US",
            "region": "CA",
            "city": "San Francisco",
            "coordinates": {
              "latitude": 37.7749,
              "longitude": -122.4194
            }
          },
          "system": {
            "os": {
              "version": "10.11.5",
              "name": "Mac OS"
            },
            "engine": {
              "name": "WebKit",
              "version": "537.36"
            },
            "browser": {
              "major": "51",
              "version": "51.0.2683.0",
              "name": "Chrome"
            },
            "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2683.0 Safari/537.36"
          },
          "timezone": -120,
          "locales": [
            "en",
            "fr"
          ]
        },
        "segments": [
          "customer",
          "friend"
        ]
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List Conversations
GET/website/{website_id}/conversations/{page_number}{?search_query}{&search_type}{&include_empty}{&filter_unread}{&filter_not_resolved}{&filter_mention}{&filter_assigned}{&filter_unassigned}{&order_date_created}{&order_date_updated}

Lists conversations for website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • session_id (string) - Session identifier
    • website_id (string) - Website identifier
    • people_id (string) - People identifier
    • state (enum[string]) - Conversation state
      • Members
        • pending
        • unresolved
        • resolved
    • status (enum[number]) - Conversation status (an alias of state; useful for sorting conversations)
      • Members
        • 0 - Numeric code for pending status
        • 1 - Numeric code for unresolved status
        • 2 - Numeric code for resolved status
    • 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
      • Members
        • 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
    • mentions (array[string]) - Mentioned user identifiers (from conversation messages)
    • created_at (number) - Conversation creation timestamp
    • updated_at (number) - Conversation update timestamp
    • compose (object) - Compose states
      • operator (object) - Compose state for operator
        • type (enum[string]) - Compose state type
          • Members
            • 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
      • visitor (object) - Compose state for visitor
        • type (enum[string]) - Compose state type
          • Members
            • start
            • stop
        • excerpt (string) - Message excerpt for compose state
        • timestamp (number) - Timestamp for compose state
    • 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
      • ip (string) - Visitor IP address
      • data (object) - Visitor data
      • avatar (string) - Visitor avatar
      • device (object) - Device information
        • capabilities (array[enum[string]]) - Visitor device capabilities
          • Members
            • 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
URI Parameters
HideShow
website_id
string (required) 

The website identifier

page_number
number (optional) 

Page number for conversations paging

search_query
string (optional) 

Search query in all conversations

search_type
string (optional) 

Search type (either text or segment)

include_empty
string (optional) 

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

filter_unread
string (optional) 

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

filter_not_resolved
string (optional) 

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

filter_mention
string (optional) 

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

filter_assigned
string (optional) 

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

filter_unassigned
string (optional) 

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

order_date_created
string (optional) 

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

order_date_updated
string (optional) 

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


GET https://api.crisp.chat/v1/website/website_id/conversations/meta/segments/page_number
RequestsList Conversation Segments
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "segment": "customer",
      "count": 214
    },
    {
      "segment": "bug",
      "count": 41
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "segment": "customer",
      "count": 214
    },
    {
      "segment": "bug",
      "count": 41
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List Conversation Segments In Meta
GET/website/{website_id}/conversations/meta/segments/{page_number}

Lists conversation segments in meta for website.

  • error (boolean)

  • reason (string)

  • data (array[object])

    • segment (string) - Segment value
    • count (number) - Number of occurences of this segment
URI Parameters
HideShow
website_id
string (required) 

The website identifier

page_number
number (optional) 

The page number (paging in segment list)


Website Conversation

Manages a single website conversation.

POST https://api.crisp.chat/v1/website/website_id/conversation
RequestsCreate A New Conversation
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses201403404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "added",
  "data": {
    "session_id": "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881"
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Create A New Conversation
POST/website/{website_id}/conversation

Creates a new conversation.

  • error (boolean)

  • reason (string)

  • data (object)

    • session_id (string) - Created conversation session identifier
URI Parameters
HideShow
website_id
string (required) 

The website identifier


HEAD https://api.crisp.chat/v1/website/website_id/conversation/session_id
RequestsCheck If Conversation Exists
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Headers
Content-Type: application/json

Check If Conversation Exists
HEAD/website/{website_id}/conversation/{session_id}

Checks if given conversation session identifier exists.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The conversation session identifier


GET https://api.crisp.chat/v1/website/website_id/conversation/session_id
RequestsGet A Conversation
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "session_id": "session_aaea8e1d-d6e3-4238-9252-d8c2e5579f5c",
    "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
    "people_id": "0cb89450-34fb-4d51-8905-040c1d14a594",
    "status": 1,
    "state": "unresolved",
    "is_verified": false,
    "is_blocked": false,
    "availability": "offline",
    "active": {
      "now": false
    },
    "last_message": "All right, thanks.",
    "mentions": [],
    "updated_at": 1468401603070,
    "created_at": 1468341857826,
    "unread": {
      "operator": 0,
      "visitor": 1
    },
    "assigned": {
      "user_id": "a4c32c68-be91-4e29-8a05-976e93abbe3f"
    },
    "meta": {
      "nickname": "Dan Boy",
      "email": "dan.boy@acme-inc.com",
      "ip": "104.236.186.68",
      "avatar": null,
      "device": {
        "capabilities": [
          "call"
        ],
        "geolocation": {
          "country": "US",
          "region": "CA",
          "city": "San Francisco",
          "coordinates": {
            "latitude": 37.7749,
            "longitude": -122.4194
          }
        },
        "system": {
          "os": {
            "version": "10.11.5",
            "name": "Mac OS"
          },
          "engine": {
            "name": "WebKit",
            "version": "537.36"
          },
          "browser": {
            "major": "51",
            "version": "51.0.2683.0",
            "name": "Chrome"
          },
          "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2683.0 Safari/537.36"
        },
        "timezone": -120,
        "locales": [
          "en",
          "fr"
        ]
      },
      "segments": [
        "customer",
        "friend"
      ]
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "conversation_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get A Conversation
GET/website/{website_id}/conversation/{session_id}

Resolves conversation information.

  • error (boolean)

  • reason (string)

  • data (object)

    • session_id (string) - Session identifier
    • website_id (string) - Website identifier
    • people_id (string) - People identifier
    • state (enum[string]) - Conversation state
      • Members
        • pending
        • unresolved
        • resolved
    • status (enum[number]) - Conversation status (an alias of state; useful for sorting conversations)
      • Members
        • 0 - Numeric code for pending status
        • 1 - Numeric code for unresolved status
        • 2 - Numeric code for resolved status
    • 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
      • Members
        • 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
    • mentions (array[string]) - Mentioned user identifiers (from conversation messages)
    • created_at (number) - Conversation creation timestamp
    • updated_at (number) - Conversation update timestamp
    • compose (object) - Compose states
      • operator (object) - Compose state for operator
        • type (enum[string]) - Compose state type
          • Members
            • 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
      • visitor (object) - Compose state for visitor
        • type (enum[string]) - Compose state type
          • Members
            • start
            • stop
        • excerpt (string) - Message excerpt for compose state
        • timestamp (number) - Timestamp for compose state
    • 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
      • ip (string) - Visitor IP address
      • data (object) - Visitor data
      • avatar (string) - Visitor avatar
      • device (object) - Device information
        • capabilities (array[enum[string]]) - Visitor device capabilities
          • Members
            • 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
URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The conversation session identifier


DELETE https://api.crisp.chat/v1/website/website_id/conversation/session_id
RequestsRemove A Conversation
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "deleted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "removal_not_permitted",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "conversation_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Remove A Conversation
DELETE/website/{website_id}/conversation/{session_id}

Removes a conversation in website.

URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The conversation session identifier


POST https://api.crisp.chat/v1/website/website_id/conversation/session_id/initiate
RequestsInitiate A Conversation With Existing Session
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses201403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "initiated",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Initiate A Conversation With Existing Session
POST/website/{website_id}/conversation/{session_id}/initiate

Initiates a conversation from an existing session.

Used to initiate a conversation from website visitor list, and trigger a chatbox open.

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

URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The conversation session identifier


GET https://api.crisp.chat/v1/website/website_id/conversation/session_id/messages?timestamp_before=
RequestsGet Messages
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200206403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "session_id": "session_0839e4c2-a059-445b-8de5-390d6417f893",
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "type": "text",
      "from": "user",
      "origin": "chat",
      "content": "Hey, how are you doing?",
      "preview": [],
      "mentions": [],
      "stamped": true,
      "read": "email",
      "delivered": "email",
      "fingerprint": 5719231201,
      "timestamp": 1468413681043,
      "user": {
        "nickname": "Dan Boy",
        "user_id": "session_0839e4c2-a059-445b-8de5-390d6417f893"
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "session_id": "session_0839e4c2-a059-445b-8de5-390d6417f893",
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "type": "text",
      "from": "user",
      "origin": "chat",
      "content": "Hey, how are you doing?",
      "preview": [],
      "mentions": [],
      "stamped": true,
      "read": "email",
      "delivered": "email",
      "fingerprint": 5719231201,
      "timestamp": 1468413681043,
      "user": {
        "nickname": "Dan Boy",
        "user_id": "session_0839e4c2-a059-445b-8de5-390d6417f893"
      }
    },
    {
      "session_id": "session_0839e4c2-a059-445b-8de5-390d6417f893",
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "type": "text",
      "from": "operator",
      "origin": "chat",
      "content": "πŸ‘",
      "preview": [],
      "mentions": [],
      "stamped": true,
      "read": "chat",
      "delivered": "chat",
      "fingerprint": 5720387819,
      "timestamp": 1468413690687,
      "user": {
        "nickname": "Valerian Saliou",
        "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b"
      }
    },
    {
      "session_id": "session_0839e4c2-a059-445b-8de5-390d6417f893",
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "type": "file",
      "from": "operator",
      "origin": "email",
      "content": {
        "name": "Thats awesome.jpg",
        "url": "https://storage.crisp.chat/users/upload/operator/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/19d956c7-0294-45ad-89e1-58ce45e7008f.jpg",
        "type": "image/jpeg"
      },
      "preview": [],
      "mentions": [],
      "stamped": true,
      "read": null,
      "delivered": "chat",
      "fingerprint": 8682935614,
      "timestamp": 1468487977677,
      "user": {
        "nickname": "Valerian Saliou",
        "user_id": "aa0b64dd-9fb4-4db9-80d6-5a49eb84087b"
      }
    },
    {
      "session_id": "session_0839e4c2-a059-445b-8de5-390d6417f893",
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "type": "text",
      "from": "user",
      "origin": "chat",
      "content": "Hey check that: https://crisp.chat/",
      "preview": [
        {
          "url": "https://crisp.chat/",
          "website": "crisp.chat",
          "title": "Simple Customer service built for startups.",
          "preview": {
            "excerpt": "Chat with your customers, Collaborate with your team",
            "image": "https://crisp.chat/tile.png"
          }
        }
      ],
      "mentions": [],
      "stamped": true,
      "read": "chat",
      "delivered": null,
      "fingerprint": 9663657330,
      "timestamp": 1468488196711,
      "user": {
        "nickname": "Dan Boy",
        "user_id": "session_0839e4c2-a059-445b-8de5-390d6417f893"
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get Messages In Conversation
GET/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.

  • 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)
      • id (string) - Object identifier (only set if message type is picker or field)
      • text (string) - Object text (only set if message type is picker or field)
      • 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
        • label (string) - Choice label
        • selected (boolean) - Whether choice is selected or not
      • 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)
        • Members
          • reminder:scheduled
          • call:started
          • call:ended
    • 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)
    • mentions (array[string]) - Mentioned user identifiers
    • read (enum[string]) - Channel in which message has been read
      • Members
        • null
        • chat
        • email
    • delivered (enum[string]) - Channel in which message has lastly been delivered
      • Members
        • null
        • chat
        • email
    • 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 (string) - Sending user type (if any)
        • Members
          • website
      • user_id (string) - Sending user identifier (may be operator user identifier or session identifier)
      • nickname (string) - Sending user nickname
      • avatar (string) - Sending user avatar
URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The conversation session identifier

timestamp_before
number (optional) 

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


POST https://api.crisp.chat/v1/website/website_id/conversation/session_id/message
RequestsSend Text MessageSend Note MessageSend File MessageSend Animation MessageSend Audio MessageSend Picker MessageSend Field MessageSend Event Message
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "text",
  "from": "operator",
  "origin": "chat",
  "content": "Hey there! Need help?"
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "note",
  "from": "operator",
  "origin": "chat",
  "content": "What should I tell him?"
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "file",
  "from": "operator",
  "origin": "chat",
  "content": {
    "name": "Thats awesome.jpg",
    "url": "https://storage.crisp.chat/users/upload/operator/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/19d956c7-0294-45ad-89e1-58ce45e7008f.jpg",
    "type": "image/jpeg"
  }
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "animation",
  "from": "operator",
  "origin": "chat",
  "content": {
    "url": "https://media2.giphy.com/media/3oKIPt3IEJbcqkff7a/100.gif",
    "type": "image/gif"
  }
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "audio",
  "from": "operator",
  "origin": "chat",
  "content": {
    "url": "https://storage.crisp.chat/users/upload/operator/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/d70935e1-c79e-4199-9568-944541657b78.webm",
    "type": "audio/webm",
    "duration": 40
  }
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "picker",
  "from": "operator",
  "origin": "chat",
  "content": {
    "id": "call-date",
    "text": "Pick your date!",
    "choices": [
      {
        "value": "1",
        "label": "Today, 1:00PM.",
        "selected": false
      },
      {
        "value": "2",
        "label": "Friday, 2:30PM.",
        "selected": true
      },
      {
        "value": "3",
        "label": "Monday, 6:15PM.",
        "selected": false
      }
    ]
  }
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "field",
  "from": "operator",
  "origin": "chat",
  "content": {
    "id": "name-field",
    "text": "What is your name?",
    "explain": "Enter your name...",
    "value": "Valerian Saliou"
  }
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "type": "event",
  "from": "operator",
  "origin": "chat",
  "content": {
    "namespace": "reminder:scheduled"
  }
}
Responses202402403404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {
    "fingerprint": 150912675256156
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "subscription_upgrade_required",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Send A Message In Conversation
POST/website/{website_id}/conversation/{session_id}/message

Sends a message in an existing conversation.

  • type (enum[string], required) - Message type

    • Members
      • text
      • note
      • file
      • animation
      • audio
      • picker
      • field
      • event
  • from (enum[string], required) - Message sender

    • Members
      • user
      • operator
  • origin (enum[string], required) - Message origin

    • Members
      • chat
      • email
      • urn:*
  • content (object, required) - Message content (string if type is text or note, object if type is file, animation, audio, picker, field or event)

    • id (string, required) - Object identifier (only set if message type is picker or field)
    • text (string, required) - Object text (only set if message type is picker or field)
    • explain (string, required) - Object explanatory text (only set if message type is field)
    • value (string, optional) - Object value (only set if message type is field)
    • choices (array[object], required) - Object choices (only set if message type is picker)
      • value (string, required) - Choice value
      • label (string, required) - Choice label
      • selected (boolean, required) - Whether choice is selected or not
    • name (string, required) - Object name (only set if message type is file)
    • duration (number, required) - Object duration in seconds (only set if message type is audio)
    • url (string, required) - Object URL (only set if message type is file, animation or audio)
    • type (string, required) - 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)
      • Members
        • reminder:scheduled
        • call:started
        • call:ended
  • mentions (array[string], optional) - Mentioned user identifiers

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

  • user (object, optional) - Sending user information

    • type (string, optional) - Sending user type
      • Members
        • website
    • nickname (string, optional) - Sending user nickname
    • avatar (string, optional) - Sending user avatar
URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The conversation session identifier


GET https://api.crisp.chat/v1/website/website_id/conversation/session_id/message/fingerprint
RequestsGet A Message
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Responses200403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "resolved",
  "data": {
    "session_id": "session_0839e4c2-a059-445b-8de5-390d6417f893",
    "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
    "type": "text",
    "from": "user",
    "origin": "chat",
    "content": "Hey, how are you doing?",
    "preview": [],
    "mentions": [],
    "stamped": true,
    "read": "email",
    "delivered": "email",
    "fingerprint": 5719231201,
    "timestamp": 1468413681043,
    "user": {
      "nickname": "Dan Boy",
      "user_id": "session_0839e4c2-a059-445b-8de5-390d6417f893"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "conversation_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "message_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get A Message In Conversation
GET/website/{website_id}/conversation/{session_id}/message/{fingerprint}

Resolves an existing message in an existing conversation.

  • error (boolean)

  • reason (string)

  • data (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)
      • id (string) - Object identifier (only set if message type is picker or field)
      • text (string) - Object text (only set if message type is picker or field)
      • 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
        • label (string) - Choice label
        • selected (boolean) - Whether choice is selected or not
      • 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)
        • Members
          • reminder:scheduled
          • call:started
          • call:ended
    • 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)
    • mentions (array[string]) - Mentioned user identifiers
    • read (enum[string]) - Channel in which message has been read
      • Members
        • null
        • chat
        • email
    • delivered (enum[string]) - Channel in which message has lastly been delivered
      • Members
        • null
        • chat
        • email
    • 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 (string) - Sending user type (if any)
        • Members
          • website
      • user_id (string) - Sending user identifier (may be operator user identifier or session identifier)
      • nickname (string) - Sending user nickname
      • avatar (string) - Sending user avatar
URI Parameters
HideShow
website_id
string (required) 

The website identifier

session_id
string (required) 

The conversation session identifier

fingerprint
number (required) 

The message fingerprint


PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/message/fingerprint
RequestsUpdate Text MessageUpdate Note MessageUpdate File MessageUpdate Animation MessageUpdate Audio MessageUpdate Picker MessageUpdate Field Message
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "content": "Hey there! Need help?"
}
Responses202400403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_message_content",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "message_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "content": "What should I tell him?"
}
Responses202400403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_message_content",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "message_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "content": {
    "name": "Thats awesome.jpg",
    "url": "https://storage.crisp.chat/users/upload/operator/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/19d956c7-0294-45ad-89e1-58ce45e7008f.jpg",
    "type": "image/jpeg"
  }
}
Responses202400403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_message_content",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "message_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "content": {
    "url": "https://media2.giphy.com/media/3oKIPt3IEJbcqkff7a/100.gif",
    "type": "image/gif"
  }
}
Responses202400403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_message_content",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "message_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}
  • Authenticated Tiers: user plugin
Headers
Content-Type: application/json
Body
{
  "content": {
    "url": "https://storage.crisp.chat/users/upload/operator/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/d70935e1-c79e-4199-9568-944541657b78.webm",
    "type": "audio/webm",
    "duration": 40
  }
}
Responses202400403404404404
Headers
Content-Type: application/json
Body
{
  "error": false,
  "reason": "dispatched",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "invalid_message_content",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "session_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error": true,
  "reason": "message_not_found",
  "data": {}
}
Headers
Content-Type: application/json
Body
{
  "error":