Crisp Platform - API Reference

API Endpoint

https://api.crisp.chat/v1

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

📝 Reference revision: 31/01/2021

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.

go-crisp-api - Crisp API wrapper for Go
node-crisp-api - Crisp API wrapper for NodeJS
php-crisp-api - Crisp API wrapper for PHP
python-crisp-api - Crisp API wrapper for Python
ruby-crisp-api - Crisp API wrapper for Ruby

Authentication

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

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

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:

Go to the Crisp token generation utility and login with a Crisp account
The utility will provide you with 2 keys: identifier and key; keep those keys private!

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

💡 Tip: You may want to create a dedicated Crisp account to generate authentication keys from. For example, that would be the case if you intend to perform generic actions with it. On the other hand, if you want to use the API on behalf of a specific operator, you can stick to this operator’s account.

➡️ 2. Use Your Authentication Keys

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

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

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

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

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

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

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

Edge rate limit (a very permissive rate limit on Crisp edge load balancers; you should not hit against this limit very often)
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)
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.

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",

  // Leave the routing tag to 'null' (you do not need routing there)
  "routing": null,

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

Note that if your API token is a plugin tier token, then you will only have access to the RTM events that your token scopes allow, based on the API routes that you have access to. For instance, if your scope includes messaging features, you will receive events like message:send.

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:sync:rating — User rating was just submitted 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_participants — The list of conversation participants has been updated
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:updated — A people profile was updated
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)

Status Events

status:health:changed — Status page health has changed

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)

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

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.

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.

🤝 Past disclosures: Hely Shah, John Gracey, Haq Khokhar, Sylvain Kerkour (many thanks to them!).

Website ¶

Manages Crisp websites.

💡 Tip: you can obtain your website_id from your Crisp Dashboard. Go to Settings, then Website Settings, and pick your target website in the list. Then, click on Setup instructions and copy your Website ID.

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"
}

Responses201423

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "added",
  "data": {
    "website_id": "e2efddb0-d1ce-47fd-99f5-d3a5b69f1def"
  }
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

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

Body

{
  "verify": "MySuperSecurePassword"
}

Responses200403403404423

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": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "password_unverified",
  "data": {}
}

Delete A Website
DELETE`/website/{website_id}`

Deletes an existing website.

verify (string, required) - User password (used to double-authenticate deletion)

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=&search_operator=&include_empty=&filter_unread=&filter_resolved=&filter_not_resolved=&filter_mention=&filter_assigned=&filter_unassigned=&filter_date_start=&filter_date_end=&order_date_created=&order_date_updated=

RequestsList Conversations

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:sessions

Headers

Content-Type: application/json

Responses200206400402403404423

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": [],
      "participants": [
        {
          "type": "email",
          "target": "jane.doe@acme-inc.com"
        }
      ],
      "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": [],
      "participants": [
        {
          "type": "email",
          "target": "jane.doe@acme-inc.com"
        }
      ],
      "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": "search_query_too_long",
  "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": "quota_limit_exceeded",
  "data": {}
}

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

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
- participants (array[object]) - External participants for this conversation
  - type (enum[string]) - External participant type
    - Members
      - email
  - target (string) - External participant target (ie. email address, identifier, etc.)
- mentions (array[string]) - Mentioned user identifiers (from conversation messages)
- created_at (number) - Conversation creation timestamp
- updated_at (number) - Conversation update timestamp
- 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 (text if type is text or segment, filter if type is filter)
search_type: string (optional)
Search type (either text, segment or filter)
search_operator: string (optional)
Search operator if search type is filter (or or and respectful to boolean algebra, defaults to and if not set)
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_resolved: string (optional)
Whether to return only conversations that are resolved (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 identifier
filter_unassigned: string (optional)
Whether to return only conversations that are not assigned to any user (1 or 0, defaults to 0)
filter_date_start: string (optional)
When to start relative to conversation creation date (date, ISO 8601, eg. 2018-03-01T17:00:00.000Z)
filter_date_end: string (optional)
When to end relative to conversation creation date (date, ISO 8601, eg. 2018-04-01T10:30:00.000Z)
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/suggest/segments/page_number

RequestsSuggest Conversation Segments

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:suggest

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 Suggested Conversation Segments
GET`/website/{website_id}/conversations/suggest/segments/{page_number}`

Lists suggested conversation segments 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)

GET https://api.crisp.chat/v1/website/website_id/conversations/suggest/data/page_number

RequestsSuggest Conversation Data Keys

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:suggest

Headers

Content-Type: application/json

Responses200206403404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "key": "plan",
      "count": 93
    },
    {
      "key": "price",
      "count": 12
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "key": "plan",
      "count": 93
    },
    {
      "key": "price",
      "count": 12
    }
  ]
}

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 Suggested Conversation Data Keys
GET`/website/{website_id}/conversations/suggest/data/{page_number}`

Lists suggested conversation data keys for website.

error (boolean)
reason (string)
data (array[object])
- key (string) - Data key value
- count (number) - Number of occurences of this data key

URI Parameters

HideShow

website_id: string (required)
The website identifier
page_number: number (optional)
The page number (paging in data 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
Plugin Scope Required: website:conversation:initiate

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
Plugin Scope Required: website:conversation:sessions

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
Plugin Scope Required: website:conversation:sessions

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": [],
    "participants": [
      {
        "type": "email",
        "target": "jane.doe@acme-inc.com"
      }
    ],
    "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)
- participants (array[object]) - External participants for this conversation
  - type (enum[string]) - External participant type
    - Members
      - email
  - target (string) - External participant target (ie. email address, identifier, etc.)
- 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
Plugin Scope Required: website:conversation:sessions

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
Plugin Scope Required: website:conversation:initiate

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
Plugin Scope Required: website:conversation:messages

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, field or event)
  - explain (string) - Object explanatory text (only set if message type is field)
  - value (string) - Object value (only set if message type is field)
  - choices (array[object]) - Object choices (only set if message type is picker)
    - value (string) - Choice value
    - 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
      - state:resolved
      - user:blocked
      - reminder:scheduled
      - thread:started
      - thread:ended
      - participant:added
      - participant:removed
      - 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)
- edited (boolean) - Whether message was edited after being sent or not
- translated (boolean) - Whether message was auto-translated or not
- 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
      - participant
  - user_id (string) - Sending user identifier (may be operator user identifier or session identifier)
  - nickname (string) - Sending user nickname
  - avatar (string) - Sending user avatar
- original (object) - Original message data (if any)
  - original_id (string) - Original identifier

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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, field or event)
- 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
    - state:resolved
    - user:blocked
    - reminder:scheduled
    - thread:started
    - thread:ended
    - participant:added
    - participant:removed
    - 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
    - participant
- nickname (string, optional) - Sending user nickname
- avatar (string, optional) - Sending user avatar
original (object, optional) - Original message data (if set, original data will then be available on a separate route)
- type (string, required) - Original message data MIME type
  - Members
    - text/html
- content (string, required) - Original message data content
translated (boolean, optional) - Whether message was auto-translated or not

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
Plugin Scope Required: website:conversation:messages

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, field or event)
  - explain (string) - Object explanatory text (only set if message type is field)
  - value (string) - Object value (only set if message type is field)
  - choices (array[object]) - Object choices (only set if message type is picker)
    - value (string) - Choice value
    - 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
      - state:resolved
      - user:blocked
      - reminder:scheduled
      - thread:started
      - thread:ended
      - participant:added
      - participant:removed
      - 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)
- edited (boolean) - Whether message was edited after being sent or not
- translated (boolean) - Whether message was auto-translated or not
- 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
      - participant
  - user_id (string) - Sending user identifier (may be operator user identifier or session identifier)
  - nickname (string) - Sending user nickname
  - avatar (string) - Sending user avatar
- original (object) - Original message data (if any)
  - original_id (string) - Original identifier

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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
Plugin Scope Required: website:conversation:messages

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": true,
  "reason": "not_subscribed",
  "data": {}
}

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:messages

Headers

Content-Type: application/json

Body

{
  "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
      }
    ]
  }
}

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
Plugin Scope Required: website:conversation:messages

Headers

Content-Type: application/json

Body

{
  "content": {
    "id": "name-field",
    "text": "What is your name?",
    "explain": "Enter your name...",
    "value": "Valerian Saliou"
  }
}

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": {}
}

Update A Message In Conversation
PATCH`/website/{website_id}/conversation/{session_id}/message/{fingerprint}`

Edits an existing message in an existing conversation.

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

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, field or event)
- 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
    - state:resolved
    - user:blocked
    - reminder:scheduled
    - thread:started
    - thread:ended
    - participant:added
    - participant:removed
    - call:started
    - call:ended

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
fingerprint: number (required)
The edited message fingerprint

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/compose

RequestsSend Compose

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:messages

Headers

Content-Type: application/json

Body

{
  "type": "start",
  "from": "operator"
}

Responses202403404404

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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Compose A Message In Conversation
PATCH`/website/{website_id}/conversation/{session_id}/compose`

Starts or stop composing a message in an existing conversation.

type (enum[string], required) - Compose type
- Members
  - start
  - stop
from (enum[string], required) - Compose sender
- Members
  - user
  - operator
excerpt (string, optional) - Compose excerpt (MagicType preview)
stealth (boolean, optional) - Compose stealth mode (ie. do not propagate compose to the other party)

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/read

RequestsMark Read

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:messages

Headers

Content-Type: application/json

Body

{
  "from": "operator",
  "origin": "urn:crisp.im:slack:0",
  "fingerprints": [
    "5719231201"
  ]
}

Responses202403404404

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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Mark Messages As Read In Conversation
PATCH`/website/{website_id}/conversation/{session_id}/read`

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

from (enum[string], required) - Sender direction
- Members
  - user
  - operator
origin (enum[string], required) - Read receipt origin
- Members
  - chat
  - email
  - urn:*
