Integração do Zoho Sales IQ HITL

# Zoho SalesIQ HITL (Human-in-the-Loop) Integration

This integration allows Botpress to seamlessly escalate conversations from a chatbot to a live agent in Zoho SalesIQ. When a user requests human assistance, the bot initiates a new conversation in Zoho SalesIQ and enables real-time communication between the user and a human agent.

How It Works

Conversation Start:

When a user requests live agent support, the bot calls Zoho SalesIQ's Open Conversation API to create a new session.
The Botpress HITL interface keeps track of the conversation ID.

Message Handling:

User messages are forwarded to the Zoho SalesIQ Send Message API, allowing the visitor to communicate with the assigned agent.

Operator Events Tracking:

The integration listens for Zoho SalesIQ webhook events, such as:
- Agent Assignment (operatorAssignedUpdate)
- Conversation Resolved (operatorConversationComplete)
- Missed Conversations (operatorConversationMissed)
- Agent Messages (operatorSendMessage)

Closing Conversations:

Once an agent resolves the conversation, Botpress will update the session and notify the chatbot.

Zoho SalesIQ Integration Setup Guide

Loom video walk through setting up the OAuth configuration.

Step 1: Create a Zoho Developer Account

Open the Zoho API Console:
https://api-console.zohocloud.ca/add?client_type=ORG
Sign in or create a Zoho Developer account if needed.
Create a new OAuth client.
Set the Redirect URI to your Botpress webhook URL.

Step 2: Generate an Authorization Code

Ensure you use the correct region URL for OAuth authentication.

Zoho Accounts Domains:

Region	Accounts URL
US	`https://accounts.zoho.com`
AU	`https://accounts.zoho.com.au`
EU	`https://accounts.zoho.eu`
IN	`https://accounts.zoho.in`
CN	`https://accounts.zoho.com.cn`
JP	`https://accounts.zoho.jp`
SA (Saudi Arabia)	`https://accounts.zoho.sa`
CA (Canada)	`https://accounts.zohocloud.ca`

Construct the following authorization URL, replacing placeholders with your actual values:

https://accounts.zohocloud.ca/oauth/v2/org/auth?response_type=code
&client_id=YOUR_CLIENT_ID
&scope=SalesIQ.Conversations.ALL,SalesIQ.apps.read
&redirect_uri=YOUR_REDIRECT_URI
&access_type=offline
&state=123

Replace YOUR_CLIENT_ID with your Zoho Client ID.
Replace YOUR_REDIRECT_URL with your Botpress webhook URL.
Ensure the scope is set to SalesIQ.Conversations.ALL.

Get Authorization Code

Open the modified URL in a browser.
Click Accept when prompted.
Copy the authorization code from the redirected URL, which will look something like:

   https://webhook.botpress.cloud/2fca97ae-3078-4287-87a2-957e7f68157a?state=123&code=1005.4e8ee2431c3713671170956c8f8ed585.8ac5720917a810e6d447df63d2b63aef&location=ca&accounts-server=https%3A%2F%2Faccounts.zohocloud.ca

The code parameter (1005.4e8ee2431c...) is your authorization code.

Step 3: Exchange Authorization Code for Access Token

Run the following cURL command, replacing placeholders with your actual credentials:

curl -X POST "ACCOUNTS_URL_REGION/oauth/v2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "code=YOUR_CODE" \
     -d "grant_type=authorization_code" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=YOUR_REDIRECT_URI" \
     -d "scope=SalesIQ.Conversations.ALL,SalesIQ.apps.read"

Replace YOUR_CODE with the authorization code from Step 2.
Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and YOUR_REDIRECT_URL with your actual values.

Step 4: Store Credentials in Your Integration

After making the request, you will receive a response containing an access token and a refresh token. Store the following credentials in your integration configuration:

Client ID
Client Secret
Access Token
Refresh Token

Step 5: Retrieve Required Zoho IDs

To fully integrate with Zoho SalesIQ, you need to gather the following details:

1. Get Your Screen Name

Visit your Zoho SalesIQ Home Page. https://salesiq.zohocloud.ca/
Your Screen Name is displayed on this page in the URL at the top of your browser, for example, envyroinc is the screen name here https://salesiq.zohocloud.ca/envyroinc/mychats.

