Crisp API Wrapper
The Crisp API Ruby wrapper. Authenticate, send messages, fetch conversations, access your agent accounts from your Ruby code.
Copyright 2023 Crisp IM SAS. See LICENSE for copying information.
- 📝 Implements: REST API Reference (V1) at revision: 16/01/2023
- 😘 Maintainer: @valeriansaliou, @eliottvincent
Usage
You may follow the REST API Quickstart guide, which will get you running with the REST API in minutes.
Add the library to your Gemfile
:
gem "crisp-api", "~> 1.1.12"
Then, import it:
require "crisp-api"
Build a new authenticated Crisp client with your identifier
and key
tokens.
client = Crisp::Client.new
client.set_tier("plugin")
client.authenticate(identifier, key)
Then, your client is ready to be consumed!
Authentication
To authenticate against the API, obtain your authentication token keypair by following the REST API Authentication guide. You'll get a token keypair made of 2 values.
Keep your token keypair 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::Client.new
# Authenticate to API with your plugin token (identifier, key)
# eg. client.authenticate("5c0595b2-9381-4a76-a2e0-04aa00c1ede7", "3bdb0812d0f5352bf68901ddc731434dade419b98507971905acdd2f967df61c")
client.set_tier("plugin")
client.authenticate(identifier, key)
# Now, you can use authenticated API sections.
Resource Methods
Most useful available Crisp API resources are implemented. Programmatic methods names are named after their label name in the REST API Reference.
All methods that you will most likely need when building a Crisp integration are prefixed with a star symbol (⭐).
In the following method prototypes, crisp
is to be replaced with your Crisp API instance. For example, instanciate client = Crisp()
and then call eg: client.website.list_conversations(website_id, 1)
.
When calling a method that writes data to the API (eg. send a message with: client.website.send_message_in_conversation()
), you need to submit it this way:
website_id = "6497e4a4-b17c-41e0-bfea-eea97ba8115a"
session_id = "session_f32bc993-f7ce-41af-bcd1-110fc147a392"
client.website.(
website_id, session_id,
{
"type" => "text",
"content" => "This message was sent from ruby-crisp-api! :)",
"from" => "operator",
"origin" => "chat"
}
)
⚠️ Note that, depending on your authentication token tier, which is either user
or plugin
, you may not be allowed to use all methods from the library. When in doubt, refer to the library method descriptions below. Most likely, you are using a plugin
token.
Website
Website Conversations
- ⭐ List Conversations [
user
,plugin
]: Reference client.website.list_conversations(website_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" page_number = 1 client.website.list_conversations(website_id, page_number);
- Search Conversations [
user
,plugin
]: Reference client.website.search_conversations(website_id, 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)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" page_number = 1 client.website.list_conversations(website_id, page_number);
- ⭐ List Conversations [
Website Conversation
- ⭐ Create A New Conversation [
user
,plugin
]: Reference client.website.create_new_conversation(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.create_new_conversation(website_id);
- Check If Conversation Exists [
user
,plugin
]: Reference client.website.check_conversation_exists(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.check_conversation_exists(website_id, session_id);
- ⭐ Get A Conversation [
user
,plugin
]: Reference client.website.get_conversation(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.get_conversation(website_id, session_id);
- Remove A Conversation [
user
,plugin
]: Reference client.website.remove_conversation(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.remove_conversation(website_id, session_id);
- Initiate A Conversation With Existing Session [
user
,plugin
]: Reference client.website.initiate_conversation_with_existing_session(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.initiate_conversation_with_existing_session(website_id, session_id);
- ⭐ Get Messages In Conversation [
user
,plugin
]: Reference client.website.get_messages_in_conversation(website_id, session_id, query)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.(website_id, session_id, query);
- ⭐ Send A Message In Conversation [
user
,plugin
]: Reference client.website.send_message_in_conversation(website_id, session_id, query)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" query = { "type" => "text", "from" => "operator", "origin" => "chat", "content" => "Hey there! Need help?" } client.website.(website_id, session_id, query);
- Update A Message In Conversation [
user
,plugin
]: Reference client.website.update_message_in_conversation(website_id, session_id, fingerprint, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" fingerprint = 524653764345 data = "Hey there! Need help?" client.website.(website_id, session_id, fingerprint, data);
- Compose A Message In Conversation [
user
,plugin
]: Reference client.website.compose_message_in_conversation(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = [ "type" => "start", "from" => "operator" ] client.website.(website_id, session_id, data);
- ⭐ Mark Messages As Read In Conversation [
user
,plugin
]: Reference client.website.mark_messages_read_in_conversation(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = [ "from" => "operator", "origin" => "urn:crisp.im:slack:0", "fingerprints" => [ "5719231201" ] ] client.website.(website_id, session_id, data);
- ⭐ Mark Messages As Delivered In Conversation [
user
,plugin
]: Reference client.website.mark_messages_delivered_in_conversation(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = [ "from" => "operator", "origin" => "urn:crisp.im:slack:0", "fingerprints" => [ "5719231201" ] ] client.website.(website_id, session_id, data);
- ⭐ Get Conversation Routing Assign [
user
,plugin
]: Reference client.website.get_conversation_routing_assign(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.get_conversation_routing_assign(website_id, session_id);
- ⭐ Assign Conversation Routing [
user
,plugin
]: Reference client.website.assign_conversation_routing(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = [ "assigned" => [ "user_id" => "a4c32c68-be91-4e29-8a05-976e93abbe3f" ] ] client.website.assign_conversation_routing(website_id, session_id, data);
- ⭐ Get Conversation Metas [
user
,plugin
]: Reference client.website.get_conversation_metas(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.(website_id, session_id);
- ⭐ Update Conversation Metas [
user
,plugin
]: Reference client.website.update_conversation_metas(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = [ "nickname" => "John Doe", "email" => "john.doe@acme-inc.com", "segments" => [ "happy", "customer", "love" ], "data" => [ "type" => "customer", "signup" => "finished" ] ] client.website.(website_id, session_id, data);
- List Conversation Pages [
user
,plugin
]: Reference client.website.list_conversation_pages(website_id, session_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" page_number = 1 client.website.list_conversation_pages(website_id, session_id, page_number);
- List Conversation Events [
user
,plugin
]: Reference client.website.list_conversation_events(website_id, session_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" page_number = 1 client.website.list_conversation_events(website_id, session_id, page_number);
- List Conversation Files [
user
,plugin
]: Reference client.website.list_conversation_files(website_id, session_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" page_number = 1 client.website.list_conversation_files(website_id, session_id, page_number);
- Get Conversation State [
user
,plugin
]: Reference client.website.get_conversation_state(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.get_conversation_state(website_id, session_id);
- ⭐ Change Conversation State [
user
,plugin
]: Reference client.website.change_conversation_state(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = "unresolved" client.website.change_conversation_state(website_id, session_id, data);
- Get Block Status For Conversation [
user
,plugin
]: Reference client.website.get_block_status_for_conversation(website_id, session_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" client.website.get_block_status_for_conversation(website_id, session_id);
- Block Incoming Messages For Conversation [
user
,plugin
]: Reference client.website.block_incoming_messages_for_conversation(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = true client.website.(website_id, session_id, data);
- Request Email Transcript For Conversation [
user
,plugin
]: Reference client.website.request_email_transcript_for_conversation(website_id, session_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" data = [ "to" => "operator", "email" => "valerian@crisp.chat" ] client.website.request_email_transcript_for_conversation(website_id, session_id, data);
- ⭐ Create A New Conversation [
Website People (these are your end-users)
- Get People Statistics [
user
,plugin
]: Reference client.website.get_people_statistics(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.get_people_statistics(website_id);
- List People Segments [
user
,plugin
]: Reference client.website.list_people_segments(website_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" page_number = 1 client.website.list_people_segments(website_id, page_number);
- ⭐ List People Profiles [
user
,plugin
]: Reference client.website.list_people_profiles(website_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" page_number = 1 client.website.list_people_profiles(website_id, page_number);
- ⭐ Add New People Profile [
user
,plugin
]: Reference client.website.add_new_people_profile(website_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" data = [ "email" => "valerian@crisp.chat", "person" => [ "nickname" => "Valerian Saliou" ] ] client.website.add_new_people_profile(website_id, data);
- ⭐ Check If People Profile Exists [
user
,plugin
]: Reference client.website.check_people_profile_exists(website_id, people_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" people_id = "c5a2f70c-f605-4648-b47f-8c39d4b03a50" client.website.check_people_profile_exists(website_id, people_id);
- ⭐ Get People Profile [
user
,plugin
]: Reference client.website.get_people_profile(website_id, people_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" people_id = "c5a2f70c-f605-4648-b47f-8c39d4b03a50" client.website.get_people_profile(website_id, people_id);
- ⭐ Save People Profile [
user
,plugin
]: Reference client.website.save_people_profile(website_id, people_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" people_id = "c5a2f70c-f605-4648-b47f-8c39d4b03a50" data = [ "email" => "valerian@crisp.chat", "person" => [ "nickname" => "Valerian Saliou" ] ] client.website.save_people_profile(website_id, people_id, data);
- Find People Profile By Email [
user
,plugin
]: Reference client.website.find_people_profile_by_email(website_id, email)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" people_id = "c5a2f70c-f605-4648-b47f-8c39d4b03a50" client.website.get_people_profile(website_id, people_id);
- ⭐ Update People Profile [
user
,plugin
]: Reference client.website.update_people_profile(website_id, people_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" people_id = "c5a2f70c-f605-4648-b47f-8c39d4b03a50" data = [ "email" => "valerian@crisp.chat", "person" => [ "nickname" => "Valerian Saliou" ] ] client.website.update_people_profile(website_id, people_id, data);
- ⭐ Remove People Profile [
user
,plugin
]: Reference client.website.remove_people_profile(website_id, people_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" people_id = "c5a2f70c-f605-4648-b47f-8c39d4b03a50" client.website.remove_people_profile(website_id, people_id);
- List People Conversations [
user
,plugin
]: Reference client.website.list_people_conversations(website_id, people_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" people_id = "c5a2f70c-f605-4648-b47f-8c39d4b03a50" page_number = 1 client.website.list_people_conversations(website_id, people_id, page_number);
- Add A People Event [
user
,plugin
]: Reference client.website.add_people_event(website_id, people_id, data)
- List People Events [
user
,plugin
]: Reference client.website.list_people_events(website_id, people_id, page_number)
- Get People Data [
user
,plugin
]: Reference client.website.get_people_data(website_id, people_id)
- Save People Data [
user
,plugin
]: Reference client.website.save_people_data(website_id, people_id, data)
- Update People Data [
user
,plugin
]: Reference client.website.update_people_data(website_id, people_id, data)
- Get People Subscription Status [
user
,plugin
]: Reference client.website.get_people_subscription_status(website_id, people_id)
- Update People Subscription Status [
user
,plugin
]: Reference client.website.update_people_subscription_status(website_id, people_id, data)
- Get People Statistics [
👉 Notice: The peopleID
argument can be an email or the peopleID
.
Website Base
- Create Website [
user
,plugin
]: Reference client.website.create_website(data)
See Example
client.website.create_website(data);
- Get A Website [
user
,plugin
]: Reference client.website.get_website(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.get_website(website_id);
- Delete A Website [
user
]: Reference client.website.delete_website(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.delete_website(website_id);
- Create Website [
Website Batch
- Batch Resolve Items [
user
]: Reference client.website.batch_resolve_items(website_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.batch_resolve_items(website_id, data);
- Batch Read Items [
user
]: Reference client.website.batch_read_items(website_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.batch_read_items(website_id, data);
- Batch Remove Items [
user
]: Reference client.website.batch_remove_items(website_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" data = [ "session_19e5240f-0a8d-461e-a661-a3123fc6eec9", "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" ] client.website.batch_remove_items(website_id, data);
- Batch Resolve Items [
Website Availability
- Get Website Availability Status [
user
,plugin
]: Reference client.website.get_website_availability_status(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.get_website_availability_status(website_id);
- Get Website Availability Status [
Website Operator
- List Website Operators [
user
,plugin
]: Reference client.website.list_website_operators(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.list_website_operators(website_id);
- List Last Active Website Operators [
user
,plugin
]: Reference client.website.list_last_active_website_operators(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.list_last_active_website_operators(website_id);
- List Website Operators [
Website Settings
- Get Website Settings [
user
,plugin
]: Reference client.website.get_website_settings(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.get_website_settings(website_id);
- Update Website Settings [
user
,plugin
]: Reference client.website.update_website_settings(website_id, data)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" data = [ "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, "helpdesk_only" => false, "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" ] ] ] client.website.update_website_settings(website_id, data);
- Get Website Settings [
Website Visitors
- Count Visitors [
user
,plugin
]: Reference client.website.count_visitors(website_id)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.count_visitors(website_id);
- List Visitors [
user
,plugin
]: Reference client.website.list_visitors(website_id, page_number)
See Example
website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" page_number = 1 client.website.list_visitors(website_id, page_number);
- Get Session ID [
user
,plugin
]: Reference client.website.get_session_id_by_token(website_id, token)
See Example
session_id = "session_700c65e1-85e2-465a-b9ac-ecb5ec2c9881" website_id = "8c842203-7ed8-4e29-a608-7cf78a7d2fcc" client.website.get_session_id_by_token(website_id, token);
- Count Visitors [
Bucket
- Bucket URL
- Generate Bucket URL [
user
,plugin
]: Reference client.bucket.generate_bucket_url(data)
- Generate Bucket URL [