Crisp provides a HTTP REST API for developers to easily develop custom behaviors for their Crisp website (eg. messaging, CRM). This article explains how to start using the Crisp HTTP REST API.

The Crisp API is documented on https://docs.crisp.chat/api/v1/. You will need to check this documentation if you start integrating your backend or app with Crisp.

The Crisp HTTP REST API endpoint is: https://api.crisp.chat/v1

Crisp provides libraries for common programming languages, which wrap HTTP routes to convenient methods and objects:

node-crisp-api - Crisp API wrapper for NodeJS
go-crisp-api - Crisp API wrapper for Go
php-crisp-api - Crisp API wrapper for PHP

This article will explain how to use the Crisp Go library. The flow is the same for other libraries; all official Crisp libraries are consistent in their integration flow. In those examples, the Crisp WEBSITE_ID in use is 8c842203-7ed8-4e29-a608-7cf78a7d2fcc (you may use your own website identifier instead).

Import the library

In order to use the Crisp API, you first need to include the relevant library in your code:

import "github.com/crisp-im/go-crisp-api/crisp"

Then, construct a new Crisp client, and then re-use that common client across your project to access API routes. For example:

client := crisp.New()

Once the client is initialized, refer to the next section: Authentication.

Authenticate to the API

To authenticate against the API, generate your session identifier and session key once using the following cURL request in your terminal (replace YOUR_ACCOUNT_EMAIL and YOUR_ACCOUNT_PASSWORD):

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

If authentication succeeds, you will get a JSON response containing your authentication keys: identifier and key. Keep those 2 values private, and store them safely for long-term use.

Then, add authentication parameters to your client instance right after you create it:

client := crisp.New()

// Authenticate to API (identifier, key)
// eg. client.Authenticate("7c3ef21c-1e04-41ce-8c06-5605c346f73e", "cc29e1a5086e428fcc6a697d5837a66d82808e65c5cce006fbf2191ceea80a0a")
client.Authenticate(identifier, key)

// Now, you can use authenticated API sections.


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

Basic usage

Now, you are ready to use the Crisp API in your project. You may list the visitors currently on your website:

// List visitors for my website
visitors, _, err := client.Website.ListVisitors("8c842203-7ed8-4e29-a608-7cf78a7d2fcc", 1)


Or, send a message to a given session (here session_19e5240f-0a8d-461e-a661-a3123fc6eec9):

// Build text message
message := crisp.ConversationTextMessageNew{Type: "text", From: "operator", Origin: "chat", Content: "Hello :)", Fingerprint: 12345}

// Send text message for website_id and session_id
, , err := client.Website.SendTextMessageInConversation("8c842203-7ed8-4e29-a608-7cf78a7d2fcc", "session_19e5240f-0a8d-461e-a661-a3123fc6eec9", message)


Advanced usage

As Crisp is a Messaging Service, you may also want to listen to realtime events to catch eg. messages as they get received and sent. For that Crisp provides a RTM API, which complements the REST API.

The RTM API runs on WebSocket / SocketIO. The Crisp Go library exposes a programmatic wrapper over the RTM API, so that you can easily listen to incoming events.

To subscribe to realtime events, you need to initiate a Listen manager from the Go library, and hook to the events you want to listen to:

// Subscribe to realtime events
// Notice: set event list to '[]string{}' to listen to all event namespaces
client.Events.Listen([]string{"message:send"}, func(reg *crisp.EventsRegister) {
fmt.Print("Now listening for events\n")

reg.On("message:send/text", func(evt crisp.EventsReceiveTextMessage) {
fmt.Printf("[message:send/text] %s\n", evt)
})
})


In order to be able to bind an event handler on an event namespace using On(), you need to tell the Crisp RTM API which events you want to receive by passing an event namespace list as the first parameter of the Listen() method (here: []string{"message:send"}).

The full list of events is available in the Go library README.

Full reference

The full list of available methods for the Go library is available in the project README.
Was this article helpful?
Thank you!