2. Get Your Department ID

Go to Settings > Departments in Zoho SalesIQ.
Click on the correct department.
The Department ID is in the URL:

   https://salesiq.zohocloud.ca/envyroinc/settings/departments/edit/6338000000002024

Example Department ID: 6338000000002024

3. Get Your App ID

Go to Settings > Brands in Zoho SalesIQ.
Click on the correct brand.
The App ID is in the URL:

   https://salesiq.zohocloud.ca/envyroinc/settings/brands/6338000000002238

Example App ID: 6338000000002238

Step 6: Final Integration Configuration Setup

Enter the following details into your integration configuration:

✅ Screen Name
✅ App ID
✅ Department ID

How to Set Up a Webhook in SalesIQ for Botpress

Follow these steps to integrate your SalesIQ account with Botpress using webhooks.

Step 1: Navigate to Webhooks in SalesIQ

Log in to your SalesIQ account.
Click on Settings in the sidebar.
Scroll down and select Webhooks.

Step 2: Add a New Webhook

Click Add a New Data Modifications Webhook.
Select the correct brand/organization for which you want to configure the webhook.

Step 3: Configure the Webhook

In the URL to be invoked field, copy and paste your Botpress webhook URL.

Step 4: Select Webhook Events

Check the following events to be associated with the webhook:

conversation.attender.updated
conversation.missed
conversation.operator.replied
conversation.completed

Step 5: Save Your Webhook

Click the Create Webhook button to finalize your webhook setup.

That's it! Your webhook is now configured to send SalesIQ events to Botpress.

