AYW + OpenAI Integration: A Developer's Guide

AYW + OpenAI Integration: A Developer's Guide A step-by-step guide to integrating OpenAI's GPT models into your AYW chatbot platform. Build intelligent, context-aware responses in 40 minutes. Published: June 6, 2026 | 10 min read | Part 3 of AYW Dev.to Series Why OpenAI + AYW? AYW's human-guided AI approach means we don't just "pipe" user messages to OpenAI. Instead, we: Route by intent (which specialist bot should respond?) Inject human-guided system prompts (persona-specific instructions) Manage conversation context (last 10 messages) Handle errors gracefully (fallback responses, rate limits) Track token usage (cost control) Let's build it. Prerequisites (5 Minutes) 1. Get Your OpenAI API Key Go to OpenAI Platform Create an account or sign in Navigate to API Keys → Create new secret key Copy the key (starts with sk-) 2. Install Dependencies cd apps/backend npm install openai 3. Add Environment Variables In apps/backend/.env: OPENAI_API_KEY=sk-your-api-key-here OPENAI_MODEL=gpt-4o-mini # or gpt-4o, gpt-3.5-turbo Part 1: Creating the OpenAI Service Create apps/backend/src/services/openaiService.ts: import OpenAI from 'openai'; import { MessageDTO } from '@ayw/shared'; export class OpenAIService { private client: OpenAI; private model: string; constructor() { this.client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); this.model = process.env.OPENAI_MODEL || 'gpt-4o-mini'; } async generateResponse(options: { botId: string; botName: string; systemPrompt: string; conversationHistory: MessageDTO[]; userMessage: string; temperature?: number; }): Promise<{ response: string; tokensUsed: number; confidence: number; }> { try { // Build messages array from conversation history const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [ { role: 'system', content: options.systemPrompt }, ...this.convertHistoryToMessages(options.conversationHistory), { role: 'user', content: options.userMessage } ]; const completion = await this.client.chat.completions.create({ model: this.model, messages, temperature: options.temperature || 0.7, max_tokens: 500, top_p: 1, frequency_penalty: 0, presence_penalty: 0 }); const response = completion.choices[0]?.message?.content || 'I apologize, I couldn\'t generate a response.'; const tokensUsed = completion.usage?.total_tokens || 0; // Calculate a simple confidence score const confidence = completion.choices[0]?.finish_reason === 'stop' ? 0.9 : 0.5; return { response, tokensUsed, confidence }; } catch (error: any) { console.error('OpenAI API error:', error); // Handle rate limits if (error?.status === 429) { throw new Error('RATE_LIMITED: OpenAI API rate limit exceeded. Please try again later.'); } // Handle authentication errors if (error?.status === 401) { throw new Error('AUTH_ERROR: Invalid OpenAI API key.'); } throw new Error(`OpenAI API error: ${error.message}`); } } private convertHistoryToMessages(history: MessageDTO[]): OpenAI.Chat.ChatCompletionMessageParam[] { return history.map(msg => ({ role: msg.sender === 'user' ? 'user' as const : 'assistant' as const, content: msg.content })); } async generateQuickReplies(options: { botId: string; context: string; count?: number; }): Promise<string[]> { try { const completion = await this.client.chat.completions.create({ model: this.model, messages: [ { role: 'system', content: `You are a helpful assistant that generates concise quick reply options for a chatbot. Generate ${options.count || 3} short, actionable quick reply labels based on the context provided.` }, { role: 'user', content: `Context: ${options.context}\n\nGenerate quick reply options as a JSON array of strings.` } ], temperature: 0.7, max_tokens: 150, response_format: { type: 'json_object' } }); const content = completion.choices[0]?.message?.content || '[]'; const parsed = JSON.parse(content); return Array.isArray(parsed) ? parsed : parsed.replies || []; } catch (error) { console.error('Error generating quick replies:', error); return ['Tell me more', 'Get started', 'Contact us']; // Fallback } } } Part 2: Integrating with AYW Bots Update ChatbotService Edit apps/backend/src/services/chatbotService.ts: import { OpenAIService } from './openaiService'; export class ChatbotService { private openai: OpenAIService; constructor() { this.openai = new OpenAIService(); } async processMessage( conversationId: string, userId: string | null, message: string, context: any ): Promise<ChatbotProcessResponse> { const { botId, conversationHistory, userPreferences } = context; // Get bot config for system prompt const botConfig = await prisma.botConfig.findUnique({ where: { botId } }); if (!botConfig || !botConfig.isActive) { return this.getFallbackResponse(); } // Use OpenAI for supported bots const aiPoweredBots = ['support', 'sales', 'knowledge']; if (aiPoweredBots.includes(botId)) { return this.processWithAI(botId, botConfig, conversationHistory, message); } // Keep Welcome Bot logic rule-based if (botId === 'welcome') { return this.processWelcomeBot(message); } // Default fallback return this.getPlaceholderResponse(botId); } private async processWithAI( botId: string, botConfig: any, conversationHistory: MessageDTO[], userMessage: string ): Promise<ChatbotProcessResponse> { try { // Define system prompts per bot const systemPrompts: Record<string, string> = { support: `You are a customer support bot for As You Wish (AYW). Be helpful, empathetic, and concise. If you can't solve an issue, offer to escalate to a human. Available capabilities: ${botConfig.capabilities.join(', ')}`, sales: `You are a sales bot for As You Wish (AYW) chatbot platform. Help potential customers understand our offerings. Be persuasive but not pushy. Highlight key benefits. Available capabilities: ${botConfig.capabilities.join(', ')}`, knowledge: `You are a knowledge base bot for AYW. Provide accurate information from our documentation. If you don't know something, say so and suggest contacting support. Available capabilities: ${botConfig.capabilities.join(', ')}` }; const result = await this.openai.generateResponse({ botId, botName: botConfig.name, systemPrompt: systemPrompts[botId] || 'You are a helpful assistant.', conversationHistory, userMessage }); // Generate dynamic quick replies const quickReplies = await this.openai.generateQuickReplies({ botId, context: userMessage, count: 3 }); return { botId, response: result.response, suggestedActions: quickReplies.map(label => ({ label, value: label.toLowerCase().replace(/\s+/g, '_') })), escalate: result.confidence < 0.5, sentiment: 'neutral' }; } catch (error: any) { console.error(`AI processing error for ${botId}:`, error); // Fallback to rule-based response if (botId === 'support') { return this.processSupportBot(userMessage); } return { botId, response: 'I apologize, but I\'m having trouble connecting to my AI service. Let me try a different approach.', suggestedActions: [ { label: 'Try Again', value: 'retry' }, { label: 'Talk to Human', value: 'escalate' } ], escalate: true, sentiment: 'negative' }; } } } Part 3: Adding Token Tracking Step 1: Create Token Usage Table Add to apps/backend/prisma/schema.prisma: model TokenUsage { id String @id @default(uuid()) conversationId String @map("conversation_id") botId String @map("bot_id") tokensUsed Int @map("tokens_used") model String createdAt DateTime @default(now()) @map("created_at") @@map("token_usage") } Run migration: cd apps/backend npx prisma migrate dev --name add_token_usage Step 2: Track Token Usage Update openaiService.ts: import { PrismaClient } from '@prisma/client'; const prisma = new PrismaClient(); // Inside generateResponse method, after getting completion: await prisma.tokenUsage.create({ data: { conversationId: options.conversationId, // You'll need to pass this botId: options.botId, tokensUsed: tokensUsed, model: this.model } }); Part 4: Testing Your Integration Test 1: Basic AI Response # Set your token export ACCESS_TOKEN="your_access_token" # Send a message to the Support Bot curl -X POST http://localhost:4000/api/conversations \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "botId": "support", "initialMessage": "How do I reset my password?" }' The response should now come from OpenAI instead of rule-based logic. Test 2: Check Token Usage SELECT bot_id, model, SUM(tokens_used) as total_tokens, COUNT(*) as request_count FROM token_usage GROUP BY bot_id, model ORDER BY total_tokens DESC; Part 5: Cost Optimization Model Selection Model Cost (per 1M tokens) Use Case gpt-4o $5.00 / $15.00 Complex reasoning, high-quality responses gpt-4o-mini $0.15 / $0.60 Most chatbot use cases (recommended) gpt-3.5-turbo $0.50 / $1.50 Simple FAQs (legacy) Token Saving Tips Limit conversation history: Only send last 10 messages Use shorter system prompts: Be concise in instructions Set max_tokens: Cap response length Cache common responses: For FAQs, use rule-based first Example - limiting history: // Only use last 10 messages for context const recentHistory = conversationHistory.slice(-10); Part 6: Error Handling & Fallbacks Rate Limit Handling // In chatbotService.ts private async processWithAI(...) { try { // ... OpenAI call } catch (error: any) { if (error.message.includes('RATE_LIMITED')) { // Wait and retry (exponential backoff) await new Promise(resolve => setTimeout(resolve, 2000)); return this.processWithAI(botId, botConfig, conversationHistory, userMessage); } // Other errors fall back to rule-based return this.getFallbackResponse(); } } Circuit Breaker Pattern For production, implement a circuit breaker to stop calling OpenAI when it's consistently failing: class CircuitBreaker { private failures = 0; private lastFailureTime = 0; private state: 'closed' | 'open' | 'half-open' = 'closed'; async call(fn: () => Promise<any>) { if (this.state === 'open') { if (Date.now() - this.lastFailureTime > 60000) { this.state = 'half-open'; } else { throw new Error('Circuit breaker is open'); } } try { const result = await fn(); this.onSuccess(); return result; } catch (error) { this.onFailure(); throw error; } } private onSuccess() { this.failures = 0; this.state = 'closed'; } private onFailure() { this.failures++; this.lastFailureTime = Date.now(); if (this.failures >= 5) { this.state = 'open'; } } } Troubleshooting "Invalid API key" error? Verify OPENAI_API_KEY in your .env file Check the key at OpenAI Platform Ensure no extra spaces or quotes around the key Responses taking too long? Check your max_tokens setting (lower = faster) Use gpt-4o-mini instead of gpt-4o Implement streaming responses (see OpenAI docs) High costs? Monitor token usage in the token_usage table Set up billing alerts in OpenAI dashboard Use shorter system prompts and limit history Bot not using AI? Check that the botId is in aiPoweredBots array Verify bot is is_active = true in database Check backend logs for OpenAI API errors Next Steps Add streaming responses - Use Server-Sent Events (SSE) for real-time AI responses Implement function calling - Let OpenAI call your APIs directly Add sentiment analysis - Use AI to detect user frustration Build a prompt library - Create and test different system prompts Resources OpenAI API Documentation AYW API Documentation OpenAI Pricing Prompt Engineering Guide Integration Complete! 🎉 Your AYW bots are now powered by OpenAI. Monitor your token usage and costs, and iterate on your system prompts to improve response quality. Questions? Drop them in the comments below! 👇 Tags: #ai #openai #nodejs #tutorial #integration #ayw Series: AYW Developer Tutorials (Part 3 of 6)

Read full story →