Crisp API Wrapper

The Crisp API Ruby wrapper. Authenticate, send messages, fetch conversations, access your agent accounts from your Ruby code.

📝 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.send_message_in_conversation(
  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);

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.get_messages_in_conversation(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.send_message_in_conversation(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.update_message_in_conversation(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.compose_message_in_conversation(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.mark_messages_read_in_conversation(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.mark_messages_delivered_in_conversation(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.get_conversation_metas(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" => "[email protected]",
  "segments" => [
    "happy",
    "customer",
    "love"
  ],
  "data" => [
    "type" => "customer",
    "signup" => "finished"
  ]
]

client.website.update_conversation_metas(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.block_incoming_messages_for_conversation(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" => "[email protected]"
]

client.website.request_email_transcript_for_conversation(website_id, session_id, data);

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" => "[email protected]",
  "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" => "[email protected]",
  "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" => "[email protected]",
  "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)

👉 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);

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

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

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" => "[email protected]",
    "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,
    "overlay_search" => true,
    "overlay_mode" => false,
    "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);

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

Bucket

Bucket URL
- Generate Bucket URL [user, plugin]: Reference
  - client.bucket.generate_bucket_url(data)

Name		Name	Last commit message	Last commit date
Latest commit History 87 Commits
.github/workflows		.github/workflows
examples		examples
lib		lib
.gitignore		.gitignore
EXAMPLES.md		EXAMPLES.md
Gemfile		Gemfile
LICENSE		LICENSE
README.md		README.md
crisp-api.gemspec		crisp-api.gemspec

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Crisp API Wrapper

Usage

Authentication

Resource Methods

Website

Bucket

About

Contributors 11

Languages

License

crisp-im/ruby-crisp-api

Folders and files

Latest commit

History

Repository files navigation

Crisp API Wrapper

Usage

Authentication

Resource Methods

Website

Bucket

About

Resources

License

Stars

Watchers

Forks

Contributors 11

Languages