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
ruby-crisp-api - Crisp API wrapper for Ruby
python-crisp-api - Crisp API wrapper for Pyhon

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 Crisp token generation utility. You'll get a token keypair made of 2 values.

Keep your token keypair values private, and store them safely for long-term use.

You can now use the token keypair you've just generated to 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: 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.

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?
Cancel
Thank you!