# **Zoho SalesIQ HITL (Human-in-the-Loop) Integration** This integration allows Botpress to **seamlessly escalate conversations** from a chatbot to a live agent in **Zoho SalesIQ**. When a user requests human assistance, the bot initiates a **new conversation** in Zoho SalesIQ and enables real-time communication between the user and a human agent. ### **How It Works** 1. **Conversation Start**: - When a user requests live agent support, the bot calls **Zoho SalesIQ's Open Conversation API** to create a new session. - The **Botpress HITL interface** keeps track of the conversation ID. 2. **Message Handling**: - User messages are forwarded to the **Zoho SalesIQ Send Message API**, allowing the visitor to communicate with the assigned agent. 3. **Operator Events Tracking**: - The integration listens for **Zoho SalesIQ webhook events**, such as: - **Agent Assignment (`operatorAssignedUpdate`)** - **Conversation Resolved (`operatorConversationComplete`)** - **Missed Conversations (`operatorConversationMissed`)** - **Agent Messages (`operatorSendMessage`)** 4. **Closing Conversations**: - Once an agent **resolves the conversation**, Botpress will update the session and notify the chatbot. --- # Zoho SalesIQ Integration Setup Guide ### **[Loom video walk through setting up the OAuth configuration.](https://www.loom.com/share/d3c758e372e54a32b4f29d7da44af1ce?sid=38c81c81-486e-4a48-bfb1-941b02d052d1)** ### ## Step 1: Create a Zoho Developer Account 1. Open the Zoho API Console: [https://api-console.zohocloud.ca/add?client_type=ORG](https://api-console.zohocloud.ca/add?client_type=ORG) 2. Sign in or create a Zoho Developer account if needed. 3. Create a new OAuth client. 4. Set the **Redirect URI** to your **Botpress webhook URL**. ## Step 2: Generate an Authorization Code Ensure you use the **correct region URL** for OAuth authentication. #### **Zoho Accounts Domains:** | Region | Accounts URL | |---------------|----------------------------------| | US | `https://accounts.zoho.com` | | AU | `https://accounts.zoho.com.au` | | EU | `https://accounts.zoho.eu` | | IN | `https://accounts.zoho.in` | | CN | `https://accounts.zoho.com.cn` | | JP | `https://accounts.zoho.jp` | | SA (Saudi Arabia) | `https://accounts.zoho.sa` | | CA (Canada) | `https://accounts.zohocloud.ca` | Construct the following authorization URL, replacing placeholders with your actual values: ```text https://accounts.zohocloud.ca/oauth/v2/org/auth?response_type=code &client_id=YOUR_CLIENT_ID &scope=SalesIQ.Conversations.ALL,SalesIQ.apps.read &redirect_uri=YOUR_REDIRECT_URI &access_type=offline &state=123 ``` - Replace `YOUR_CLIENT_ID` with your **Zoho Client ID**. - Replace `YOUR_REDIRECT_URL` with your **Botpress webhook URL**. - Ensure the scope is set to `SalesIQ.Conversations.ALL`. ### Get Authorization Code 1. Open the modified URL in a browser. 2. Click **Accept** when prompted. 3. Copy the **authorization code** from the redirected URL, which will look something like: ```text https://webhook.botpress.cloud/2fca97ae-3078-4287-87a2-957e7f68157a?state=123&code=1005.4e8ee2431c3713671170956c8f8ed585.8ac5720917a810e6d447df63d2b63aef&location=ca&accounts-server=https%3A%2F%2Faccounts.zohocloud.ca ``` 4. The `code` parameter (`1005.4e8ee2431c...`) is your **authorization code**. ## Step 3: Exchange Authorization Code for Access Token Run the following cURL command, replacing placeholders with your actual credentials: ```sh curl -X POST "ACCOUNTS_URL_REGION/oauth/v2/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "code=YOUR_CODE" \ -d "grant_type=authorization_code" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "redirect_uri=YOUR_REDIRECT_URI" \ -d "scope=SalesIQ.Conversations.ALL,SalesIQ.apps.read" ``` - Replace `YOUR_CODE` with the **authorization code** from Step 2. - Replace `YOUR_CLIENT_ID`, `YOUR_CLIENT_SECRET`, and `YOUR_REDIRECT_URL` with your actual values. ## Step 4: Store Credentials in Your Integration After making the request, you will receive a response containing an **access token** and a **refresh token**. Store the following credentials in your integration configuration: - **Client ID** - **Client Secret** - **Access Token** - **Refresh Token** ## Step 5: Retrieve Required Zoho IDs To fully integrate with **Zoho SalesIQ**, you need to gather the following details: ### 1. Get Your Screen Name - Visit your **Zoho SalesIQ Home Page**. [https://salesiq.zohocloud.ca/](https://salesiq.zohocloud.ca/) - Your **Screen Name** is displayed on this page in the URL at the top of your browser, for example, envyroinc is the screen name here https://salesiq.zohocloud.ca/envyroinc/mychats. ### 2. Get Your Department ID 1. Go to **Settings > Departments** in **Zoho SalesIQ**. 2. Click on the correct department. 3. The **Department ID** is in the URL: ```text https://salesiq.zohocloud.ca/envyroinc/settings/departments/edit/6338000000002024 ``` - Example **Department ID**: `6338000000002024` ### 3. Get Your App ID 1. Go to **Settings > Brands** in **Zoho SalesIQ**. 2. Click on the correct brand. 3. The **App ID** is in the URL: ```text https://salesiq.zohocloud.ca/envyroinc/settings/brands/6338000000002238 ``` - Example **App ID**: `6338000000002238` ## Step 6: Final Integration Configuration Setup Enter the following details into your integration configuration: ✅ **Screen Name** ✅ **App ID** ✅ **Department ID** # How to Set Up a Webhook in SalesIQ for Botpress Follow these steps to integrate your SalesIQ account with Botpress using webhooks. ## Step 1: Navigate to Webhooks in SalesIQ 1. **Log in** to your SalesIQ account. 2. Click on **Settings** in the sidebar. 3. Scroll down and select **Webhooks**. ## Step 2: Add a New Webhook 4. Click **Add a New Data Modifications Webhook**. 5. Select the **correct brand/organization** for which you want to configure the webhook. ## Step 3: Configure the Webhook 6. In the **URL to be invoked** field, **copy and paste** your Botpress webhook URL. ## Step 4: Select Webhook Events 7. Check the following events to be associated with the webhook: - `conversation.attender.updated` - `conversation.missed` - `conversation.operator.replied` - `conversation.completed` ## Step 5: Save Your Webhook 8. Click the **Create Webhook** button to finalize your webhook setup. **That's it!** Your webhook is now configured to send SalesIQ events to Botpress.

Zoho Sales IQ HITL