fingerprints (array[number], optional) - Target message fingerprints (if not set, this marks all messages as read in conversation)

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/delivered

RequestsMark Delivered

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:messages

Headers

Content-Type: application/json

Body

{
  "from": "operator",
  "origin": "urn:crisp.im:slack:0",
  "fingerprints": [
    "5719231201"
  ]
}

Responses202403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "delivered",
  "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": {}
}

Mark Messages As Delivered In Conversation
PATCH`/website/{website_id}/conversation/{session_id}/delivered`

Marks messages as delivered in conversation.

from (enum[string], required) - Sender direction
- Members
  - operator
origin (enum[string], required) - Delivered receipt origin
- Members
  - chat
  - email
  - urn:*
fingerprints (array[number], required) - Target message fingerprints

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/open

RequestsSet Conversation Opened

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:actions

Headers

Content-Type: application/json

Body

{
  "opened": true
}

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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Update Conversation Open State
PATCH`/website/{website_id}/conversation/{session_id}/open`

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

opened (boolean, required) - Open state

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/routing

RequestsGet Assigned

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:routing

Headers

Content-Type: application/json

Responses200402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "assigned": {
      "user_id": "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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get Conversation Routing Assign
GET`/website/{website_id}/conversation/{session_id}/routing`

Resolves assigned operator for conversation routing.

error (boolean)
reason (string)
data (object)
- assigned (object) - Assigned operator (if any)
  - user_id (string) - Operator user identifier

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/routing

RequestsAssign Routing

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:routing

Headers

Content-Type: application/json

Body

{
  "assigned": {
    "user_id": "a4c32c68-be91-4e29-8a05-976e93abbe3f"
  }
}

Responses200402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "assigned",
  "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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Assign Conversation Routing
PATCH`/website/{website_id}/conversation/{session_id}/routing`

Assigns conversation routing to an operator, or unassign.

assigned (object, required) - Assigned operator (set to blank value for none)
- user_id (string, required) - Operator user identifier

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/meta

RequestsGet Metas

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:sessions

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "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 Conversation Metas
GET`/website/{website_id}/conversation/{session_id}/meta`

Resolves conversation meta information.

error (boolean)
reason (string)
data (object)
- 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

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/meta

RequestsUpdate Metas

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:sessions

Headers

Content-Type: application/json

Body

{
  "nickname": "John Doe",
  "email": "john.doe@acme-inc.com",
  "segments": [
    "happy",
    "customer",
    "love"
  ],
  "data": {
    "type": "customer",
    "signup": "finished"
  }
}

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": "conversation_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Update Conversation Metas
PATCH`/website/{website_id}/conversation/{session_id}/meta`

Updates conversation meta information.

nickname (string, optional) - Visitor nickname
email (string, optional) - Visitor email
avatar (string, optional) - Visitor avatar
ip (string, optional) - Visitor IP address
data (object, optional) - Visitor data
phone (string, optional) - Visitor phone number
address (string, optional) - Visitor address
segments (array[string], optional) - Segments for conversation
device (object, optional) - Visitor device information
- capabilities (array[enum[string]], optional) - Visitor device capabilities
  - Members
    - browsing
    - call
- geolocation (object, optional) - Geolocation information for visitor device
  - country (string, optional) - Country code (can be blank)
  - region (string, optional) - Region code (can be blank)
  - city (string, optional) - City name (can be blank)
  - coordinates (object, required) - Location coordinates
    - latitude (number, required) - Latitude coordinate
    - longitude (number, required) - Longitude coordinate
- system (object, optional) - Visitor device system information
  - os (object, optional) - Operating system information
    - version (string, required) - OS version
    - name (string, required) - OS name
  - engine (object, optional) - Rendering engine information
    - version (string, required) - Engine version
    - name (string, required) - Engine name
  - browser (object, optional) - Browser information
    - major (string, required) - Browser major version (eg: version 8.1 has a major of 8)
    - version (string, required) - Browser version
    - name (string, required) - Browser name
  - useragent (string, required) - Visitor user agent
- timezone (number, optional) - Visitor device timezone offset (UTC)
- locales (array[string], optional) - Visitor device locales

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/original/original_id

RequestsGet An Original Message

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:messages

Headers

Content-Type: application/json

Responses200403404404410

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
    "session_id": "session_0839e4c2-a059-445b-8de5-390d6417f893",
    "original_id": "448817d7-50cb-4306-88b3-06721f449c65",
    "type": "text/html",
    "content": "<html><body><p>Hello, what's up?</p><p><em>Cheers, Valerian.</em></p></body></html>",
    "timestamp": 1468413681043
  }
}

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": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "original_vanished",
  "data": {}
}

Get An Original Message In Conversation
GET`/website/{website_id}/conversation/{session_id}/original/{original_id}`

Resolves an existing original message in an existing conversation.

error (boolean)
reason (string)
data (object)
- website_id (string) - Website identifier
- session_id (string) - Session identifier
- original_id (string) - Original identifier
- type (string) - Original message data MIME type
  - Members
    - text/html
- content (string) - Original message data content
- timestamp (number) - Timestamp at which the original was stored

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
original_id: string (required)
The original identifier

GET https://api.crisp.chat/v1/website/website_id/conversation/session_id/pages/page_number

RequestsList Pages

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:pages

Headers

Content-Type: application/json

Responses200206403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "timestamp": 1468341926143,
      "page_title": "Acme Inc. | Marketplace",
      "page_url": "https://shop.acme-inc.com/",
      "page_referrer": "https://www.acme-inc.com/"
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "timestamp": 1468341926143,
      "page_title": "Acme Inc. | Marketplace",
      "page_url": "https://shop.acme-inc.com/",
      "page_referrer": "https://www.acme-inc.com/"
    },
    {
      "timestamp": 1468341867516,
      "page_title": "Acme Inc. | Website",
      "page_url": "https://www.acme-inc.com/",
      "page_referrer": "https://email.acme-inc.com/"
    }
  ]
}

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": {}
}

List Conversation Pages
GET`/website/{website_id}/conversation/{session_id}/pages/{page_number}`

Lists browsed pages in conversation.

error (boolean)
reason (string)
data (array[object])
- page_title (string) - Page title as seen by visitor browser
- page_url (string) - Page URL
- page_referrer (string) - Page referrer (if any)
- timestamp (number) - Timestamp of page access (when the page was loaded)

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
page_number: number (optional)
The page number (paging in page list)

GET https://api.crisp.chat/v1/website/website_id/conversation/session_id/events/page_number

RequestsList Events

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:events

Headers

Content-Type: application/json

Responses200206403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "timestamp": 1468341926143,
      "text": "Added item to basket",
      "data": {
        "price": 10.99,
        "currency": "USD"
      },
      "color": "red"
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "timestamp": 1468341926143,
      "text": "Added item to basket",
      "data": {
        "price": 10.99,
        "currency": "USD"
      },
      "color": "red"
    },
    {
      "timestamp": 1468341867516,
      "text": "Signed up",
      "data": {},
      "color": "blue"
    }
  ]
}

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": {}
}

List Conversation Events
GET`/website/{website_id}/conversation/{session_id}/events/{page_number}`

Lists stacked events in conversation.

error (boolean)
reason (string)
data (array[object])
- text (string) - Text for event
- data (object) - Data for event (if any)
- color (enum[string]) - Color for event (if any)
  - Members
    - red
    - orange
    - yellow
    - green
    - blue
    - purple
    - pink
    - brown
    - grey
    - black
- timestamp (number) - Timestamp of event (when the event was stacked)

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
page_number: number (optional)
The page number (paging in event list)

GET https://api.crisp.chat/v1/website/website_id/conversation/session_id/state

RequestsGet State

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:states

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "state": "unresolved"
  }
}

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 Conversation State
GET`/website/{website_id}/conversation/{session_id}/state`

Resolves conversation state.

error (boolean)
reason (string)
data (object)
- state (enum[string]) - Conversation state
  - Members
    - pending
    - unresolved
    - resolved

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/state

RequestsUnresolve Conversation

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:states

Headers

Content-Type: application/json

Body

{
  "state": "unresolved"
}

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": "conversation_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Change Conversation State
PATCH`/website/{website_id}/conversation/{session_id}/state`

Updates conversation state.

state (enum[string], required) - Conversation state
- Members
  - pending
  - unresolved
  - resolved

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/participants

RequestsResolve Participants

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:participants

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "participants": [
      {
        "type": "email",
        "target": "jane.doe@acme-inc.com"
      }
    ]
  }
}

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 Conversation Participants
GET`/website/{website_id}/conversation/{session_id}/participants`

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

error (boolean)
reason (string)
data (object)
- participants (array[object]) - External participants for conversation
  - type (enum[string]) - External participant type
    - Members
      - email
  - target (string) - External participant target (ie. email address, identifier, etc.)

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PUT https://api.crisp.chat/v1/website/website_id/conversation/session_id/participants

RequestsSave Participants

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:participants

Headers

Content-Type: application/json

Body

{
  "participants": [
    {
      "type": "email",
      "target": "jane.doe@acme-inc.com"
    }
  ]
}

Responses200402403404404425

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": "conversation_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "session_email_required",
  "data": {}
}

Save Conversation Participants
PUT`/website/{website_id}/conversation/{session_id}/participants`

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

participants (array[object], required) - External participants for conversation
- type (enum[string], required) - External participant type
  - Members
    - email
- target (string, required) - External participant target (ie. email address, identifier, etc.)

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/block

RequestsGet Visitor Block Status

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:actions

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "blocked": true
  }
}

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 Block Status For Conversation
GET`/website/{website_id}/conversation/{session_id}/block`

Resolves conversation block status.

error (boolean)
reason (string)
data (object)
- blocked (boolean) - Block state

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/block

RequestsBlock Visitor

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:actions

Headers

Content-Type: application/json

