[pull] master from botpress:master

.github/workflows/deploy-integrations-production.yml

@@ -31,7 +31,7 @@ jobs:
         uses: ./.github/actions/deploy-integrations
         with:
           environment: 'production'
-          extra_filter: "-F '!docusign'"
+          extra_filter: "-F '!docusign' -F '!zendesk-messaging-hitl'"
           force: ${{ github.event.inputs.force == 'true' }}
           sentry_auth_token: ${{ secrets.SENTRY_AUTH_TOKEN }}
           token_cloud_ops_account: ${{ secrets.PRODUCTION_TOKEN_CLOUD_OPS_ACCOUNT }}

.github/workflows/deploy-integrations-staging.yml

@@ -39,6 +39,7 @@ jobs:
         uses: ./.github/actions/deploy-integrations
         with:
           environment: 'staging'
+          extra_filter: "-F '!zendesk-messaging-hitl'"
           force: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.force == 'true' }}
           dry_run: ${{ github.event_name == 'pull_request' }}
           sentry_auth_token: ${{ secrets.SENTRY_AUTH_TOKEN }}

integrations/zendesk-messaging-hitl/.gitignore

@@ -0,0 +1 @@
+.botpress

integrations/zendesk-messaging-hitl/eslint.config.mjs

@@ -0,0 +1,13 @@
+import rootConfig from '../../eslint.config.mjs'
+
+export default [
+  ...rootConfig,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+]

integrations/zendesk-messaging-hitl/hub.md

@@ -0,0 +1,56 @@
+# Zendesk Messaging HITL
+
+## Description
+
+This integration makes Sunshine Conversations (Sunco) available as a channel for Human-in-the-loop on Botpress, integrated with Zendesk. When a user requests to speak with an agent, a conversation will be created in Sunshine Conversations and passed to Zendesk Agent Workspace for agent handling.
+
+## Configuration
+
+You will need to have access to your **Zendesk Account** account to configure this integration.
+
+### Configuration fields on Botpress
+
+- **App ID**: Your Sunshine Conversations App ID
+- **Key ID**: Your Sunshine Conversations Key ID
+- **Key Secret**: Your Sunshine Conversations Key Secret
+
+### Automatic Setup
+
+When you register this integration, it will automatically:
+
+1. Create a Integration in Zendesk Account with the name `botpress-hitl-{webhookId}`
+2. Configure the webhook to receive events from Zendesk Messaging
+3. Set up the integration to handle messages and switchboard events
+
+The webhook URL is automatically configured during registration
+
+## Enabling Multi Conversations
+
+Please enable multi conversations in Zendesk Messaging, you need to configure your Zendesk account settings:
+
+1. Go to your Zendesk Admin Center
+2. Navigate to **Channels** > **Messaging and social** > **Manage Settings**
+3. Enable **Multi conversations**
+
+When multi conversations is enabled, each new HITL session will create a separate conversation in Zendesk, allowing for better organization and handling of multiple support requests from the same customer.
+
+## Ending Sessions
+
+### Overview
+
+Ending messaging sessions allows you to stop further interaction via messaging without closing tickets. This is useful to end a hitl session so the user can get back to the bot.
+
+Please allow the agent to end sessions for a better hitl experience, otherwise, only the user will be able to do it
+
+1. Go to your Zendesk Admin Center
+2. Navigate to **Channels** > **Messaging and social** > **Manage Settings**
+3. Enable **Ending messaging sessions**
+
+### Agent Actions
+
+Agents can end messaging sessions at any time through the Zendesk Agent Workspace interface. When a session is ended:
+
+1. The messaging channel for that conversation is closed and user is sent back to the bot
+2. The ticket remains open for email follow-up.
+3. A new hitl sessions from the customer will create a new ticket
+4. The agent's capacity is automatically released

integrations/zendesk-messaging-hitl/integration.definition.ts

