# Botpress Integration: Zoho CRM
## **Zoho CRM Integration Guide**
For further details, refer to the [**Zoho CRM API documentation**](https://www.zoho.com/crm/developer/docs/api/v7/).
## **Overview**
This Botpress integration allows seamless interaction with **Zoho CRM**. It enables users to manage contacts, deals, appointments, and files directly through their chatbot.
## **Features**
- **Record Management:** Create, retrieve, update, delete, and search records.
- **Appointments Management:** Create, update, retrieve, and delete appointments.
- **File Management:** Upload and retrieve files.
- **Emails:** Send emails and associate them with records.
- **Organization & User Management:** Retrieve organization details and user information.
## Register Your Application
Before making any API calls using the Zoho Botpress Integration, you must register your application with **Zoho CRM**.
### **[Loom video walk through setting up the OAuth configuration.](https://www.loom.com/share/41c2811c047a48cbb08a2d1b0dc98f69?sid=8cb4d496-2cca-415d-be1d-536a87c73a3a)**
### Steps to Register
1. **Go to the [Zoho Developer Console](https://accounts.zoho.com/developerconsole).**
2. Click **Add Client**.
3. Choose the client type: **Self Client**.
4. Click the **Generate Code** tab and enter the following scopes:
```
ZohoCRM.modules.ALL,ZohoCRM.org.ALL,ZohoCRM.users.ALL,ZohoCRM.settings.ALL,ZohoCRM.send_mail.all.CREATE,ZohoCRM.files.CREATE,ZohoCRM.files.READ
```
5. Set the **time duration** to **10 minutes**.
6. Provide a scope description (This is not vital to the registration).
7. Click **Create**, select your CRM, and click **Create** again.
8. Download your **credentials file**.
### Generate Refresh Token
Now, execute the following **cURL** command to obtain a refresh token. 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` |
### Execute cURL Request
Replace the placeholders (`CLIENT_ID`, `CLIENT_SECRET`, and `AUTHORIZATION_CODE`) with your actual values before executing the request.
```sh
curl --request POST \
--url 'https://YOUR_REGION_ACCOUNT_URL/oauth/v2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET' \
--data 'redirect_uri=YOUR_REDIRECT_URI' \
--data 'code=AUTHORIZATION_CODE'
```
### Expected Response
If the request is successful, you should receive a response similar to the following:
```json
{
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"api_domain": "https://www.zohoapis.com",
"token_type": "Bearer",
"expires_in": 3600
}
```
# Define the Zoho OAuth token endpoint based on your region
$uri = "https://YOUR_REGION_ACCOUNT_URL/oauth/v2/token"
# Define the request body with required parameters
$body = @{
grant_type = "authorization_code"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
redirect_uri = "YOUR_REDIRECT_URI"
code = "AUTHORIZATION_CODE"
}
### Generate Refresh Token using PowerShell (Windows Users)
⚠️ Use this PowerShell command if you're on Windows. Do NOT use cURL—this is for PowerShell only! ⚠️
#### Define the Zoho OAuth token endpoint based on your region
$uri = "https://YOUR_REGION_ACCOUNT_URL/oauth/v2/token"
# Define the request body with required parameters
$body = @{
grant_type = "authorization_code"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
redirect_uri = "YOUR_REDIRECT_URI"
code = "AUTHORIZATION_CODE"
}
##### Convert body to URL-encoded form data
```
$body = $body | ForEach-Object { "$( $_.Key )=$( $_.Value )" } -join "&"
```
#### Send the POST request using Invoke-RestMethod
```
$response = Invoke-RestMethod -Uri $uri -Method Post -ContentType "application/x-www-form-urlencoded" -Body $body
```
#### Output the response
```
$response
```
## Configure Zoho Botpress Integration
Once you have the necessary credentials, navigate to the **Zoho Botpress Integration** configuration page and enter the following details:
- **Client ID**
- **Client Secret**
- **Refresh Token**
- **Region**
This completes the registration and integration process for **Zoho Botpress**. You are now ready to start making authorized API calls.
---
For more details, refer to the [Zoho API Documentation](https://www.zoho.com/crm/developer/docs/).
---
## API Functions & Usage
Below are the available actions in this integration:
### 1️⃣ **Record Management**
#### **Insert Record**
- **Method:** `POST /crm/v7/{module}`
- **Input:**
```json
{
"module": "Leads",
"data": [{ "Last_Name": "Daly", "First_name": "Paul", "Email": "[email protected]" }]
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"code": "SUCCESS",
"message": "Record added",
"status": "success",
"details": {
"id": "27234000000176001",
"Created_By": "Matea Vasileski",
"Modified_By": "Matea Vasileski",
"Created_Time": "2025-02-26T18:39:39-05:00",
"Modified_Time": "2025-02-26T18:39:39-05:00"
}
}
}
```
#### **Get Records**
- **Method:** `GET /crm/v7/{module}`
- **Input:**
```json
{
"module": "Leads",
"params": { "fields": "Email" }
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"id": "27234000000157008",
"Full_Name": "Jim Mulani",
"First_Name": "Jim",
"Last_Name": "Mulani",
"Email": "[email protected]",
"Company": "envy",
"Owner": {
"name": "Matea Vasileski",
"id": "27234000000095001",
"email": "[email protected]"
},
"Created_By": {
"name": "Matea Vasileski",
"id": "27234000000095001",
"email": "[email protected]"
},
"Modified_By": {
"name": "Matea Vasileski",
"id": "27234000000095001",
"email": "[email protected]"
},
"Created_Time": "2025-02-23T21:51:21-05:00",
"Modified_Time": "2025-02-26T18:19:10-05:00",
"Lead_Status": null,
"Lead_Source": null,
"Record_Status": "Available"
}
}
```
#### **Get Record By ID**
- **Method:** `GET /crm/v7/{module}/{recordId}`
- **Input:**
```json
{
"module": "Leads",
"recordId": "27234000000157008"
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"id": "27234000000157008",
"Full_Name": "Jim Mulani",
"First_Name": "Jim",
"Last_Name": "Mulani",
"Email": "[email protected]",
"Company": "envy",
"Owner": {
"name": "Matea Vasileski",
"id": "27234000000095001",
"email": "[email protected]"
},
"Created_By": {
"name": "Matea Vasileski",
"id": "27234000000095001",
"email": "[email protected]"
},
"Modified_By": {
"name": "Matea Vasileski",
"id": "27234000000095001",
"email": "[email protected]"
},
"Created_Time": "2025-02-23T21:51:21-05:00",
"Modified_Time": "2025-02-26T18:19:10-05:00",
"Lead_Status": null,
"Lead_Source": null,
"Record_Status": "Available"
}
}
```
#### **Update Record**
- **Method:** `PUT /crm/v7/{module}/{recordId}`
- **Input:**
```json
{
"module": "Leads",
"recordId": "27234000000162001",
"data": [{ "Email": "[email protected]" }]
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"code": "SUCCESS",
"message": "Record updated",
"status": "success",
"details": {
"id": "27234000000157008",
"Created_By": "Matea Vasileski",
"Modified_By": "Matea Vasileski",
"Created_Time": "2025-02-23T21:51:21-05:00",
"Modified_Time": "2025-02-26T18:55:37-05:00"
}
}
}
```
#### **Delete Record**
- **Method:** `DELETE /crm/v7/{module}/{recordId}`
- **Input:**
```json
{
"module": "Leads",
"recordId": "27234000000162008"
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"code": "SUCCESS",
"message": "Record deleted",
"status": "success",
"details": {
"id": "27234000000157008"
}
}
}
```
#### **Search Records**
- **Method:** `GET /crm/v7/{module}/search`
- **Input:**
```json
{
"module": "Leads",
"criteria": "(First_Name:equals:John)"
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"records": [
{
"id": "27234000000176001",
"Full_Name": "Daly",
"Email": "[email protected]",
"Created_Time": "2025-02-26T18:39:39-05:00",
"Modified_Time": "2025-02-26T18:39:39-05:00",
"Owner": {
"name": "Matea Vasileski",
"email": "[email protected]"
},
"Record_Status": "Available"
},
{
"id": "27234000000174002",
"Full_Name": "Daly",
"Email": "[email protected]",
"Created_Time": "2025-02-26T18:17:10-05:00",
"Modified_Time": "2025-02-26T18:17:10-05:00",
"Owner": {
"name": "Matea Vasileski",
"email": "[email protected]"
},
"Record_Status": "Available"
}
],
"pagination": {
"per_page": 200,
"count": 2,
"page": 1,
"sort_by": "id",
"sort_order": "desc",
"more_records": false
}
}
}
```
---
### 2️⃣ **Appointments Management**
#### **Create Appointment**
- **Method:** `POST /crm/v7/Appointments__s`
- **Input:**
```json
[
{
"Appointment_Name": "Matea - Mowing Service",
"Appointment_For": {
"module": {
"api_name": "Contacts"
},
"name": "k m",
"id": "27234000000163029"
},
"Service_Name": {
"name": "mow",
"id": "27234000000168178"
},
"Appointment_Start_Time": "2025-02-24T19:33:00Z",
"Owner": "27234000000095001",
"Location": "Business Address",
"Address": "Business Address",
"Additional_Information": "",
"Remind_At": [
{
"unit": 30,
"period": "minutes"
}
],
"Price": "$1.00"
}
]
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"code": "SUCCESS",
"message": "Record added",
"status": "success",
"details": {
"id": "27234000000175008",
"Created_By": "Matea Vasileski",
"Modified_By": "Matea Vasileski",
"Created_Time": "2025-02-26T19:21:59-05:00",
"Modified_Time": "2025-02-26T19:21:59-05:00"
}
}
}
```
#### **Get Appointments**
- **Method:** `GET /crm/v7/Appointments__s`
- **Input:**
```json
{
"params": { "fields": "Service_Name" }
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"records": [
{
"id": "27234000000159008",
"Service_Name": {
"name": "mow",
"id": "27234000000168178"
}
}
],
"pagination": {
"per_page": 200,
"count": 1,
"page": 1,
"sort_by": "id",
"sort_order": "desc",
"more_records": false
}
}
}
```
#### **Get Appointment By ID**
- **Method:** `GET /crm/v7/Appointments__s/{appointmentId}`
- **Input:**
```json
{
"appointmentId": "123456"
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"appointment": {
"id": "27234000000175008",
"Appointment_Name": "Matea - Mowing Service",
"Service_Name": {
"name": "mow",
"id": "27234000000168178"
},
"Appointment_For": {
"name": "k m",
"id": "27234000000163029",
"module": "Contacts"
},
"Owner": {
"name": "Matea Vasileski",
"email": "[email protected]"
},
"Created_By": {
"name": "Matea Vasileski",
"email": "[email protected]"
},
"Modified_By": {
"name": "Matea Vasileski",
"email": "[email protected]"
},
"Appointment_Start_Time": "2025-02-24T14:33:00-05:00",
"Appointment_End_Time": "2025-02-24T15:03:00-05:00",
"Duration": 30,
"Status": "Overdue",
"Location": "Business Address",
"Remind_At": [
{
"unit": 30,
"period": "minutes"
}
],
"Created_Time": "2025-02-26T19:21:59-05:00",
"Modified_Time": "2025-02-26T19:21:59-05:00",
"Record_Status": "Available"
}
}
}
```
#### **Update Appointment**
- **Method:** `PUT /crm/v7/Appointments__s/{appointmentId}`
- **Input:**
```json
{
"appointmentId": "27234000000159008",
"data": {
"appointments": [
{
"Appointment_Name": "Update appt",
"Appointment_For": {
"module": "Contacts",
"name": "k m",
"id": "27234000000163029"
},
"Service_Name": {
"name": "mow",
"id": "27234000000168178"
},
"Appointment_Start_Time": "2025-02-24T19:33:00Z",
"Owner": "27234000000095001",
"Location": "Business Address",
"Address": "Business Address",
"Additional_Information": "",
"Remind_At": [
{
"unit": 30,
"period": "minutes"
}
],
"Price": "$1.00"
}
]
}
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"code": "SUCCESS",
"message": "Record updated",
"status": "success",
"details": {
"id": "27234000000159008",
"Created_By": "Matea Vasileski",
"Modified_By": "Matea Vasileski",
"Created_Time": "2025-02-24T19:44:23-05:00",
"Modified_Time": "2025-02-26T19:48:20-05:00"
}
}
}
```
#### **Delete Appointment**
- **Method:** `DELETE /crm/v7/Appointments__s/{appointmentId}`
- **Input:**
```json
{
"appointmentId": "123456"
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"code": "SUCCESS",
"message": "Record deleted",
"status": "success",
"details": {
"id": "27234000000159008"
}
}
}
```
---
### 3️⃣ **File Management**
#### **Upload File**
- **Method:** `POST /crm/v7/files`
- **Input:**
```json
{
"fileUrl": "https://example.com/file.pdf"
}
```
- **Output:**
```json
{
"success": true,
"message": "File uploaded successfully",
"data": {
"code": "SUCCESS",
"message": "File uploaded successfully",
"status": "success",
"details": {
"name": "20250226050635-LO9N1PT0.webp",
"id": "36c38a1979b316686084c58303b1b6cb654eb04f0f1038ed0a8fdf8a6ff28598dceae7f8711509bfd80b56bf8cd4dbba"
}
}
}
```
#### **Get File**
- **Method:** `GET /crm/v7/files/{fileId}`
- **Input:**
```json
{
"fileId": "dcc53e79cfef0810414e8335b0e11d8882a51116f390194f400828673ca4a59492a22be84db32aa8425d0859862491f9"
}
```
- **Output:**
```json
{
"success":true,
"message":"Request successful",
"data": BinaryFileData
}
```
---
### 4️⃣ **Organization & User Management**
#### **Get Organization Details**
- **Method:** `GET /crm/v7/org`
- **Input:**
No input is required.
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"organization": {
"id": "27234000000000684",
"company_name": "Envyro",
"domain_name": "org110000680144",
"primary_email": "[email protected]",
"currency": "Canadian Dollar - CAD",
"currency_symbol": "$",
"time_zone": "America/Toronto",
"country_code": "US",
"license_details": {
"paid": true,
"paid_type": "professional",
"paid_expiry": "2025-03-23T20:00:00-04:00",
"users_license_purchased": 1
},
"created_time": "2024-09-11T11:04:19-04:00"
}
}
}
```
#### **Get Users**
- **Method:** `GET /crm/v7/users`
- **Input:**
```json
{
"params": { "status": "active" }
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"users": [
{
"id": "27234000000095001",
"full_name": "Matea Vasileski",
"email": "[email protected]",
"role": "CEO",
"profile": "Administrator",
"status": "active",
"country": "Canada",
"state": "Ontario",
"time_zone": "America/Toronto",
"created_time": "2024-09-11T11:04:19-04:00",
"modified_time": "2024-09-11T11:04:19-04:00"
},
{
"id": "27234000000103062",
"full_name": "Milos Arsik",
"email": "[email protected]",
"role": "CEO",
"profile": "Administrator",
"status": "closed",
"time_zone": "America/Toronto",
"created_time": "2024-09-16T00:36:14-04:00",
"modified_time": "2024-11-01T12:18:54-04:00"
}
],
"pagination": {
"per_page": 200,
"count": 2,
"page": 1,
"more_records": false
}
}
}
```
---
### 5️⃣ **Emails**
#### **Send Email**
- **Method:** `POST /crm/v7/emails`
- **Input:**
```json
{
"module": "Leads",
"recordId": "123456",
"data": [
{
"from": {
"user_name": "Matea Vasileski",
"email": "[email protected]"
},
"to": [
{
"user_name": "user1",
"email": "[email protected]"
}
],
"cc": [],
"bcc": [],
"subject": "Important Update",
"content": "Here is an important update for you.",
"mail_format": "html"
}
]
}
```
- **Output:**
```json
{
"success": true,
"message": "Request successful",
"data": {
"code": "SUCCESS",
"message": "Your mail has been sent successfully.",
"status": "success",
"details": {
"message_id": "2e660cab6382a85766b68e77778eadf168f923354a69b362ace2e52ce0b934ba"
}
}
}
```
---