Body

{
  "blocked": true
}

Responses200402403404404

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": "conversation_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Block Incoming Messages For Conversation
PATCH`/website/{website_id}/conversation/{session_id}/block`

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

blocked (boolean, required) - Block state

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/transcript

RequestsRequest Email Transcript

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:actions

Headers

Content-Type: application/json

Body

{
  "to": "operator",
  "email": "valerian@crisp.chat"
}

Responses202403404404404412423

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": "conversation_not_found",
  "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": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "email_not_available",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

Request Email Transcript For Conversation
POST`/website/{website_id}/conversation/{session_id}/transcript`

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

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

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/purge

RequestsRequest Chatbox Purge

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:actions

Headers

Content-Type: application/json

Body

{}

Responses202403404404412

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": "conversation_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "session_not_online",
  "data": {}
}

Request Chatbox Binding Purge For Conversation
POST`/website/{website_id}/conversation/{session_id}/purge`

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

URI Parameters

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/browsing

RequestsList Available Browsing Sessions

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:browsing

Headers

Content-Type: application/json

Responses200402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "browsing_id": "browsing_05a9392d-ff3f-45e7-b021-1179c45668fa",
      "browsing_token": "9cbb95ab83be4c3f",
      "useragent": "Mozilla/5.0 (Windows NT 6.2; rv:20.0) Gecko/20121202 Firefox/20.0"
    },
    {
      "browsing_id": "browsing_19f4a6b4-1263-4e1a-965c-57ba9ef72151",
      "browsing_token": "a17f332049e14519",
      "useragent": "Mozilla/5.0 (Windows NT 6.2; rv:20.0) Gecko/20121202 Firefox/20.0"
    }
  ]
}

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": {}
}

List Browsing Sessions For Conversation
GET`/website/{website_id}/conversation/{session_id}/browsing`

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

error (boolean)
reason (string)
data (array[object])
- browsing_id (string) - Browsing session identifier
- browsing_token (string) - Browsing token (used to authenticate cross-channel requests, eg. to the HTTP proxy)
- useragent (string) - Useragent for browsing session

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/browsing

RequestsInitiate Browsing Session

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:browsing

Headers

Content-Type: application/json

Responses201402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "initiated",
  "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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Initiate Browsing Session For Conversation
POST`/website/{website_id}/conversation/{session_id}/browsing`

Initiates browsing session for conversation.

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

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

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/browsing/browsing_id

RequestsSend Start Action To Browsing Session

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:browsing

Headers

Content-Type: application/json

Body

{
  "action": "start"
}

Responses202402403404404404

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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "browsing_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Send Action To An Existing Browsing Session
PATCH`/website/{website_id}/conversation/{session_id}/browsing/{browsing_id}`

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

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

action (enum[string], required) - Browsing action
- Members
  - start
  - stop
  - heartbeat

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
browsing_id: string (required)
The browsing session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/browsing/browsing_id/debug

RequestsSend Debug Execute To Browsing Session

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:browsing

Headers

Content-Type: application/json

Body

{
  "action": "execute",
  "execute": "alert('Remote JavaScript executed');"
}

Responses202402403404404404

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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "browsing_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Debug An Existing Browsing Session
PATCH`/website/{website_id}/conversation/{session_id}/browsing/{browsing_id}/debug`

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

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

action (enum[string], required) - Debug action
- Members
  - start
  - stop
  - heartbeat
  - execute
execute (string, optional) - JavaScript code to execute in browsing session (action must be execute)

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
browsing_id: string (required)
The browsing session identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/browsing/browsing_id/assist

RequestsSend Assist Mouse To Browsing Session

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:browsing

Headers

Content-Type: application/json

Body

{
  "action": "mouse",
  "mouse": {
    "x": 0,
    "y": 784
  }
}

Responses202402403404404404

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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "browsing_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Assist An Existing Browsing Session
PATCH`/website/{website_id}/conversation/{session_id}/browsing/{browsing_id}/assist`

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

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

action (enum[string], required) - Assist action
- Members
  - start
  - stop
  - heartbeat
  - mouse
  - scroll
  - click
mouse (object, optional) - Mouse position for assist cursor in browsing session (action must be mouse)
- x (number, required) - Mouse cursor horizontal position
- y (number, required) - Mouse cursor vertical position
click (object, optional) - Click target for assist cursor in browsing session (action must be click)
- x (number, required) - Click cursor horizontal position
- y (number, required) - Click cursor vertical position
scroll (object, optional) - Scroll position for assist scroll wheel in browsing session (action must be scroll)
- x (number, required) - Scroll wheel horizontal position
- y (number, required) - Scroll wheel vertical position

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
browsing_id: string (required)
The browsing session identifier

POST https://api.crisp.chat/v1/website/website_id/conversation/session_id/call

RequestsInitiate New Call Session

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:calls

Headers

Content-Type: application/json

Body

{
  "mode": "audio"
}

Responses201402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "initiated",
  "data": {
    "call_id": "call_35a0c062-72fa-4095-a2a0-f9911d47ee56"
  }
}

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": {}
}

Initiate New Call Session For Conversation
POST`/website/{website_id}/conversation/{session_id}/call`

Initiates a new audio/video call session for conversation.

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

mode (string, required) - Mode of the call to start
- Members
  - video
  - audio

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/call

RequestsGet Ongoing Call Session

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:calls

Headers

Content-Type: application/json

Responses200402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "call_id": "call_35a0c062-72fa-4095-a2a0-f9911d47ee56"
  }
}

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": {}
}

Get Ongoing Call Session For Conversation
GET`/website/{website_id}/conversation/{session_id}/call`

Gets the ongoing audio/video call session for conversation.

error (boolean)
reason (string)
data (object)
- call_id (string) - Call session identifier (if any call ongoing)

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/call/call_id

RequestsAbort Ongoing Call Session

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:calls

Headers

Content-Type: application/json

Responses200402403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "aborted",
  "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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "call_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Abort Ongoing Call Session For Conversation
DELETE`/website/{website_id}/conversation/{session_id}/call/{call_id}`

Aborts the ongoing audio/video call session for conversation.

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
call_id: string (required)
The call identifier

PATCH https://api.crisp.chat/v1/website/website_id/conversation/session_id/call/call_id/signaling

RequestsTransmit Signaling Payload

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:calls

Headers

Content-Type: application/json

Responses202402403404404404

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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "call_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Transmit Signaling On Ongoing Call Session
PATCH`/website/{website_id}/conversation/{session_id}/call/{call_id}/signaling`

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

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

type (string, required) - Signaling type to transmit
- Members
  - sdp
  - candidate
payload (object, required) - Signaling payload to transmit

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier
call_id: string (required)
The call identifier

POST https://api.crisp.chat/v1/website/website_id/conversation/session_id/reminder

RequestsSchedule Reminder

Authenticated Tiers: user plugin
Plugin Scope Required: website:conversation:reminders

Headers

Content-Type: application/json

Body

{
  "date": "2018-05-29T09:00:00Z",
  "note": "Call this customer."
}

Responses201400400400402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "scheduled",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "date_in_past",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "date_too_far_in_future",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "date_too_soon",
  "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": "session_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Schedule A Reminder For Conversation
POST`/website/{website_id}/conversation/{session_id}/reminder`

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

date (string, required) - Date in the future at which you want to be reminded (ISO 8601)
note (string, required) - Note message to be sent as a reminder

URI Parameters

HideShow

website_id: string (required)
The website identifier
session_id: string (required)
The conversation session identifier

Website People ¶

Manages website people.

GET https://api.crisp.chat/v1/website/website_id/people/stats

RequestsGet People Statistics

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:statistics

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",

  "data": {
    {
      "total": 432
    }
  }
}

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": "not_subscribed",
  "data": {}
}

Get People Statistics
GET`/website/{website_id}/people/stats`

Resolves statistics on people in website.

error (boolean)
reason (string)
data (object)
- total (number) - Total number of people

URI Parameters

HideShow

website_id: string (required)
The website identifier

GET https://api.crisp.chat/v1/website/website_id/people/suggest/segments/page_number

RequestsSuggest People Segments

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:suggest

Headers

Content-Type: application/json

Responses200206402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "segment": "customer",
      "count": 214
    },
    {
      "segment": "poweruser",
      "count": 121
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "segment": "customer",
      "count": 214
    },
    {
      "segment": "poweruser",
      "count": 121
    }
  ]
}

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": "not_subscribed",
  "data": {}
}

List Suggested People Segments
GET`/website/{website_id}/people/suggest/segments/{page_number}`

Lists suggested segments for people.

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)

GET https://api.crisp.chat/v1/website/website_id/people/suggest/data/page_number

RequestsSuggest People Data Keys

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:suggest

Headers

Content-Type: application/json

Responses200206402403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "key": "plan",
      "count": 93
    },
    {
      "key": "price",
      "count": 12
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "key": "plan",
      "count": 93
    },
    {
      "key": "price",
      "count": 12
    }
  ]
}

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": "not_subscribed",
  "data": {}
}

List Suggested People Data Keys
GET`/website/{website_id}/people/suggest/data/{page_number}`

Lists suggested data keys for people.

error (boolean)
reason (string)
data (array[object])
- key (string) - Data key value
- count (number) - Number of occurences of this data key

URI Parameters

HideShow

website_id: string (required)
The website identifier
page_number: number (optional)
The page number (paging in data list)

GET https://api.crisp.chat/v1/website/website_id/people/profiles/page_number?sort_field=&sort_order=&search_operator=&search_filter=&search_text=&filter_date_start=&filter_date_end=

RequestsList People Profiles

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:profiles

Headers

Content-Type: application/json

