README.md in qismo-0.12.1 vs README.md in qismo-0.13.0
- old
+ new
@@ -10,62 +10,78 @@
bundle add qismo
```
## Usage
-### Initialize and make request
-
-To start using Qismo ruby, you must get your account's `App ID` and `Qiscus Secret Key` which can be checked in your admin dashboard's [settings page](https://omnichannel.qiscus.com/settings). After getting these data, you can start initialize the client.
-
```ruby
-Qismo.configure do |client|
- client.app_id = "YOU_ACCOUNT_APP_ID"
- client.secret_key = "YOUR_ACCOUNT_SECRET_KEY"
+# config/initializers/qismo.rb
- ## Optional
- client.url = "https://qismo.qiscus.com"
- client.logger = { logger: Logger.new($stdout) }
- client.instrumentation = { instrumenter: ActiveSupport::Notifications.instrumenter }
- client.timeout = { connect: 5, write: 2, read: 5 }
- client.proxy = ["proxy-hostname.local", 8080, "username", "password"]
+Qismo.configure do |client|
+ client.app_id = ENV["QISCUS_APP_ID"]
+ client.secret_key = ENV["QISCUS_SECRET_KEY"]
end
```
-Then, start requesting to any endpoint yg want
+Then, start requesting to available endpoint
```ruby
params = {
- channel: { id: 12345, source: "wa" },
+ channel: { channel_id: 12345, source: "wa" },
status: "unresolved",
serve_status: "served",
- is_handled_by_bot: false,
+ is_handled_by_bot: true,
}
+# List rooms
rooms = Qismo.rooms(params)
-```
-If your app manage multiple app id, you initialize the client like below
-
-```ruby
-client = Qismo::Client.new(app_id: "YOUR_ACCOUNT_APP_ID", secret_key: "YOUR_ACCOUNT_SECRET_KEY")
+puts rooms
+# [
+# #<Qismo::SingleObject
+# channel_id=6171,
+# contact_id=71716,
+# id=181917,
+# is_handled_by_bot=true,
+# is_resolved=false,
+# is_waiting=false,
+# last_comment_sender="admin@qismo.com",
+# last_comment_sender_type="system",
+# last_comment_text="Agent joined this conversation",
+# last_comment_timestamp="2022-12-09T04:25:55Z",
+# last_customer_comment_text=nil,
+# last_customer_timestamp="2022-11-28T09:03:08Z",
+# name="Customer - Yogyakarta",
+# room_badge="https://multichannel.qiscus.com/img/whatsapp_badge.svg",
+# room_id="8191816171",
+# room_type="individual",
+# source="wa",
+# user_avatar_url="https://multichannel.qiscus.com/img/default_avatar.svg",
+# user_id="628155555711"
+# >
+# ]
```
-Then, start requesting to an endpoint using that `client` variable
+## Multiple app id client initialization
```ruby
+client = Qismo::Client.new(app_id: "QISCUS_APP_ID", secret_key: "QISCUS_SECRET_KEY")
+
params = {
- channel: { id: 12345, source: "wa" },
+ channel: { channel_id: 12345, source: "wa" },
status: "unresolved",
serve_status: "served",
- is_handled_by_bot: false,
+ is_handled_by_bot: true,
}
-rooms = client.rooms(params)
+# This will produce same result as explained before
+client.rooms(params)
```
-### Client configuration
+## Client optional configuration
+Qismo ruby also provide some optional configuration that you can pass, they are:
+
**url**
Defaultly, Qismo ruby will use your QISCUS_OMNICHANNEL_URL env as base url. If its nil, it will use https://qismo.qiscus.com. If you need to customize URL other than that, you can pass it at client initialization
```ruby
@@ -128,11 +144,11 @@
```ruby
client.proxy = ["proxy-hostname.local", 8080, "username", "password"]
```
-### Handling pagination
+## Handling pagination
Some of the Qiscus Omnichannel API will return list of data with pagination. To handle the pagination, you can to that like this example:
```ruby
all_rooms = []
@@ -143,18 +159,102 @@
rooms = rooms.next_page
all_rooms.append(rooms)
end
```
-### Handling error
+## Handling error
Qismo ruby raise error while getting non successful http code from Qiscus Omnichannel API. To handle it, you follow this example:
```ruby
begin
client.rooms
rescue Qismo::HTTPRequestError => e
e.message
e.status_code
e.response_body
+end
+```
+
+## Handle incoming webhook request
+
+Qiscus Omnichannel provide webhooks that triggered from various action on your account. Qismo ruby gem provide convenient way to handle the request.
+
+```ruby
+class QiscusWebhooksController < ApplicationController
+ skip_before_action :verify_authenticity_token
+
+ def handle_agent_allocation_webhook
+ webhook = Qismo::WebhookRequests::OnAgentAllocationNeeded.new(JSON.parse(request.raw_body))
+
+ # Do any action you want using payload that has been objectified
+ if webhook.candidate_agent.present?
+ Qismo.assign_agent(
+ webhook.room_id,
+ webhook.candidate_agent.id
+ )
+ end
+ end
+
+ def handle_custom_button_webhook
+ webhook = Qismo::WebhookRequests::OnCustomButtonClicked.new(JSON.parse(request.raw_body))
+
+ # Do any action you want using payload that has been objectified. The
+ # following example assuming you want to create Zendesk ticket
+ # everytime your agent click custom button "Create Ticket". We are
+ # assuming, you have setup Zendesk ruby client
+ zendesk_ticket_subject = webhook.additional_info.find do |info|
+ info.key == "Zendesk Ticket Subject"
+ end
+
+ if zendesk_ticket_subject.present?
+ ZendeskAPI::Ticket.create!(
+ zendesk_client,
+ subject: zendesk_ticket_subject.value,
+ submitter_id: webhook.agent.email,
+ priority: "urgent"
+ )
+ end
+ end
+
+ def handle_custom_channel_webhook
+ webhook = Qismo::WebhookRequests::OnCustomChannelMessageSent.new(JSON.parse(request.raw_body))
+
+ # Do any action you want
+ # The following example assuming you want to reply customer's message from Twitter
+ # Assuming that you have installed and setup twitter ruby client
+
+ # Fetch customer from room participants
+ customer = webhook.payload.room.participants.find { |participant| participant.email.start_with?("twitter_customer_") }
+ if customer.present?
+ twitter_rest_client.create_direct_message(webhook.payload.rooms, webhook.payload.message.text)
+ end
+ end
+
+ def handle_bot_webhook
+ webhook = Qismo::WebhookRequests::OnMessageForBotSent.new(JSON.parse(request.raw_body))
+
+ # Do any action you want. The following example assuming you want to use
+ # Dialogflow as bot engine
+
+ # Detect intent for customer's message
+ response = dialogflow_client.detect_intent(
+ session: "session_#{webhook.payload.room.id}",
+ query_input: {
+ text: {
+ text: webhook.payload.message.text,
+ language_code: "en-US"
+ }
+ }
+ )
+
+ # Parse bot message which will be sent back to customer
+ bot_message = response.query_result.fulfillment_text
+
+ # Send message to Qismo room
+ Qismo.send_bot_message(
+ webhook.payload.room.id,
+ message: bot_message
+ )
+ end
end
```