@@ -0,0 +1,147 @@
+import * as sdk from '@botpress/sdk'
+import { sentry as sentryHelpers } from '@botpress/sdk-addons'
+import hitl from './bp_modules/hitl'
+
+export default new sdk.IntegrationDefinition({
+  name: 'zendesk-messaging-hitl',
+  version: '0.1.0',
+  title: 'Zendesk Messaging HITL',
+  description: 'This integration allows your bot to use Sunshine Conversations (Sunco) as a HITL Provider for Zendesk',
+  icon: 'icon.svg',
+  readme: 'hub.md',
+  configuration: {
+    schema: sdk.z.object({
+      appId: sdk.z.string().min(1).title('App ID').describe('Your Sunshine Conversations App ID'),
+      keyId: sdk.z.string().min(1).title('Key ID').describe('Your Sunshine Conversations Key ID'),
+      keySecret: sdk.z.string().min(1).title('Key Secret').describe('Your Sunshine Conversations Key Secret'),
+    }),
+  },
+  states: {
+    switchboardIntegrationIds: {
+      type: 'integration',
+      schema: sdk.z.object({
+        switchboardIntegrationId: sdk.z
+          .string()
+          .title('Switchboard Integration ID')
+          .describe('The ID of the Botpress switchboard integration used for HITL sessions')
+          .optional(),
+        agentWorkspaceSwitchboardIntegrationId: sdk.z
+          .string()
+          .title('Agent Workspace Switchboard Integration ID')
+          .describe('The ID of the Zendesk Agent Workspace switchboard integration')
+          .optional(),
+      }),
+    },
+  },
+  channels: {},
+  events: {},
+  user: {
+    tags: {
+      id: {
+        title: 'User ID',
+        description: 'The Sunshine Conversations user ID',
+      },
+      email: {
+        title: 'Email',
+        description: 'The email address of the Sunshine Conversations user',
+      },
+    },
+  },
+  entities: {
+    hitlConversation: {
+      title: 'HITL Conversation',
+      description: 'A support request',
+      schema: sdk.z.object({
+        priority: sdk.z
+          .enum(['Low', 'Medium', 'High', 'Urgent'])
+          .title('Priority')
+          .describe('Priority of the conversation. Leave empty for default priority.')
+          .optional(),
+        originSourceType: sdk.z
+          .enum([
+            'android',
+            'ios',
+            'web',
+            'sdk',
+            'apple',
+            'googlercs',
+            'instagram',
+            'kakao',
+            'line',
+            'mailgun',
+            'messagebird',
+            'messenger',
+            'slackconnect',
+            'telegram',
+            'twilio',
+            'twitter',
+            'viber',
+            'wechat',
+            'whatsapp',
+          ])
+          .title('Origin Source Type')
+          .describe(
+            'The channel where this conversation originated from. Leave empty to default to SUNSHINE CONVERSATIONS API.'
+          )
+          .optional(),
+        organizationId: sdk.z
+          .string()
+          .title('Organization Id')
+          .describe('The organization ID to assign the ticket to.')
+          .optional(),
+        brandId: sdk.z.string().title('Brand Id').describe('The brand ID to assign the ticket to.').optional(),
+        groupId: sdk.z.string().title('Group Id').describe('The group ID to assign the ticket to.').optional(),
+        assigneeId: sdk.z.string().title('Assignee Id').describe('The assignee ID to assign the ticket to.').optional(),
+        tags: sdk.z.array(sdk.z.string()).title('Tags').describe('Tags to add to the ticket.').optional(),
+        customTicketFields: sdk.z
+          .array(
+            sdk.z.object({
+              id: sdk.z.string().min(1).title('Custom Field ID').describe('The ID of the custom field in Zendesk'),
+              value: sdk.z
+                .string()
+                .min(1)
+                .title('Custom Field Value')
+                .describe('The value to set for this custom field'),
+            })
+          )
+          .title('Custom Ticket Fields')
+          .describe(
+            'Custom ticket fields to set on the ticket. The id should be the ticket field ID, and the value should be the field value. Example: { "40033266756891": "value" }'
+          )
+          .optional(),
+        additionalMetadata: sdk.z
+          .array(
+            sdk.z.object({
+              key: sdk.z.string().min(1).title('Metadata Key').describe('The metadata key to add'),
+              value: sdk.z.string().min(1).title('Metadata Value').describe('The value to set for this metadata key'),
+            })
+          )
+          .title('Additional Metadata')
+          .describe('Additional metadata fields to add directly to the metadata object.')
+          .optional(),
+      }),
+    },
+  },
+  secrets: sentryHelpers.COMMON_SECRET_NAMES,
+}).extend(hitl, (self) => ({
+  entities: { hitlSession: self.entities.hitlConversation },
+  channels: {
+    hitl: {
+      title: 'Zendesk Messaging',
+      description: 'Zendesk Messaging HITL',
+      conversation: {
+        tags: {
+          id: { title: 'Sunco Conversation Id', description: 'Sunco Conversation Id' },
+        },
+      },
+      message: {
+        tags: {
+          id: {
+            title: 'Sunco Message ID',
+            description: 'The ID of the message in Sunco',
+          },
+        },
+      },
+    },
+  },
+}))

integrations/zendesk-messaging-hitl/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@botpresshub/zendesk-messaging-hitl",
+  "description": "Zendesk Messaging HITL integration for Botpress",
+  "private": true,
+  "scripts": {
+    "build": "bp add -y && bp build",
+    "check:type": "tsc --noEmit",
+    "check:bplint": "bp lint"
+  },
+  "dependencies": {
+    "@botpress/cli": "workspace:*",
+    "@botpress/client": "workspace:*",
+    "@botpress/common": "workspace:*",
+    "@botpress/sdk": "workspace:*",
+    "@botpress/sdk-addons": "workspace:*",
+    "sunshine-conversations-client": "^9.12.0"
+  },
+  "devDependencies": {
+    "@botpress/cli": "workspace:*",
+    "@botpress/common": "workspace:*",
+    "@sentry/cli": "^2.39.1"
+  },
+  "bpDependencies": {
+    "hitl": "../../interfaces/hitl"
+  }
+}