Responses200206403404404423

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "people_id": "c5a2f70c-f605-4648-b47f-8c39d4b03a50",
      "email": "valerian@crisp.chat",
      "person": {
        "nickname": "Valerian Saliou",
        "gender": "male",
        "phone": "+33757905447",
        "address": "France",
        "description": "Full Stack Developer & UI Designer - XMPP Technologist - Objectivist - Co-founder CTO @crisp_im",
        "website": "https://valeriansaliou.name/",
        "timezone": -120,
        "profiles": [
          {
            "type": "github",
            "handle": "valeriansaliou"
          }
        ],
        "employment": {
          "name": "Crisp",
          "domain": "crisp.chat",
          "title": "CTO",
          "role": "Software Engineer",
          "seniority": "lead"
        },
        "geolocation": {
          "country": "LV",
          "region": "Rīga",
          "city": "Rīga",
          "coordinates": {
            "latitude": 56.9553,
            "longitude": 24.1195
          }
        },
        "locales": [
          "fr",
          "fr-FR",
          "en",
          "en-US"
        ]
      },
      "company": {
        "name": "Crisp",
        "legal_name": "Crisp IM SARL",
        "domain": "crisp.chat",
        "url": "https://crisp.chat/",
        "description": "Crisp is the best way to chat with your website visitors. Add it on your website in 2 minutes and start increasing your sales!",
        "timezone": -300,
        "metrics": {
          "employees": 4,
          "market_cap": 0,
          "raised": 0,
          "arr": 0
        },
        "geolocation": {
          "country": "FR",
          "region": "29",
          "city": "Brest",
          "coordinates": {
            "latitude": 48.3908,
            "longitude": -4.4703
          }
        },
        "tags": [
          "chat",
          "saas"
        ],
        "phones": [],
        "emails": [
          "contact@crisp.chat",
          "support@crisp.chat"
        ]
      },
      "segments": [
        "love",
        "poweruser"
      ],
      "notepad": "",
      "active": {
        "now": false
      },
      "created_at": 1468341857826,
      "updated_at": 1468401603070
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "people_id": "c5a2f70c-f605-4648-b47f-8c39d4b03a50",
      "email": "valerian@crisp.chat",
      "person": {
        "nickname": "Valerian Saliou",
        "gender": "male",
        "phone": "+33757905447",
        "address": "France",
        "description": "Full Stack Developer & UI Designer - XMPP Technologist - Objectivist - Co-founder CTO @crisp_im",
        "website": "https://valeriansaliou.name/",
        "timezone": -120,
        "profiles": [
          {
            "type": "github",
            "handle": "valeriansaliou"
          }
        ],
        "employment": {
          "name": "Crisp",
          "domain": "crisp.chat",
          "title": "CTO",
          "role": "Software Engineer",
          "seniority": "lead"
        },
        "geolocation": {
          "country": "LV",
          "region": "Rīga",
          "city": "Rīga",
          "coordinates": {
            "latitude": 56.9553,
            "longitude": 24.1195
          }
        },
        "locales": [
          "fr",
          "fr-FR",
          "en",
          "en-US"
        ]
      },
      "company": {
        "name": "Crisp",
        "legal_name": "Crisp IM SARL",
        "domain": "crisp.chat",
        "url": "https://crisp.chat/",
        "description": "Crisp is the best way to chat with your website visitors. Add it on your website in 2 minutes and start increasing your sales!",
        "timezone": -300,
        "metrics": {
          "employees": 4,
          "market_cap": 0,
          "raised": 0,
          "arr": 0
        },
        "geolocation": {
          "country": "FR",
          "region": "29",
          "city": "Brest",
          "coordinates": {
            "latitude": 48.3908,
            "longitude": -4.4703
          }
        },
        "tags": [
          "chat",
          "saas"
        ],
        "phones": [],
        "emails": [
          "contact@crisp.chat",
          "support@crisp.chat"
        ]
      },
      "segments": [
        "love",
        "poweruser"
      ],
      "active": {
        "now": false
      },
      "created_at": 1468341857826,
      "updated_at": 1468401603070
    }
  ]
}

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": "not_subscribed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

List People Profiles
GET`/website/{website_id}/people/profiles/{page_number}{?sort_field}{&sort_order}{&search_operator}{&search_filter}{&search_text}{&filter_date_start}{&filter_date_end}`

Lists people profiles for website.

error (boolean)
reason (string)
data (array[object])
- people_id (string) - People identifier
- email (string) - Email for people profile
- person (object) - Personal information
  - nickname (string) - Nickname for user (includes first name and last name)
  - avatar (string) - Avatar for user
  - gender (string) - Gender for user
    - Members
      - male
      - female
  - phone (string) - Phone number for user
  - address (string) - Address for user
  - description (string) - Description for user
  - website (string) - Website of user
  - timezone (number) - Timezone offset of user (UTC)
  - profiles (array[object]) - Online profiles for user
    - type (string) - Profile type (eg: facebook, twitter)
    - handle (string) - User handle on online platform
    - url (string) - URL for the profile
  - employment (object) - Employment information for user
    - name (string) - Company name
    - domain (string) - Company domain name
    - title (string) - User title in company
    - role (string) - User role in company
    - seniority (string) - User seniority in company
  - geolocation (object) - Geolocation information for user
    - country (string) - Country code
    - region (string) - Region code
    - city (string) - City name
    - coordinates (object) - Location coordinates
      - latitude (number) - Latitude coordinate
      - longitude (number) - Longitude coordinate
  - locales (array[string]) - Locales supported by user (ISO 639-1)
- company (object) - Company information
  - name (string) - Company name
  - legal_name (string) - Company legal name
  - domain (string) - Company domain name
  - url (string) - Company website URL
  - description (string) - Company description
  - timezone (number) - Company timezone offset (UTC)
  - phones (array[string]) - Company phone numbers
  - emails (array[string]) - Company email addresses
  - geolocation (object) - Company location
    - country (string) - Country code
    - region (string) - Region code
    - city (string) - City name
    - coordinates (object) - Location coordinates
      - latitude (number) - Latitude coordinate
      - longitude (number) - Longitude coordinate
  - metrics (object) - Metrics for company
    - employees (number) - Number of employees
    - market_cap (number) - Market capitalization
    - raised (number) - Money raised
    - arr (number) - Annual Recurring Revenue
  - tags (array[string]) - Tags for company
- segments (array[string]) - Segments attributed to people profile
- notepad (string) - Private notepad on people profile
- active (object) - User activity statistics (based on last active session from user)
  - now (boolean) - Whether user is considered active right now or not
  - last (number) - Timestamp at which the user was last active
- score (number) - Score associated to this profile, from 1 to 5 (based on ratings from user)
- created_at (number) - Profile creation timestamp
- updated_at (number) - Profile update timestamp

URI Parameters

HideShow

website_id: string (required)
The website identifier
page_number: number (optional)
Page number for people paging
sort_field: string (optional)
Sort on field (based on available search field names)
sort_order: string (optional)
Sort order (ascending or descending)
search_operator: string (optional)
Search operator (or or and respectful to boolean algebra, defaults to and if not set)
search_filter: string (optional)
Search filter (object filter mapped as string)
search_text: string (optional)
Search text (text for a quick search)
filter_date_start: string (optional)
When to start relative to profile creation date (date, ISO 8601)
filter_date_end: string (optional)
When to end relative to profile creation date (date, ISO 8601)

POST https://api.crisp.chat/v1/website/website_id/people/profile

RequestsCreate A New People Profile

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:profiles

Headers

Content-Type: application/json

Body

{
  "email": "valerian@crisp.chat",
  "person": {
    "nickname": "Valerian Saliou"
  }
}

Responses201402403404404409

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "added",
  "data": {
    "people_id": "c5a2f70c-f605-4648-b47f-8c39d4b03a50"
  }
}

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": "not_subscribed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_exists",
  "data": {}
}

Add New People Profile
POST`/website/{website_id}/people/profile`

Adds a new people profile.

email (string, required) - Email for people profile
person (object, required) - Personal information
- nickname (string, required) - Nickname for user (includes first name and last name)
- avatar (string, optional) - Avatar for user
- gender (string, optional) - Gender for user
  - Members
    - male
    - female
- phone (string, optional) - Phone number for user
- address (string, optional) - Address for user
- description (string, optional) - Description for user
- website (string, optional) - Website of user
- timezone (number, optional) - Timezone offset of user (UTC)
- profiles (array[object], optional) - Online profiles for user
  - type (string, required) - Profile type (eg: facebook, twitter)
  - handle (string, optional) - User handle on online platform
  - url (string, required) - URL for the profile
- employment (object, optional) - Employment information for user
  - name (string, required) - Company name
  - domain (string, optional) - Company domain name
  - title (string, optional) - User title in company
  - role (string, optional) - User role in company
  - seniority (string, optional) - User seniority in company
- geolocation (object, optional) - Geolocation information for user
  - country (string, optional) - Country code (can be blank)
  - region (string, optional) - Region code (can be blank)
  - city (string, optional) - City name (can be blank)
  - coordinates (object, optional) - Location coordinates
    - latitude (number, required) - Latitude coordinate
    - longitude (number, required) - Longitude coordinate
- locales (array[string], optional) - Locales supported by user (ISO 639-1)
company (object, optional) - Company information
- name (string, required) - Company name
- legal_name (string, optional) - Company legal name
- domain (string, optional) - Company domain name
- url (string, optional) - Company website URL
- description (string, optional) - Company description
- timezone (number, optional) - Company timezone offset (UTC)
- phones (array[string], optional) - Company phone numbers
- emails (array[string], optional) - Company email addresses
- geolocation (object, optional) - Company location
  - country (string, optional) - Country code (can be blank)
  - region (string, optional) - Region code (can be blank)
  - city (string, optional) - City name (can be blank)
  - coordinates (object, optional) - Location coordinates
    - latitude (number, required) - Latitude coordinate
    - longitude (number, required) - Longitude coordinate
