wehub/botpress--botpress
1
0
Fork 0
Code Issues Pull Requests Actions 1 Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
botpress--botpress/integrations/zoho/hub.md
T
wehub-resource-sync 77bb5bf71f chore: import upstream snapshot with attribution
2026-07-13 13:34:48 +08:00

17 KiB
Raw Permalink Blame History

Botpress Integration: Zoho CRM

Zoho CRM Integration Guide

For further details, refer to the Zoho CRM API documentation.

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.

Connect Zoho CRM

Use the Connect with OAuth setup flow in Botpress. The integration will ask for your Zoho data center, redirect you to Zoho for consent, request the required CRM scopes, and securely store the returned OAuth tokens.

The Zoho OAuth app must allow the Botpress callback URL shown by your integration setup. It should use the stable callback path /oauth/wizard/oauth-callback; the OAuth state value is sent separately and should not be included in the registered redirect URI.

The scopes are requested during the authorization flow. They are not configured directly on the Zoho application:

ZohoCRM.modules.ALL,ZohoCRM.org.ALL,ZohoCRM.users.ALL,ZohoCRM.settings.ALL,ZohoCRM.send_mail.all.CREATE,ZohoCRM.files.CREATE,ZohoCRM.files.READ

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
CA (Canada) https://accounts.zohocloud.ca

Manual Configuration

Manual configuration is available as an advanced fallback. Use it only if you need to provide your own Zoho OAuth client credentials and refresh token.

Register Your Application

  1. Go to the Zoho Developer Console.
  2. Click Add Client.
  3. Choose a server-based client type.
  4. Add the Botpress OAuth callback URL as an authorized redirect URI.
  5. Save the client ID and client secret.

Generate Refresh Token

Create an authorization URL with the scopes above, access_type=offline, and prompt=consent. After granting consent, exchange the returned authorization code for OAuth tokens.

Replace the placeholders (CLIENT_ID, CLIENT_SECRET, and AUTHORIZATION_CODE) with your actual values before executing the request.

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'

If successful, Zoho returns a response similar to:

{
  "access_token": "{access_token}",
  "refresh_token": "{refresh_token}",
  "api_domain": "https://www.zohoapis.com",
  "token_type": "Bearer",
  "expires_in": 3600
}

Enter these values in the Manual configuration setup:

  • Client ID
  • Client Secret
  • Refresh Token
  • Region

API Functions & Usage

Below are the available actions in this integration:

1️⃣ Record Management

