@minded-ai/mindedjs 1.0.0-ec2-beta-1

package/docs/integrations/zendesk.md

@@ -0,0 +1,554 @@
+# Zendesk Integration
+
+The Zendesk integration enables your Minded agents to seamlessly interact with Zendesk tickets, conversations, and customer data. This integration provides a complete interface for building intelligent customer support agents that can handle ticket management, customer communication, and workflow automation.
+
+## Overview
+
+The Zendesk integration provides:
+
+- **Ticket Management** - Create, update, and manage ticket status
+- **Customer Communication** - Send messages and comments
+- **Conversation Handling** - Access conversation history and context
+- **Tag Management** - Add and manage ticket tags
+- **Custom Fields** - Set and update custom field values
+- **Search Capabilities** - Search tickets and conversations
+- **Real-time Updates** - Receive and respond to Zendesk events
+
+## Quick Start
+
+### 1. Basic Setup
+
+```typescript
+import { Agent } from '@minded/sdk';
+import { zendesk } from '@minded/sdk/interfaces/zendesk';
+import { events } from '@minded/sdk';
+
+const agent = new Agent({
+  memorySchema: yourMemorySchema,
+  config: mindedConfig,
+  tools: yourTools,
+});
+
+// Initialize Zendesk interface
+zendesk.init(agent);
+
+// Handle AI messages - send them to Zendesk
+agent.on(events.AI_MESSAGE, async ({ message, state }) => {
+  await zendesk.sendMessage(state.sessionId!, message);
+});
+```
+
+### 2. Trigger Configuration
+
+Configure your flow with a Zendesk trigger:
+
+```yaml
+# flows/zendeskFlow.yaml
+name: Zendesk Support Flow
+nodes:
+  - name: Zendesk-Trigger
+    type: trigger
+    triggerType: app
+    appTriggerId: zendesk-interface
+    appTriggerName: Zendesk Minded Conversation
+    appName: Zendesk
+
+  - name: Support-Agent
+    type: promptNode
+    prompt: |
+      You are a helpful customer support agent. 
+      Respond to the customer's inquiry professionally and helpfully.
+
+edges:
+  - source: Zendesk-Trigger
+    target: Support-Agent
+    type: stepForward
+```
+
+## Available Methods
+
+### Core Communication
+
+#### `sendMessage(sessionId: string, message: string)`
+
+Send a message to the customer in the Zendesk conversation.
+
+```typescript
+await zendesk.sendMessage(sessionId, 'Hello! How can I help you today?');
+```
+
+#### `sendComment(sessionId: string, comment: string)`
+
+Add an internal comment to the ticket (not visible to customer).
+
+```typescript
+await zendesk.sendComment(sessionId, 'Customer issue escalated to tier 2');
+```
+
+#### `sendPublicComment(sessionId: string, comment: string)`
+
+Add a public comment to the ticket (visible to customer).
+
+```typescript
+await zendesk.sendPublicComment(sessionId, 'Issue resolved - closing ticket');
+```
+
+### Conversation Management
+
+#### `getConversation(sessionId: string)`
+
+Retrieve the complete conversation context.
+
+```typescript
+const conversation = await zendesk.getConversation(sessionId);
+console.log(conversation);
+```
+
+#### `getConversationMessages(sessionId: string)`
+
+Get all messages in the conversation.
+
+```typescript
+const messages = await zendesk.getConversationMessages(sessionId);
+```
+
+### Ticket Operations
+
+#### `getTicket(sessionId: string)`
+
+Retrieve ticket information and metadata.
+
+```typescript
+const ticket = await zendesk.getTicket(sessionId);
+console.log(`Ticket status: ${ticket.status}`);
+```
+
+#### `createTicket(params)`
+
+Create a new ticket with specified parameters.
+
+```typescript
+await zendesk.createTicket({
+  sessionId: sessionId,
+  subject: 'Customer inquiry about order #12345',
+  ticketBody: 'Customer is asking about their order status',
+  priority: 'normal',
+  tags: ['order-inquiry', 'customer-support'],
+  customFields: [
+    { id: 123, value: 'urgent' },
+    { id: 456, value: 'premium-customer' },
+  ],
+});
+```
+
+#### `markTicketAsSolved(sessionId: string)`
+
+Mark a ticket as solved.
+
+```typescript
+await zendesk.markTicketAsSolved({ sessionId });
+```
+
+#### `markTicketAsOpen(sessionId: string)`
+
+Reopen a closed ticket.
+
+```typescript
+await zendesk.markTicketAsOpen({ sessionId });
+```
+
+### Tag and Field Management
+
+#### `addTag(sessionId: string, tag: string)`
+
+Add a tag to the ticket.
+
+```typescript
+await zendesk.addTag(sessionId, 'escalated');
+```
+
+#### `setCustomFields(sessionId: string, fields: any[])`
+
+Set custom field values on the ticket.
+
+```typescript
+await zendesk.setCustomFields({
+  sessionId,
+  fields: [
+    { id: 123, value: 'high-priority' },
+    { id: 456, value: 'technical-issue' },
+  ],
+});
+```
+
+#### `search(sessionId: string, query: string)`
+
+Search tickets and conversations.
+
+```typescript
+const results = await zendesk.search({
+  sessionId,
+  query: 'customer:john.doe@example.com status:open',
+});
+```
+
+## Complete Example
+
+Here's a comprehensive example of a Zendesk customer support agent:
+
+### Project Structure
+
+```
+zendesk-agent/
+├── minded.json
+├── schema.ts
+├── zendeskAgent.ts
+├── flows/
+│   └── supportFlow.yaml
+└── tools/
+    ├── escalateIssue.ts
+    ├── lookupOrder.ts
+    └── index.ts
+```
+
+### Configuration
+
+**`minded.json`:**
+
+```json
+{
+  "flows": ["./flows"],
+  "tools": ["./tools"],
+  "agent": "./zendeskAgent.ts",
+  "llm": {
+    "name": "AzureChatOpenAI",
+    "properties": {
+      "model": "gpt-4o",
+      "temperature": 0.7
+    }
+  }
+}
+```
+
+### Memory Schema
+
+**`schema.ts`:**
+
+```typescript
+import { z } from 'zod';
+
+export default z.object({
+  // Customer information
+  customerName: z.string().optional(),
+  customerEmail: z.string().optional(),
+  customerId: z.string().optional(),
+
+  // Issue tracking
+  issueType: z.enum(['billing', 'technical', 'general', 'escalation']).optional(),
+  issueDescription: z.string().optional(),
+  priority: z.enum(['low', 'normal', 'high', 'urgent']).optional(),
+
+  // Ticket information
+  ticketId: z.string().optional(),
+  ticketStatus: z.string().optional(),
+  ticketTags: z.array(z.string()).optional(),
+
+  // Resolution tracking
+  resolution: z.string().optional(),
+  resolved: z.boolean().optional(),
+  escalated: z.boolean().optional(),
+
+  // Conversation context
+  conversationStage: z.enum(['greeting', 'information_gathering', 'issue_resolution', 'closing']).optional(),
+});
+```
+
+### Agent Implementation
+
+**`zendeskAgent.ts`:**
+
+```typescript
+import { Agent } from '@minded/sdk';
+import { zendesk } from '@minded/sdk/interfaces/zendesk';
+import { events } from '@minded/sdk';
+import { HumanMessage } from '@langchain/core/messages';
+import memorySchema from './schema';
+import tools from './tools';
+import mindedConfig from './minded.json';
+
+const agent = new Agent({
+  memorySchema,
+  config: mindedConfig,
+  tools,
+});
+
+// Initialize Zendesk interface
+zendesk.init(agent);
+
+// Handle AI messages
+agent.on(events.AI_MESSAGE, async ({ message, state }) => {
+  await zendesk.sendMessage(state.sessionId!, message);
+});
+
+// Handle trigger events from Zendesk
+agent.on(events.TRIGGER_EVENT, async ({ triggerBody, sessionId }) => {
+  // Qualify the trigger and set initial context
+  const isValidTrigger = triggerBody.content && triggerBody.content.trim().length > 0;
+
+  if (!isValidTrigger) {
+    return { isQualified: false };
+  }
+
+  return {
+    isQualified: true,
+    messages: [new HumanMessage({ content: triggerBody.content })],
+    sessionId,
+    memory: {
+      conversationStage: 'greeting',
+      customerEmail: triggerBody.customerEmail,
+      ticketId: triggerBody.ticketId,
+    },
+  };
+});
+
+// Handle escalation events
+agent.on(events.MEMORY_UPDATE, async ({ memory, state }) => {
+  if (memory.escalated && !memory.resolved) {
+    await zendesk.addTag(state.sessionId!, 'escalated');
+    await zendesk.sendComment(state.sessionId!, `Issue escalated: ${memory.issueDescription}`);
+  }
+});
+
+export default agent;
+```
+
+### Flow Definition
+
+**`flows/supportFlow.yaml`:**
+
+```yaml
+name: Zendesk Support Flow
+nodes:
+  - name: Zendesk-Trigger
+    type: trigger
+    triggerType: app
+    appTriggerId: zendesk-interface
+    appTriggerName: Zendesk Minded Conversation
+    appName: Zendesk
+
+  - name: Support-Agent
+    type: promptNode
+    prompt: |
+      You are a professional customer support agent. 
+
+      Customer Context:
+      - Email: {{memory.customerEmail}}
+      - Issue Type: {{memory.issueType}}
+      - Priority: {{memory.priority}}
+      - Stage: {{memory.conversationStage}}
+
+      Guidelines:
+      1. Be empathetic and professional
+      2. Gather necessary information about the issue
+      3. Provide clear solutions or next steps
+      4. Escalate complex issues when needed
+      5. Always confirm resolution before closing
+
+      If this is the first interaction, greet the customer and ask about their issue.
+
+  - name: Escalate-Issue
+    type: tool
+    toolName: escalateIssue
+
+  - name: Resolve-Issue
+    type: promptNode
+    prompt: |
+      The issue has been resolved. Please:
+      1. Summarize the solution provided
+      2. Ask if the customer needs anything else
+      3. Thank them for their patience
+
+edges:
+  - source: Zendesk-Trigger
+    target: Support-Agent
+    type: stepForward
+
+  - source: Support-Agent
+    target: Escalate-Issue
+    type: promptCondition
+    prompt: Customer issue requires escalation to a specialist
+
+  - source: Support-Agent
+    target: Resolve-Issue
+    type: promptCondition
+    prompt: Customer issue has been resolved successfully
+
+  - source: Escalate-Issue
+    target: Support-Agent
+    type: stepForward
+
+  - source: Resolve-Issue
+    target: Support-Agent
+    type: promptCondition
+    prompt: Customer has additional questions or issues
+```
+
+### Tools Implementation
+
+**`tools/escalateIssue.ts`:**
+
+```typescript
+import { Tool } from '@minded/sdk';
+import { zendesk } from '@minded/sdk/interfaces/zendesk';
+import { z } from 'zod';
+
+const escalateIssue: Tool<any, any> = {
+  name: 'escalateIssue',
+  description: 'Escalate a customer issue to a specialist',
+  inputSchema: z.object({
+    reason: z.string().describe('Reason for escalation'),
+    priority: z.enum(['high', 'urgent']).describe('Escalation priority'),
+  }),
+  func: async ({ reason, priority }, { memory, sessionId }) => {
+    // Add escalation tag
+    await zendesk.addTag(sessionId!, 'escalated');
+
+    // Set priority
+    await zendesk.setCustomFields({
+      sessionId: sessionId!,
+      fields: [{ id: 123, value: priority }], // Assuming field ID 123 is priority
+    });
+
+    // Add internal comment
+    await zendesk.sendComment(sessionId!, `ESCALATED: ${reason} - Priority: ${priority}`);
+
+    return {
+      success: true,
+      message: `Issue escalated with priority: ${priority}`,
+      memory: {
+        ...memory,
+        escalated: true,
+        priority: priority,
+      },
+    };
+  },
+};
+
+export default escalateIssue;
+```
+
+## Best Practices
+
+### 1. Error Handling
+
+Always implement proper error handling for Zendesk operations:
+
+```typescript
+agent.on(events.AI_MESSAGE, async ({ message, state }) => {
+  try {
+    await zendesk.sendMessage(state.sessionId!, message);
+  } catch (err) {
+    logger.error({ message: 'Failed to send message to Zendesk', err });
+    // Implement fallback or retry logic
+  }
+});
+```
+
+### 2. Memory Management
+
+Use memory to maintain context across the conversation:
+
+```typescript
+// Track conversation progress
+memory.conversationStage = 'information_gathering';
+
+// Store important customer data
+memory.customerEmail = triggerBody.customerEmail;
+memory.issueType = 'billing';
+```
+
+### 3. Trigger Qualification
+
+Implement proper trigger qualification to handle only relevant events:
+
+```typescript
+agent.on(events.TRIGGER_EVENT, async ({ triggerBody, sessionId }) => {
+  // Only process triggers with actual content
+  if (!triggerBody.content || triggerBody.content.trim().length === 0) {
+    return { isQualified: false };
+  }
+
+  // Skip automated messages
+  if (triggerBody.isAutomated) {
+    return { isQualified: false };
+  }
+
+  return { isQualified: true };
+});
+```
+
+### 4. Tag Management
+
+Use tags consistently for tracking and automation:
+
+```typescript
+// Add tags based on issue type
+if (memory.issueType === 'billing') {
+  await zendesk.addTag(sessionId, 'billing-issue');
+}
+
+// Track resolution status
+if (memory.resolved) {
+  await zendesk.addTag(sessionId, 'resolved-by-ai');
+}
+```
+
+### 5. Custom Fields
+
+Leverage custom fields for enhanced workflow automation:
+
+```typescript
+// Set custom fields for reporting and automation
+await zendesk.setCustomFields({
+  sessionId,
+  fields: [
+    { id: 123, value: memory.priority },
+    { id: 456, value: memory.issueType },
+    { id: 789, value: 'ai-handled' },
+  ],
+});
+```
+
+## Integration Architecture
+
+The Zendesk integration follows this architecture:
+
+1. **Trigger Events** - Zendesk sends events to your agent
+2. **Agent Processing** - Your agent processes the event and determines response
+3. **Zendesk API Calls** - Agent makes calls back to Zendesk via the interface
+4. **Real-time Updates** - Changes are reflected in Zendesk immediately
+
+This architecture ensures seamless bi-directional communication between your Minded agent and Zendesk, enabling sophisticated customer support automation while maintaining full control over the conversation flow.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Issues**: Ensure your Zendesk credentials are properly configured
+2. **Permission Errors**: Verify your Zendesk API permissions include required scopes
+3. **Rate Limiting**: Implement proper rate limiting and retry logic
+4. **Session Management**: Ensure sessionId is properly maintained across requests
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```typescript
+// Add debugging to your agent
+agent.on(events.AI_MESSAGE, async ({ message, state }) => {
+  console.log('Sending message to Zendesk:', { message, sessionId: state.sessionId });
+  await zendesk.sendMessage(state.sessionId!, message);
+});
+```
+
+For additional support, consult the [Minded platform documentation](../platform) or contact support.