- metrics (object, optional) - Metrics for company
  - employees (number, optional) - Number of employees
  - market_cap (number, optional) - Market capitalization
  - raised (number, optional) - Money raised
  - arr (number, optional) - Annual Recurring Revenue
- tags (array[string], optional) - Tags for company
segments (array[string], optional) - Segments attributed to people profile
notepad (string, optional) - Private notepad on people profile

URI Parameters

HideShow

website_id: string (required)
The website identifier

HEAD https://api.crisp.chat/v1/website/website_id/people/profile/people_id

RequestsCheck If People Profile Exists

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:profiles

Headers

Content-Type: application/json

Responses200403404

Headers

Content-Type: application/json

Headers

Content-Type: application/json

Headers

Content-Type: application/json

Check If People Profile Exists
HEAD`/website/{website_id}/people/profile/{people_id}`

Checks if given people profile exists.

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

GET https://api.crisp.chat/v1/website/website_id/people/profile/people_id

RequestsGet People Profile

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:profiles

Headers

Content-Type: application/json

Responses200403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "people_id": "c5a2f70c-f605-4648-b47f-8c39d4b03a50",
    "email": "valerian@crisp.chat",
    "person": {
      "nickname": "Valerian Saliou",
      "gender": "male",
      "phone": "+33757905447",
      "address": "France",
      "description": "Full Stack Developer & UI Designer - XMPP Technologist - Objectivist - Co-founder CTO @crisp_im",
      "website": "https://valeriansaliou.name/",
      "timezone": -120,
      "profiles": [
        {
          "type": "github",
          "handle": "valeriansaliou"
        }
      ],
      "employment": {
        "name": "Crisp",
        "domain": "crisp.chat",
        "title": "CTO",
        "role": "Software Engineer",
        "seniority": "lead"
      },
      "geolocation": {
        "country": "LV",
        "region": "Rīga",
        "city": "Rīga",
        "coordinates": {
          "latitude": 56.9553,
          "longitude": 24.1195
        }
      },
      "locales": [
        "fr",
        "fr-FR",
        "en",
        "en-US"
      ]
    },
    "company": {
      "name": "Crisp",
      "legal_name": "Crisp IM SARL",
      "domain": "crisp.chat",
      "url": "https://crisp.chat/",
      "description": "Crisp is the best way to chat with your website visitors. Add it on your website in 2 minutes and start increasing your sales!",
      "timezone": -300,
      "metrics": {
        "employees": 4,
        "market_cap": 0,
        "raised": 0,
        "arr": 0
      },
      "geolocation": {
        "country": "FR",
        "region": "29",
        "city": "Brest",
        "coordinates": {
          "latitude": 48.3908,
          "longitude": -4.4703
        }
      },
      "tags": [
        "chat",
        "saas"
      ],
      "phones": [],
      "emails": [
        "contact@crisp.chat",
        "support@crisp.chat"
      ]
    },
    "segments": [
      "love",
      "poweruser"
    ],
    "notepad": "",
    "active": {
      "now": false
    },
    "created_at": 1468341857826,
    "updated_at": 1468401603070
  }
}

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": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get People Profile
GET`/website/{website_id}/people/profile/{people_id}`

Resolves people profile.

error (boolean)
reason (string)
data (object)
- people_id (string) - People identifier
- email (string) - Email for people profile
- person (object) - Personal information
  - nickname (string) - Nickname for user (includes first name and last name)
  - avatar (string) - Avatar for user
  - gender (string) - Gender for user
    - Members
      - male
      - female
  - phone (string) - Phone number for user
  - address (string) - Address for user
  - description (string) - Description for user
  - website (string) - Website of user
  - timezone (number) - Timezone offset of user (UTC)
  - profiles (array[object]) - Online profiles for user
    - type (string) - Profile type (eg: facebook, twitter)
    - handle (string) - User handle on online platform
    - url (string) - URL for the profile
  - employment (object) - Employment information for user
    - name (string) - Company name
    - domain (string) - Company domain name
    - title (string) - User title in company
    - role (string) - User role in company
    - seniority (string) - User seniority in company
  - geolocation (object) - Geolocation information for user
    - country (string) - Country code
    - region (string) - Region code
    - city (string) - City name
    - coordinates (object) - Location coordinates
      - latitude (number) - Latitude coordinate
      - longitude (number) - Longitude coordinate
  - locales (array[string]) - Locales supported by user (ISO 639-1)
- company (object) - Company information
  - name (string) - Company name
  - legal_name (string) - Company legal name
  - domain (string) - Company domain name
  - url (string) - Company website URL
  - description (string) - Company description
  - timezone (number) - Company timezone offset (UTC)
  - phones (array[string]) - Company phone numbers
  - emails (array[string]) - Company email addresses
  - geolocation (object) - Company location
    - country (string) - Country code
    - region (string) - Region code
    - city (string) - City name
    - coordinates (object) - Location coordinates
      - latitude (number) - Latitude coordinate
      - longitude (number) - Longitude coordinate
  - metrics (object) - Metrics for company
    - employees (number) - Number of employees
    - market_cap (number) - Market capitalization
    - raised (number) - Money raised
    - arr (number) - Annual Recurring Revenue
  - tags (array[string]) - Tags for company
- segments (array[string]) - Segments attributed to people profile
- notepad (string) - Private notepad on people profile
- active (object) - User activity statistics (based on last active session from user)
  - now (boolean) - Whether user is considered active right now or not
  - last (number) - Timestamp at which the user was last active
- score (number) - Score associated to this profile, from 1 to 5 (based on ratings from user)
- created_at (number) - Profile creation timestamp
- updated_at (number) - Profile update timestamp

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

PUT https://api.crisp.chat/v1/website/website_id/people/profile/people_id

RequestsSave People Profile

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:profiles

Headers

Content-Type: application/json

Body

{
  "email": "valerian@crisp.chat",
  "person": {
    "nickname": "Valerian Saliou"
  }
}

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": "website_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_email_exists",
  "data": {}
}

Save People Profile
PUT`/website/{website_id}/people/profile/{people_id}`

Saves people profile, and overwrite all previous information.

email (string, required) - Email for people profile
person (object, required) - Personal information
- nickname (string, required) - Nickname for user (includes first name and last name)
- avatar (string, optional) - Avatar for user
- gender (string, optional) - Gender for user
  - Members
    - male
    - female
- phone (string, optional) - Phone number for user
- address (string, optional) - Address for user
- description (string, optional) - Description for user
- website (string, optional) - Website of user
- timezone (number, optional) - Timezone offset of user (UTC)
- profiles (array[object], optional) - Online profiles for user
  - type (string, required) - Profile type (eg: facebook, twitter)
  - handle (string, optional) - User handle on online platform
  - url (string, required) - URL for the profile
- employment (object, optional) - Employment information for user
  - name (string, required) - Company name
  - domain (string, optional) - Company domain name
  - title (string, optional) - User title in company
  - role (string, optional) - User role in company
  - seniority (string, optional) - User seniority in company
- geolocation (object, optional) - Geolocation information for user
  - country (string, optional) - Country code (can be blank)
  - region (string, optional) - Region code (can be blank)
  - city (string, optional) - City name (can be blank)
  - coordinates (object, optional) - Location coordinates
    - latitude (number, required) - Latitude coordinate
    - longitude (number, required) - Longitude coordinate
- locales (array[string], optional) - Locales supported by user (ISO 639-1)
company (object, optional) - Company information
- name (string, required) - Company name
- legal_name (string, optional) - Company legal name
- domain (string, optional) - Company domain name
- url (string, optional) - Company website URL
- description (string, optional) - Company description
- timezone (number, optional) - Company timezone offset (UTC)
- phones (array[string], optional) - Company phone numbers
- emails (array[string], optional) - Company email addresses
- geolocation (object, optional) - Company location
  - country (string, optional) - Country code (can be blank)
  - region (string, optional) - Region code (can be blank)
  - city (string, optional) - City name (can be blank)
  - coordinates (object, optional) - Location coordinates
    - latitude (number, required) - Latitude coordinate
    - longitude (number, required) - Longitude coordinate
- metrics (object, optional) - Metrics for company
  - employees (number, optional) - Number of employees
  - market_cap (number, optional) - Market capitalization
  - raised (number, optional) - Money raised
  - arr (number, optional) - Annual Recurring Revenue
- tags (array[string], optional) - Tags for company
segments (array[string], optional) - Segments attributed to people profile
notepad (string, optional) - Private notepad on people profile

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

PATCH https://api.crisp.chat/v1/website/website_id/people/profile/people_id

RequestsUpdate People Profile

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:profiles

Headers

Content-Type: application/json

Body

{
  "email": "valerian@crisp.chat",
  "person": {
    "nickname": "Valerian Saliou"
  }
}

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": "website_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_email_exists",
  "data": {}
}

Update People Profile
PATCH`/website/{website_id}/people/profile/{people_id}`

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

email (string, optional) - Email for people profile
person (object, optional) - Personal information
- nickname (string, optional) - Nickname for user (includes first name and last name)
- avatar (string, optional) - Avatar for user
- gender (string, optional) - Gender for user
  - Members
    - male
    - female
- phone (string, optional) - Phone number for user
- address (string, optional) - Address for user
- description (string, optional) - Description for user
- website (string, optional) - Website of user
- timezone (number, optional) - Timezone offset of user (UTC)
- profiles (array[object], optional) - Online profiles for user
  - type (string, optional) - Profile type (eg: facebook, twitter)
  - handle (string, optional) - User handle on online platform
  - url (string, optional) - URL for the profile
- employment (object, optional) - Employment information for user
  - name (string, optional) - Company name
  - domain (string, optional) - Company domain name
  - title (string, optional) - User title in company
  - role (string, optional) - User role in company
  - seniority (string, optional) - User seniority in company