Insert Record

  • Method: POST /crm/v7/{module}
  • Input: 
    {
  "module": "Leads",
  "data": [{ "Last_Name": "Daly", "First_name": "Paul", "Email": "p.daly@zylker.com" }]
}
  • Output: 
    {
  "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: 
    {
  "module": "Leads",
  "params": { "fields": "Email" }
}
  • Output: 
    {
  "success": true,
  "message": "Request successful",
  "data": {
    "id": "27234000000157008",
    "Full_Name": "Jim Mulani",
    "First_Name": "Jim",
    "Last_Name": "Mulani",
    "Email": "updated@email.com",
    "Company": "envy",
    "Owner": {
      "name": "Matea Vasileski",
      "id": "27234000000095001",
      "email": "matea@envyro.io"
    },
    "Created_By": {
      "name": "Matea Vasileski",
      "id": "27234000000095001",
      "email": "matea@envyro.io"
    },
    "Modified_By": {
      "name": "Matea Vasileski",
      "id": "27234000000095001",
      "email": "matea@envyro.io"
    },
    "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: 
    {
  "module": "Leads",
  "recordId": "27234000000157008"
}
  • Output: 
    {
  "success": true,
  "message": "Request successful",
  "data": {
    "id": "27234000000157008",
    "Full_Name": "Jim Mulani",
    "First_Name": "Jim",
    "Last_Name": "Mulani",
    "Email": "updated@email.com",
    "Company": "envy",
    "Owner": {
      "name": "Matea Vasileski",
      "id": "27234000000095001",
      "email": "matea@envyro.io"
    },
    "Created_By": {
      "name": "Matea Vasileski",
      "id": "27234000000095001",
      "email": "matea@envyro.io"
    },
    "Modified_By": {
      "name": "Matea Vasileski",
      "id": "27234000000095001",
      "email": "matea@envyro.io"
    },
    "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: 
    {
  "module": "Leads",
  "recordId": "27234000000162001",
  "data": [{ "Email": "updated@email.com" }]
}
  • Output:
{
  "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: 
    {
  "module": "Leads",
  "recordId": "27234000000162008"
}
  • Output: 
    {
  "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: 
    {
  "module": "Leads",
  "criteria": "(First_Name:equals:John)"
}
  • Output:
{
  "success": true,
  "message": "Request successful",
  "data": {
    "records": [
      {
        "id": "27234000000176001",
        "Full_Name": "Daly",
        "Email": "p.daly@zylker.com",
        "Created_Time": "2025-02-26T18:39:39-05:00",
        "Modified_Time": "2025-02-26T18:39:39-05:00",
        "Owner": {
          "name": "Matea Vasileski",
          "email": "matea@envyro.io"
        },
        "Record_Status": "Available"
      },
      {
        "id": "27234000000174002",
        "Full_Name": "Daly",
        "Email": "p.daly@zylker.com",
        "Created_Time": "2025-02-26T18:17:10-05:00",
        "Modified_Time": "2025-02-26T18:17:10-05:00",
        "Owner": {
          "name": "Matea Vasileski",
          "email": "matea@envyro.io"
        },
        "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: 
    [
  {
    "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:
{
  "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: 
    {
  "params": { "fields": "Service_Name" }
}
  • Output:
{
  "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: 
    {
  "appointmentId": "123456"
}
  • Output:
{
  "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": "matea@envyro.io"
      },
      "Created_By": {
        "name": "Matea Vasileski",
        "email": "matea@envyro.io"
      },
      "Modified_By": {
        "name": "Matea Vasileski",
        "email": "matea@envyro.io"
      },
      "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: 
    {
  "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:
{
  "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: 
    {
  "appointmentId": "123456"
}
  • Output:
{
  "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:
{
  "fileUrl": "https://example.com/file.pdf"
}
  • Output:
{
  "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:
{
  "fileId": "dcc53e79cfef0810414e8335b0e11d8882a51116f390194f400828673ca4a59492a22be84db32aa8425d0859862491f9"
}
  • Output:
{
    "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:

{
  "success": true,
  "message": "Request successful",
  "data": {
    "organization": {
      "id": "27234000000000684",
      "company_name": "Envyro",
      "domain_name": "org110000680144",
      "primary_email": "matea@envyro.io",
      "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: 
    {
  "params": { "status": "active" }
}
  • Output:
{
  "success": true,
  "message": "Request successful",
  "data": {
    "users": [
      {
        "id": "27234000000095001",
        "full_name": "Matea Vasileski",
        "email": "matea@envyro.io",
        "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": "milos@envyro.io",
        "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: 
    {
  "module": "Leads",
  "recordId": "123456",
  "data": [
    {
      "from": {
        "user_name": "Matea Vasileski",
        "email": "matea@envyro.io"
      },
      "to": [
        {
          "user_name": "user1",
          "email": "milos@envyro.io"
        }
      ],
      "cc": [],
      "bcc": [],
      "subject": "Important Update",
      "content": "Here is an important update for you.",
      "mail_format": "html"
    }
  ]
}
  • Output:
{
  "success": true,
  "message": "Request successful",
  "data": {
    "code": "SUCCESS",
    "message": "Your mail has been sent successfully.",
    "status": "success",
    "details": {
      "message_id": "2e660cab6382a85766b68e77778eadf168f923354a69b362ace2e52ce0b934ba"
    }
  }
}
Reference in New Issue View Git Blame Copy Permalink