feat: Add Kommo integration #237
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new Botpress Kommo integration focused on lead operations (create/get/update), along with initial scaffolding for definitions, config, and API client.
Changes:
- Introduces Kommo integration definition (config schema, icon, hub.md) and TypeScript project setup.
- Implements Kommo API client plus lead actions (create/get/update), with a placeholder
moveLead. - Adds action/event/state definitions for the integration.
Reviewed changes
Copilot reviewed 13 out of 28 changed files in this pull request and generated 15 comments.
Show a summary per file
| File | Description |
|---|---|
| integrations/kommo/tsconfig.json | TypeScript compiler configuration for the new integration. |
| integrations/kommo/package.json | Declares integration package metadata and dependencies. |
| integrations/kommo/package-lock.json | Locks dependency versions for reproducible installs. |
| integrations/kommo/integration.definition.ts | Defines integration metadata + configuration schema + wires actions/events/states. |
| integrations/kommo/icon.svg | Adds the integration icon asset. |
| integrations/kommo/hub.md | Adds integration Hub readme (currently template content). |
| integrations/kommo/deploy.log | Adds a deployment log artifact (should not be committed). |
| integrations/kommo/definitions/index.ts | Re-exports integration definitions. |
| integrations/kommo/definitions/actions/index.ts | Re-exports action definitions. |
| integrations/kommo/definitions/actions/lead.ts | Defines lead action schemas (create/get/update/move). |
| integrations/kommo/definitions/events.ts | Defines lead-related event schemas. |
| integrations/kommo/definitions/states.ts | Defines an OAuth credentials integration state schema. |
| integrations/kommo/src/index.ts | Registers the integration runtime and exports actions (includes moveLead). |
| integrations/kommo/src/actions/lead.ts | Implements runtime handlers for lead actions. |
| integrations/kommo/src/actions/index.ts | Placeholder (currently empty). |
| integrations/kommo/src/kommo-api/types.ts | Adds Kommo API response/request type definitions. |
| integrations/kommo/src/kommo-api/kommo-client.ts | Adds an axios-based Kommo API client (create/get/update lead). |
| integrations/kommo/src/kommo-api/index.ts | Placeholder (currently empty). |
| integrations/kommo/src/kommo-api/error-handling.ts | Placeholder (currently empty). |
| integrations/kommo/src/auth.ts | Placeholder (currently empty). |
| integrations/kommo/src/setup.ts | Placeholder (currently empty). |
| integrations/kommo/src/utils.ts | Placeholder (currently empty). |
| integrations/kommo/src/webhook/index.ts | Placeholder (currently empty). |
| integrations/kommo/src/webhook/handler.ts | Placeholder (currently empty). |
| integrations/kommo/src/webhook/event-payloads.ts | Placeholder (currently empty). |
| integrations/kommo/src/webhook/handlers/index.ts | Placeholder (currently empty). |
| integrations/kommo/src/webhook/handlers/lead-events.ts | Placeholder (currently empty). |
| integrations/kommo/src/webhook/handlers/oauth-callback.ts | Placeholder (currently empty). |
Files not reviewed (1)
- integrations/kommo/package-lock.json: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| import { KommoClient } from '../kommo-api/kommo-client' | ||
| import { CreateLeadRequest, UpdateLeadRequest, KommoLead } from '../kommo-api/types' | ||
|
|
||
| // mapping kommo to loval schema |
There was a problem hiding this comment.
Typo in comment: "loval" should be "local".
| // mapping kommo to loval schema | |
| // mapping kommo to local schema |
| * Source: https://developers.kommo.com/reference/patch-lead | ||
| */ | ||
| export interface UpdateLeadRequest { | ||
| id?: number // Required for update |
There was a problem hiding this comment.
UpdateLeadRequest.id is marked optional but the comment says it's required. Either make the type required (if Kommo expects it in the payload) or update the comment/remove the field if the endpoint is /leads/{id} and doesn’t require an id in the body.
| id?: number // Required for update | |
| id: number // Required for update |
integrations/kommo/hub.md
Outdated
| # Hello World | ||
|
|
||
| This integration is a template with a single action. | ||
|
|
||
| > Describe the integration's purpose. | ||
|
|
||
| ## Configuration | ||
|
|
||
| This integration does not need a configuration. | ||
|
|
||
| > Explain how to configure your integration and list prerequisites `ex: accounts, etc.`. | ||
| > You might also want to add configuration details for specific use cases. | ||
|
|
||
| ## Usage | ||
|
|
||
| To use, call the action `helloWorld`. This action will greet the user. | ||
|
|
||
| > Explain how to use your integration. | ||
| > You might also want to include an example if there is a specific use case. | ||
|
|
||
| ## Limitations | ||
|
|
||
| The `helloWorld` action has a max name size limit of 2^28 - 16 characters (the max javascript string size). | ||
|
|
||
| > List the known bugs. | ||
| > List known limits `ex: rate-limiting, payload sizes, etc.` | ||
| > List unsupported use cases. | ||
|
|
||
| ## Changelog | ||
|
|
||
| - 0.1.0: Implemented `helloWorld` action. | ||
|
|
||
| > If some versions of your integration introduce changes worth mentionning (breaking changes, bug fixes), describe them here. This will help users to know what to expect when updating the integration. | ||
|
|
||
| ### Integration publication checklist | ||
|
|
||
| - [ ] The register handler is implemented and validates the configuration. |
There was a problem hiding this comment.
hub.md is still the template "Hello World" content (mentions helloWorld and says no configuration). Update it to describe Kommo, required configuration (baseDomain, accessToken), and the available lead actions, otherwise the integration listing/readme will be misleading.
| # Hello World | |
| This integration is a template with a single action. | |
| > Describe the integration's purpose. | |
| ## Configuration | |
| This integration does not need a configuration. | |
| > Explain how to configure your integration and list prerequisites `ex: accounts, etc.`. | |
| > You might also want to add configuration details for specific use cases. | |
| ## Usage | |
| To use, call the action `helloWorld`. This action will greet the user. | |
| > Explain how to use your integration. | |
| > You might also want to include an example if there is a specific use case. | |
| ## Limitations | |
| The `helloWorld` action has a max name size limit of 2^28 - 16 characters (the max javascript string size). | |
| > List the known bugs. | |
| > List known limits `ex: rate-limiting, payload sizes, etc.` | |
| > List unsupported use cases. | |
| ## Changelog | |
| - 0.1.0: Implemented `helloWorld` action. | |
| > If some versions of your integration introduce changes worth mentionning (breaking changes, bug fixes), describe them here. This will help users to know what to expect when updating the integration. | |
| ### Integration publication checklist | |
| - [ ] The register handler is implemented and validates the configuration. | |
| # Kommo | |
| This integration connects your bot to Kommo, a CRM and sales management platform. It lets you create and manage leads directly from conversations, keep your pipeline up to date, and log relevant context back into Kommo. | |
| ## Configuration | |
| To use this integration, you need an existing Kommo account with API access enabled. | |
| The following configuration fields are required: | |
| - **`baseDomain`** | |
| The base domain of your Kommo account, for example: `your-company.kommo.com`. | |
| This is used to route all API calls to the correct Kommo workspace. | |
| - **`accessToken`** | |
| A Kommo API access token with permissions to read and manage leads (and any related entities you plan to use). | |
| You can generate an access token from your Kommo account settings / API & Integrations section. Make sure to keep this token secret and rotate it periodically according to your security policies. | |
| After adding `baseDomain` and `accessToken` to the integration configuration in your workspace, the integration will validate them during registration by making a request to Kommo. If the credentials are invalid or lack required permissions, registration will fail with an explanatory error. | |
| ## Usage | |
| Once configured, the Kommo integration exposes actions you can call from your flows to manage leads in your CRM. Typical lead-related actions include: | |
| - **Create leads** from new conversations or form submissions, populating fields such as name, contact details, and source. | |
| - **Update existing leads** when a user provides new information (e.g., phone, email, budget, status). | |
| - **Search or find leads** by identifiers such as email, phone, or custom fields to avoid creating duplicates. | |
| - **Add notes or activities to leads** to log conversation context, qualification details, or next steps. | |
| You can combine these actions to build flows such as: | |
| - Capturing new inquiries as Kommo leads when a user first contacts your bot. | |
| - Looking up an existing lead before answering support or sales questions. | |
| - Enriching a lead record as the conversation progresses. | |
| - Logging follow-up tasks or notes in Kommo at the end of a conversation. | |
| Configure each action in your flow by mapping bot variables to the Kommo lead fields you want to read or write. | |
| ## Limitations | |
| - All operations are subject to Kommo API availability and rate limits defined by your Kommo plan. | |
| - The integration can only access data that the configured `accessToken` is permitted to read or update. | |
| - Data created or updated via the integration may not appear instantly in the Kommo UI if there are synchronization or caching delays on Kommo's side. | |
| ## Changelog | |
| - 0.1.0: Initial Kommo integration with lead management actions (create, update, search, and note logging for leads). | |
| ### Integration publication checklist | |
| - [ ] The register handler is implemented and validates the configuration (`baseDomain`, `accessToken`). |
| // create lead handler | ||
| export const createLead = async ({ | ||
| ctx, | ||
| input, | ||
| logger, | ||
| }: any) => { |
There was a problem hiding this comment.
Action handlers are typed as any, which loses the generated integration typings and makes it easier to pass/return the wrong shapes. In this repo, actions are typically typed as bp.IntegrationProps['actions']['<actionName>'] (e.g. integrations/apollo/src/actions/createContact.ts:6). Consider updating these exports to use the generated .botpress types instead of any.
| // Prepare the request data | ||
| // Only include optional fields if they have valid (non-zero) values | ||
| const leadData: CreateLeadRequest = { | ||
| name: input.name, | ||
| ...(input.price && input.price > 0 && { price: input.price }), |
There was a problem hiding this comment.
price is dropped when it is 0 because the spread condition uses a truthy check (input.price && ...). If 0 is a valid lead price, use an explicit input.price !== undefined (and then validate the allowed range) so 0 can be sent intentionally.
| // Prepare the request data | |
| // Only include optional fields if they have valid (non-zero) values | |
| const leadData: CreateLeadRequest = { | |
| name: input.name, | |
| ...(input.price && input.price > 0 && { price: input.price }), | |
| // Validate optional numeric fields | |
| if (input.price !== undefined && input.price < 0) { | |
| throw new Error('Invalid price: must be greater than or equal to 0') | |
| } | |
| // Prepare the request data | |
| // Only include optional fields if they have valid values | |
| const leadData: CreateLeadRequest = { | |
| name: input.name, | |
| ...(input.price !== undefined && { price: input.price }), |
| import * as bp from '../../.botpress' | ||
| import { CreateLeadRequest, KommoLead, KommoCreateResponse, KommoGetResponse, UpdateLeadRequest } from './types' | ||
|
|
||
| // handles api communcation with kommo |
There was a problem hiding this comment.
Typo in comment: "communcation" should be "communication" (and consider capitalizing the sentence for readability).
| import { z } from '@bpinternal/zui' | ||
| import { ActionDefinition } from '@botpress/sdk' |
There was a problem hiding this comment.
This integration imports z from @bpinternal/zui, but other integrations consistently import z from @botpress/sdk (e.g. integrations/pipedrive/definitions/actions/person.ts:1). To follow repo conventions and avoid relying on an internal package, switch this import to @botpress/sdk.
| import { EventDefinition } from '@botpress/sdk' | ||
| import { z } from '@bpinternal/zui' |
There was a problem hiding this comment.
This file imports z from @bpinternal/zui, while the rest of the repo uses z from @botpress/sdk for event schemas (e.g. integrations/brevo-hitl/src/definitions/events.ts:1). Aligning to @botpress/sdk keeps schema types consistent and avoids depending on an internal package.
| import { StateDefinition } from '@botpress/sdk' | ||
| import { z } from '@bpinternal/zui' |
There was a problem hiding this comment.
This file imports z from @bpinternal/zui, but state schemas in the repo use z from @botpress/sdk (e.g. integrations/mailerlite/definitions/states.ts:1). Consider switching to @botpress/sdk to match conventions and avoid relying on an internal package.
| logger.forBot().info('Moving lead:', input) | ||
|
|
||
| const { baseDomain, accessToken } = ctx.configuration | ||
| const kommoClient = new KommoClient(accessToken, baseDomain, logger) |
There was a problem hiding this comment.
Unused variable kommoClient.
| const kommoClient = new KommoClient(accessToken, baseDomain, logger) |
| @@ -0,0 +1,17 @@ | |||
| { | |||
There was a problem hiding this comment.
issue: Add to pnpm workspace in the repo
integrations/kommo/package.json
Outdated
| @@ -0,0 +1,17 @@ | |||
| { | |||
| "name": "kommo-integration", | |||
There was a problem hiding this comment.
suggestion: just kommo
integrations/kommo/package.json
Outdated
| }, | ||
| "private": true, | ||
| "dependencies": { | ||
| "@botpress/client": "1.28.0", |
There was a problem hiding this comment.
todo: check if these are latest versions
yueranlu
changed the title
Added Kommo integration with the features for leads implemented.