- geolocation (object, optional) - Geolocation information for user
  - country (string, optional) - Country code (can be blank)
  - region (string, optional) - Region code (can be blank)
  - city (string, optional) - City name (can be blank)
  - coordinates (object, optional) - Location coordinates
    - latitude (number, optional) - Latitude coordinate
    - longitude (number, optional) - Longitude coordinate
- locales (array[string], optional) - Locales supported by user (ISO 639-1)
company (object, optional) - Company information
- name (string, optional) - Company name
- legal_name (string, optional) - Company legal name
- domain (string, optional) - Company domain name
- url (string, optional) - Company website URL
- description (string, optional) - Company description
- timezone (number, optional) - Company timezone offset (UTC)
- phones (array[string], optional) - Company phone numbers
- emails (array[string], optional) - Company email addresses
- geolocation (object, optional) - Company location
  - country (string, optional) - Country code (can be blank)
  - region (string, optional) - Region code (can be blank)
  - city (string, optional) - City name (can be blank)
  - coordinates (object, optional) - Location coordinates
    - latitude (number, optional) - Latitude coordinate
    - longitude (number, optional) - Longitude coordinate
- metrics (object, optional) - Metrics for company
  - employees (number, optional) - Number of employees
  - market_cap (number, optional) - Market capitalization
  - raised (number, optional) - Money raised
  - arr (number, optional) - Annual Recurring Revenue
- tags (array[string], optional) - Tags for company
segments (array[string], optional) - Segments attributed to people profile
notepad (string, optional) - Private notepad on people profile

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

DELETE https://api.crisp.chat/v1/website/website_id/people/profile/people_id

RequestsRemove People Profile

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:profiles

Headers

Content-Type: application/json

Responses200402403403404404404

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": "removal_not_permitted",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Remove People Profile
DELETE`/website/{website_id}/people/profile/{people_id}`

Removes people profile in website.

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

GET https://api.crisp.chat/v1/website/website_id/people/conversations/people_id/list/page_number

RequestsList People Conversations

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:conversations

Headers

Content-Type: application/json

Responses200206402403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    "session_b7642ced-5e5a-449b-9864-6489ebdadca3",
    "session_2fedcdb1-c1d7-4adf-a34c-e8c83e887572"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    "session_b7642ced-5e5a-449b-9864-6489ebdadca3"
  ]
}

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": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List People Conversations
GET`/website/{website_id}/people/conversations/{people_id}/list/{page_number}`

Lists conversations linked to people.

error (boolean)
reason (string)
data (array[string])

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)
page_number: number (optional)
The page number (paging in conversation list)

POST https://api.crisp.chat/v1/website/website_id/people/events/people_id

RequestsAdd Event

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:events

Headers

Content-Type: application/json

Responses201402403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "added",
  "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": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Add A People Event
POST`/website/{website_id}/people/events/{people_id}`

Stacks an event for people.

text (string, required) - Text for event
data (object, optional) - Data for event (if any)
color (enum[string], optional) - Color for event (if any)
- Members
  - red
  - orange
  - yellow
  - green
  - blue
  - purple
  - pink
  - brown
  - grey
  - black

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

GET https://api.crisp.chat/v1/website/website_id/people/events/people_id/list/page_number

RequestsList Events

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:events

Headers

Content-Type: application/json

Responses200206402403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "timestamp": 1468341926143,
      "text": "Added item to basket",
      "data": {
        "price": 10.99,
        "currency": "USD"
      },
      "color": "red"
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "timestamp": 1468341926143,
      "text": "Added item to basket",
      "data": {
        "price": 10.99,
        "currency": "USD"
      },
      "color": "red"
    },
    {
      "timestamp": 1468341867516,
      "text": "Signed up",
      "data": {},
      "color": "blue"
    }
  ]
}

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": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List People Events
GET`/website/{website_id}/people/events/{people_id}/list/{page_number}`

Lists stacked events for people.

error (boolean)
reason (string)
data (array[object])
- text (string) - Text for event
- data (object) - Data for event (if any)
- color (enum[string]) - Color for event (if any)
  - Members
    - red
    - orange
    - yellow
    - green
    - blue
    - purple
    - pink
    - brown
    - grey
    - black
- timestamp (number) - Timestamp of event (when the event was stacked)

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)
page_number: number (optional)
The page number (paging in event list)

GET https://api.crisp.chat/v1/website/website_id/people/data/people_id

RequestsGet Data

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:data

Headers

Content-Type: application/json

Responses200402403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "data": {
      "type": "customer",
      "signup": "finished"
    }
  }
}

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": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get People Data
GET`/website/{website_id}/people/data/{people_id}`

Gets stored data for people.

error (boolean)
reason (string)
data (object)
- data (object) - People data

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

PUT https://api.crisp.chat/v1/website/website_id/people/data/people_id

RequestsSave Data

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:data

Headers

Content-Type: application/json

Body

{
  "data": {
    "type": "customer",
    "signup": "finished"
  }
}

Responses200402403404404404

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_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Save People Data
PUT`/website/{website_id}/people/data/{people_id}`

Saves stored data for people.

data (object, optional) - People data

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

GET https://api.crisp.chat/v1/website/website_id/people/subscription/people_id

RequestsGet Subscription Status

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:subscriptions

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "email": 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": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "people_not_found",
  "data": {}
}

Get People Subscription Status
GET`/website/{website_id}/people/subscription/{people_id}`

Resolves subscription status for people (subscribed or unsubscribed).

error (boolean)
reason (string)
data (object)
- email (boolean) - Whether people is subscribed to emails or not

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

PATCH https://api.crisp.chat/v1/website/website_id/people/subscription/people_id

RequestsUpdate Subscription

Authenticated Tiers: user plugin
Plugin Scope Required: website:people:subscriptions

Headers

Content-Type: application/json

Body

{
  "email": true
}

Responses200403404404423

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": "people_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

Update People Subscription Status
PATCH`/website/{website_id}/people/subscription/{people_id}`

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

email (boolean, required) - Whether to subscribe to emails or not

URI Parameters

HideShow

website_id: string (required)
The website identifier
people_id: string (required)
The people identifier (also allowed: people email)

POST https://api.crisp.chat/v1/website/website_id/people/export/profiles

RequestsExport People Profiles

Authenticated Tiers: user

Headers

Content-Type: application/json

Body

{}

Responses202402403404

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": "website_not_found",
  "data": {}
}

Export People Profiles
POST`/website/{website_id}/people/export/profiles`

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

URI Parameters

HideShow

website_id: string (required)
The website identifier

POST https://api.crisp.chat/v1/website/website_id/people/import/profiles

RequestsImport People Profiles

Authenticated Tiers: user

Headers

Content-Type: application/json

Body

{
  "url": "https://storage.crisp.chat/users/processing/import/aa0b64dd-9fb4-4db9-80d6-5a49eb84087b/19d956c7-0294-45ad-89e1-58ce45e7008f.csv",
  "mapping": [
    {
      "column": 1,
      "field": "email"
    },
    {
      "column": 2,
      "field": "person.nickname"
    }
  ],
  "options": {
    "column_separator": ";",
    "skip_header": true
  }
}

Responses202402403404423423

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "dispatched",
  "data": {
    "import_id": "b831c61f-c289-469d-938c-4eaa1b0ee466"
  }
}

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": "import_busy_ingesting",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

Import People Profiles
POST`/website/{website_id}/people/import/profiles`

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

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

url (string, required) - File URL containing user data to be imported
mapping (array[object], required) - Raw data to Crisp data mapping
- column (number, required) - Mapping from raw data column index (starts at 1)
- field (string, required) - Mapping to Crisp field (regular field, or virtual field starting with _.)
  - Members
    - email
    - segments
    - notepad
    - person.nickname
    - person.phone
    - person.address
    - person.website
    - person.geolocation.country
    - person.geolocation.city
    - company.name
    - data.[*]
    - created_at
    - active
    - _.person.first_name
    - _.person.last_name
options (string, required) - Import options
- column_separator (string, required) - One-character column separator
- skip_header (boolean, required) - Whether to skip headers or not

URI Parameters

HideShow

website_id: string (required)
The website identifier

Website Visitors ¶

Manages multiple website visitors.

GET https://api.crisp.chat/v1/website/website_id/visitors/count

RequestsCount Visitors

Authenticated Tiers: user plugin
Plugin Scope Required: website:visitors

Headers

Content-Type: application/json

Responses200403404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "counted",
  "data": {
    "count": 42,
    "active": 7,
    "limited": false
  }
}

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)
- limited (boolean) - Whether visitor sockets are limited or not (due to high traffic)

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
Plugin Scope Required: website:visitors

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.enrich.email/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.enrich.email/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
Plugin Scope Required: website:visitors

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.enrich.email/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/token/

RequestsGet Session From Token

Authenticated Tiers: user plugin
Plugin Scope Required: website:visitors

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "resolved",
  "data": {
    "session_id": "session_85a46e79-b712-4c10-92f0-a4db8ebd1d8c"
  }
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "token_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

Get Session Identifier From Token
GET`/website/{website_id}/visitors/token/`

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

error (boolean)
reason (string)
data (array[object])
- session_id (string) - Session identifier
- token_id (string) - Token value

URI Parameters

HideShow

website_id: string (required)
The website identifier

GET https://api.crisp.chat/v1/website/website_id/visitors/blocked

RequestsCount Blocked Visitors

Authenticated Tiers: user

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 (enum[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

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 (enum[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

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 Availability ¶

Manages website availability operations.

GET https://api.crisp.chat/v1/website/website_id/availability/status

RequestsGet Website Availability Status

Authenticated Tiers: user plugin
Plugin Scope Required: website:availability

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
Plugin Scope Required: website:availability

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 Operators ¶

Manages multiple website operators.

GET https://api.crisp.chat/v1/website/website_id/operators/list

RequestsList Website Operators

Authenticated Tiers: user plugin
Plugin Scope Required: website:operators

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",
        "title": "CEO",
        "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",
        "title": "CTO",
        "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
    - sandbox
- details (object) - Member details
  - user_id (string) - User identifier (for operator and sandbox types only)
  - email (string) - User email (for all types)
  - avatar (string) - User avatar (for operator type only)
  - first_name (string) - User first name (for operator and sandbox types only)
  - last_name (string) - User last name (for operator and sandbox types only)
  - role (enum[string]) - User role (for operator and invite types only)
    - Members
      - owner
      - member
  - title (string) - User title (if any, for operator type only)
  - availability (enum[string]) - User availability (for operator type only)
    - Members
      - online
      - away
      - offline
  - has_token (boolean) - Whether operator has Two Factor Authentication enabled or not (for operator type only)
  - identifier (string) - User invite identifier (for invite type only)
  - key (string) - User invite key (for invite type only)

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
Plugin Scope Required: website:operators

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

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
Plugin Scope Required: website:operators

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
Plugin Scope Required: website:operators

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",
    "title": "CTO",
    "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
- title (string) - User title (if any)
- 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",
  "verify": "MySuperSecurePassword"
}

Responses202403403404409409423

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": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "password_unverified",
  "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
verify (string, required) - User password (used to double-authenticate invite)

URI Parameters

HideShow

website_id: string (required)
The website identifier

PATCH https://api.crisp.chat/v1/website/website_id/operator/user_id

RequestsChange Operator Membership

Authenticated Tiers: user

Headers

Content-Type: application/json

Body

{
  "role": "owner",
  "title": "CTO"
}

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 Membership
PATCH`/website/{website_id}/operator/{user_id}`

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

role (enum[string], optional) - Operator role
- Members
  - owner
  - member
title (string, optional) - Operator title (if any)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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`

Responses202402403404404404404410412412412412423

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_none",
  "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

Headers

Content-Type: application/json

Responses202402403404404404404404410412412412412423

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_none",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "campaign_recipients_unfilterable",
  "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

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

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

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.enrich.email/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.enrich.email/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.enrich.email/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 Analytics ¶

Manages website analytics.

GET https://api.crisp.chat/v1/website/website_id/analytics/type/metric/points?date_from=&date_to=&date_split=&classifier=&filter_primary=&filter_secondary=&filter_tertiary=

RequestsAcquire Analytics Points

Authenticated Tiers: user

Headers

Content-Type: application/json

Responses200400400400400402403404404412416416

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "acquired",
  "data": {
    "pipeline": {
      "aggregator": "summation"
    },
    "points": [
      {
        "value": 0,
        "hits": 0,
        "date": {
          "from": 1544436600000,
          "to": 1544522999999
        }
      },
      {
        "value": 0,
        "hits": 0,
        "date": {
          "from": 1544523000000,
          "to": 1544609399999
        }
      },
      {
        "value": 0,
        "hits": 0,
        "date": {
          "from": 1544609400000,
          "to": 1544695799999
        }
      },
      {
        "value": 8,
        "hits": 2,
        "date": {
          "from": 1544695800000,
          "to": 1544782199999
        }
      },
      {
        "value": 0,
        "hits": 0,
        "date": {
          "from": 1544782200000,
          "to": 1544868599999
        }
      },
      {
        "value": 0,
        "hits": 0,
        "date": {
          "from": 1544868600000,
          "to": 1544954399999
        }
      }
    ]
  }
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_point_type",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_point_metric",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_date_range",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_date_split",
  "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": "not_subscribed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "too_many_date_splits",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "underflow_date_range",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "overflow_date_range",
  "data": {}
}

Acquire Analytics Points
GET`/website/{website_id}/analytics/{type}/{metric}/points{?date_from}{&date_to}{&date_split}{&classifier}{&filter_primary}{&filter_secondary}{&filter_tertiary}`

Acquires analytics points for given type and metric in website.

error (boolean)
reason (string)
data (object)
- pipeline (object) - Analytics pipeline information
  - aggregator (enum[string]) - Used point aggregator
    - Members
      - average
      - summation
- points (array[object]) - Acquired points
  - value (number) - Aggregated value for points (in date range)
  - hits (number) - Number of aggregated points (in date range)
  - date (object) - Date range used for aggregation (ie. point reduction)
    - from (number) - Range start date
    - to (number) - Range end date

URI Parameters

HideShow

website_id: string (required)
The website identifier
type: string (required)
The requested analytics type
metric: string (required)
The requested analytics metric
date_from: string (required)
When to start (date, ISO 8601)
date_to: string (required)
When to end (date, ISO 8601)
date_split: string (required)
Date split to use (either: hourly, daily, weekly or monthly)
classifier: string (optional)
Point classifier (required for certain analytics)
filter_primary: string (optional)
Primary point filter (required for certain analytics)
filter_secondary: string (optional)
Secondary point filter (required for certain analytics)
filter_tertiary: string (optional)
Tertiary point filter (required for certain analytics)

GET https://api.crisp.chat/v1/website/website_id/analytics/filters/page_number?date_from=&date_to=]

RequestsList Analytics Filters

Authenticated Tiers: user

Headers

Content-Type: application/json

Responses200400400400400402403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "primary": "chat",
      "secondary": "",
      "tertiary": "",
      "aggregated": 12
    },
    {
      "primary": "important",
      "secondary": "",
      "tertiary": "",
      "aggregated": 3
    },
    {
      "primary": "lead",
      "secondary": "",
      "tertiary": "",
      "aggregated": 1
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_point_type",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_point_metric",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "unsupported_point_filter",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_date_range",
  "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": "no_point_filter",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List Analytics Filters
GET`/website/{website_id}/analytics/filters/{page_number}{?date_from}{&date_to}]`

Acquires available analytics filters in website.

error (boolean)
reason (string)
data (array[object])
- primary (string) - Filter primary value
- secondary (string) - Filter secondary value (if any)
- tertiary (string) - Filter tertiary value (if any)
- aggregated (number) - Aggregated value for points in filter (in date range, if set)

URI Parameters

HideShow

website_id: string (required)
The website identifier
page_number: number (optional)
The page number (paging if many websites)
date_from: string (optional)
When to start (date, ISO 8601)
date_to: string (optional)
When to end (date, ISO 8601)

GET https://api.crisp.chat/v1/website/website_id/analytics/type/metric/classifiers/page_number?date_from=&date_to=

RequestsList Analytics Classifiers

Authenticated Tiers: user

Headers

Content-Type: application/json

Responses200400400400402403404404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "classifier": "FR",
      "aggregated": 1
    },
    {
      "classifier": "GB",
      "aggregated": 33
    },
    {
      "classifier": "US",
      "aggregated": 2
    },
    {
      "classifier": "UY",
      "aggregated": 2
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_point_type",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_point_metric",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "invalid_date_range",
  "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": "no_point_classifier",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_subscribed",
  "data": {}
}

List Analytics Classifiers
GET`/website/{website_id}/analytics/{type}/{metric}/classifiers/{page_number}{?date_from}{&date_to}`

Acquires available analytics classifiers in website.

error (boolean)
reason (string)
data (array[object])
- classifier (string) - Classifier value
- aggregated (number) - Aggregated value for points in classifier (in date range)

URI Parameters

HideShow

website_id: string (required)
The website identifier
page_number: number (optional)
The page number (paging if many websites)
type: string (required)
The requested analytics type
metric: string (required)
The requested analytics metric
date_from: string (required)
When to start (date, ISO 8601)
date_to: string (required)
When to end (date, ISO 8601)

Website Batch ¶

Proceeds batch operations on website.

PATCH https://api.crisp.chat/v1/website/batch/resolve

RequestsResolve All Conversations

Authenticated Tiers: user

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

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

Headers

Content-Type: application/json

Body

{
  "sessions": [
    "session_19e5240f-0a8d-461e-a661-a3123fc6eec9",
    "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881"
  ]
}

Responses200403403404404423

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": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "quota_limit_exceeded",
  "data": {}
}

Authenticated Tiers: user

Headers

Content-Type: application/json

Body

{
  "people": {
    "profiles": [
      "eee8759d-52db-48e5-982d-3426e3566ce0"
    ]
  }
}

Responses200403403404404423

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": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "quota_limit_exceeded",
  "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 Settings ¶

Manages the website settings.

GET https://api.crisp.chat/v1/website/website_id/settings

RequestsGet Website Settings

Authenticated Tiers: user plugin
Plugin Scope Required: website:settings

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": "+33757905447",
      "messenger": null,
      "telegram": null,
      "twitter": "crisp-im"
    },
    "inbox": {
      "lock_removal": false,
      "force_operator_token": 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,
      "visitor_compose": 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
  - force_operator_token (boolean) - Whether to force operators to use Two Factor Authentication or not
- emails (object) - Emails settings
  - rating (boolean) - Whether to ask users to rate support or not
  - transcript (boolean) - Whether to notify users of transcript records for conversation or not
  - enrich (boolean) - Whether to enable profile enrichment based on email or not
  - junk_filter (boolean) - Whether to enable the junk filter or not
- chatbox (object) - Chatbox settings
  - tile (enum[string]) - Which tile to use for messages view background in chatbox (set to blank value for none)
    - 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)
  - visitor_compose (boolean) - Whether to show visitor compose preview or not (MagicType from visitor)
  - file_transfer (boolean) - Whether to show the file upload tools in chatbox
  - 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
Plugin Scope Required: website:settings

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": "+33757905447"
  },
  "inbox": {
    "lock_removal": false,
    "force_operator_token": 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,
    "visitor_compose": 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"
    ]
  }
}

Responses200403403404412

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_member_token_missing",
  "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
- force_operator_token (boolean, optional) - Whether to force operators to use Two Factor Authentication 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)
- visitor_compose (boolean, optional) - Whether to show visitor compose preview or not (MagicType from visitor)
- 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 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
Plugin Scope Required: website:verify

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
Plugin Scope Required: website:verify

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
Plugin Scope Required: website:verify

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
Plugin Scope Required: website:verify

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

Plugin ¶

Manages Crisp plugins.

Plugins Subscription ¶

Manages website subscription to plugins.

GET https://api.crisp.chat/v1/plugins/subscription

RequestsList All Active Subscriptions

Authenticated Tiers: user

Headers

Content-Type: application/json

Responses200

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "id": "12a1a9b5-588d-4a5f-9007-4cce1093ef3a",
      "urn": "urn:crisp.im:email-redirect:0",
      "type": "internal",
      "name": "Email Redirect",
      "category": "feature",
      "summary": "Redirect your emails to Crisp.",
      "price": 5,
      "plans": [],
      "icon": "https://storage.crisp.chat/plugins/images/cc5b2440-552e-4142-b308-a8b04ec32ac8/icon.png",
      "website_url": null,
      "contact_url": null,
      "terms_url": null,
      "privacy_url": null,
      "help_url": null,
      "video_url": null,
      "configurable": false,
      "since": "2016-07-03T08:13:52.000Z",
      "active": true,
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
      "card_id": "b5be332d-bf2b-464f-9710-27a1573740f7"
    }
  ]
}

List All Active Subscriptions
GET`/plugins/subscription`

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

error (boolean)
reason (string)
data (array[object])
- id (string) - Plugin identifier
- urn (string) - Plugin Uniform Resource Name
- type (enum[string]) - Plugin type
  - Members
    - internal
    - external
- name (string) - Plugin name
- category (enum[string]) - Plugin category
  - Members
    - feature
    - automation
    - cms
    - crm
    - marketing
    - messaging
    - teamwork
    - other
- summary (string) - Plugin summary
- price (number) - Plugin price (in platform-wide currency)
- plans (array[object]) - Plans the plugin is included in (if part of a plan)
  - id (string) - Plan identifier
  - name (string) - Plan name
  - price (number) - Plan price (in platform-wide currency)
- icon (string) - Plugin icon URL
- website_url (string) - Website for the plugin (if any)
- contact_url (string) - Contact address for the plugin (if any)
- terms_url (string) - Terms of use for the plugin (if any)
- privacy_url (string) - Privacy policy for the plugin (if any)
- help_url (string) - Help article for the plugin (if any)
- video_url (string) - Explanatory video for the plugin (if any)
- configurable (boolean) - Whether the plugin can be configured or not
- since (string) - Datetime since when the plugin is available
- active (boolean) - Whether the plugin is active, or has been disabled (eg: due to failed renewal payment)
- website_id (string) - Website identifier on which plugin is active
- card_id (string) - Card identifier which is used to pay the plugin subscription

GET https://api.crisp.chat/v1/plugins/subscription/website_id

RequestsList Subscriptions For A Website

Authenticated Tiers: user

Headers

Content-Type: application/json

Responses200403404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "id": "12a1a9b5-588d-4a5f-9007-4cce1093ef3a",
      "urn": "urn:crisp.im:email-redirect:0",
      "type": "internal",
      "name": "Email Redirect",
      "category": "feature",
      "summary": "Redirect your emails to Crisp.",
      "price": 5,
      "plans": [],
      "icon": "https://storage.crisp.chat/plugins/images/cc5b2440-552e-4142-b308-a8b04ec32ac8/icon.png",
      "website_url": null,
      "contact_url": null,
      "terms_url": null,
      "privacy_url": null,
      "help_url": null,
      "video_url": null,
      "configurable": false,
      "since": "2016-07-03T08:13:52.000Z",
      "active": true,
      "website_id": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc"
    }
  ]
}

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 Subscriptions For A Website
GET`/plugins/subscription/{website_id}`

Lists plugin subscriptions for given website.

error (boolean)
reason (string)
data (array[object])
- id (string) - Plugin identifier
- urn (string) - Plugin Uniform Resource Name
- type (enum[string]) - Plugin type
  - Members
    - internal
    - external
- name (string) - Plugin name
- category (enum[string]) - Plugin category
  - Members
    - feature
    - automation
    - cms
    - crm
    - marketing
    - messaging
    - teamwork
    - other
- summary (string) - Plugin summary
- price (number) - Plugin price (in platform-wide currency)
- plans (array[object]) - Plans the plugin is included in (if part of a plan)
  - id (string) - Plan identifier
  - name (string) - Plan name
  - price (number) - Plan price (in platform-wide currency)
- icon (string) - Plugin icon URL
- website_url (string) - Website for the plugin (if any)
- contact_url (string) - Contact address for the plugin (if any)
- terms_url (string) - Terms of use for the plugin (if any)
- privacy_url (string) - Privacy policy for the plugin (if any)
- help_url (string) - Help article for the plugin (if any)
- video_url (string) - Explanatory video for the plugin (if any)
- configurable (boolean) - Whether the plugin can be configured or not
- since (string) - Datetime since when the plugin is available
- active (boolean) - Whether the plugin is active, or has been disabled (eg: due to failed renewal payment)
- website_id (string) - Website identifier on which plugin is active

URI Parameters

HideShow

website_id: string (required)
The website identifier

GET https://api.crisp.chat/v1/plugins/subscription/website_id/plugin_id

RequestsGet Subscription Details

Authenticated Tiers: user

Headers

Content-Type: application/json

Responses200403404404

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "listed",
  "data": [
    {
      "id": "12a1a9b5-588d-4a5f-9007-4cce1093ef3a",
      "urn": "urn:crisp.im:email-redirect:0",
      "type": "internal",
      "name": "Email Redirect",
      "category": "feature",
      "summary": "Redirect your emails to Crisp.",
      "price": 5,
      "plans": [],
      "icon": "https://storage.crisp.chat/plugins/images/cc5b2440-552e-4142-b308-a8b04ec32ac8/icon.png",
      "website_url": null,
      "contact_url": null,
      "terms_url": null,
      "privacy_url": null,
      "help_url": null,
      "video_url": null,
      "configurable": false,
      "since": "2016-07-03T08:13:52.000Z",
      "active": true
    }
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "not_allowed",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "subscription_not_found",
  "data": {}
}

Headers

Content-Type: application/json

Body

{
  "error": true,
  "reason": "website_not_found",
  "data": {}
}

Get Subscription Details
GET`/plugins/subscription/{website_id}/{plugin_id}`

Resolves details on a given subscription.

error (boolean)
reason (string)
data (object)
- id (string) - Plugin identifier
- urn (string) - Plugin Uniform Resource Name
- type (enum[string]) - Plugin type
  - Members
    - internal
    - external
- name (string) - Plugin name
- category (enum[string]) - Plugin category
  - Members
    - feature
    - automation
    - cms
    - crm
    - marketing
    - messaging
    - teamwork
    - other
- summary (string) - Plugin summary
- price (number) - Plugin price (in platform-wide currency)
- plans (array[object]) - Plans the plugin is included in (if part of a plan)
  - id (string) - Plan identifier
  - name (string) - Plan name
  - price (number) - Plan price (in platform-wide currency)
- icon (string) - Plugin icon URL
- website_url (string) - Website for the plugin (if any)
- contact_url (string) - Contact address for the plugin (if any)
- terms_url (string) - Terms of use for the plugin (if any)
- privacy_url (string) - Privacy policy for the plugin (if any)
- help_url (string) - Help article for the plugin (if any)
- video_url (string) - Explanatory video for the plugin (if any)
- configurable (boolean) - Whether the plugin can be configured or not
- since (string) - Datetime since when the plugin is available
- active (boolean) - Whether the plugin is active, or has been disabled (eg: due to failed renewal payment)

URI Parameters

HideShow

website_id: string (required)
The website identifier
plugin_id: string (required)
The plugin identifier

POST https://api.crisp.chat/v1/plugins/subscription/website_id

RequestsSubscribe Plugin To Website

Authenticated Tiers: user

Headers

Content-Type: application/json

Body

{
  "plugin_id": "98454664-9f7d-4d95-a9ce-f37356f5e65a"
}

Responses201403403404404424424424

Headers

Content-Type: application/json

Body

{
  "error": false,
  "reason": "subscribed",
  "data": {}
}

Headers

Content-Type:

API Endpoint

Prerequisites ¶

Libraries ¶

Authentication ¶

Rate Limits ¶

🔀 RTM Events ¶

🚨 Security Reports ¶

Website ¶

Website Base ¶

Headers

Headers

Headers

Check If Website ExistsHEAD/website{?domain}

Headers

Body

Headers

Body

Headers

Body

Create WebsitePOST/website

Headers

Headers

Body

Headers

Body

Headers

Body

Get A WebsiteGET/website/{website_id}

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Delete A WebsiteDELETE/website/{website_id}

Website Conversations ¶

Headers

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Headers

Body

Headers

Body

Headers

Body

Headers

Body

List Suggested Conversation SegmentsGET/website/{website_id}/conversations/suggest/segments/{page_number}

Headers

Headers

Body

Headers

Body

Headers

Body

Headers

Body

List Suggested Conversation Data KeysGET/website/{website_id}/conversations/suggest/data/{page_number}

Website Conversation ¶

Headers

Headers

Prerequisites

Libraries

Authentication

Rate Limits

🔀 RTM Events

🚨 Security Reports

Check If Website Exists
HEAD`/website{?domain}`

Create Website
POST`/website`

Get A Website
GET`/website/{website_id}`

Delete A Website
DELETE`/website/{website_id}`

List Suggested Conversation Segments
GET`/website/{website_id}/conversations/suggest/segments/{page_number}`

List Suggested Conversation Data Keys
GET`/website/{website_id}/conversations/suggest/data/{page_number}`

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

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

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

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

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

Get Messages In Conversation
GET`/website/{website_id}/conversation/{session_id}/messages{?timestamp_before}`