OpenAI GPT

Go to platform.openai.com and sign in. Click 'API Keys' in the left sidebar (or navigate to platform.openai.com/api-keys). Click 'Create new secret key.' Give it a name like 'Bubble App' so you can identify it later and set any usage limits if available. Click 'Create secret key.' The API key is shown **exactly once** — copy it immediately and store it in a password manager. If you lose it, you must generate a new one (old keys can be revoked from the dashboard). The key starts with `sk-` followed by a long alphanumeric string. This is the value you will paste into Bubble's API Connector Authorization header. **Understanding rate limits:** OpenAI's rate limits depend on your account tier. New accounts start at Tier 1: - GPT-4o: ~500 requests per minute (RPM), 30,000 tokens per minute (TPM) - GPT-3.5-turbo: higher limits For most Bubble apps in early stages, Tier 1 limits are sufficient. As your app grows and you spend more on the OpenAI API over time, your tier automatically increases. Monitor your usage at platform.openai.com → Usage. **Cost awareness:** GPT-4o charges per token (verify current rates at openai.com/pricing). Setting `max_tokens` in your API call limits the maximum output size and caps per-call cost. Without a `max_tokens` limit, GPT can generate very long responses that cost more than expected.

1// OpenAI API key format:
2// sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3
4// OpenAI API base URL:
5https://api.openai.com/v1
6
7// Chat Completions endpoint:
8POST https://api.openai.com/v1/chat/completions
9
10// Required headers:
11// Authorization: Bearer sk-your-key-here  (mark Private in Bubble)
12// Content-Type: application/json
13
14// Recommended models for Bubble apps:
15// gpt-4o        — best quality, higher cost
16// gpt-4o-mini   — fast, cost-efficient, great for most use cases
17// gpt-3.5-turbo — legacy, cheapest

In your Bubble editor, click Plugins in the left sidebar. Find the API Connector plugin and click 'Add another API.' Name it 'OpenAI.' At the API group level, add a shared header: - Name: `Authorization` - Value: `Bearer sk-your-openai-api-key-here` - Check the **Private** checkbox — this is the critical step that keeps your API key server-side Add another shared header: - Name: `Content-Type` - Value: `application/json` Now add the main call. Click 'Add another call' and name it 'Chat Completion.' Set: - Method: POST - URL: `https://api.openai.com/v1/chat/completions` - Use as: Action For the JSON body, add parameters: - `model` (text, default `gpt-4o-mini`) — the model name - `messages` (JSON array) — the conversation messages array - `max_tokens` (number, default 500) — limits response length and cost - `temperature` (number, default 0.7) — controls creativity (0=deterministic, 1=creative) The messages parameter is the key field. In Bubble's body editor, set it to a JSON array containing at minimum a system message and a user message: ```json [ {"role": "system", "content": "<dynamic_system_prompt>"}, {"role": "user", "content": "<dynamic_user_message>"} ] ``` Mark `system_prompt` and `user_message` as dynamic parameters. **Initialize call:** Click 'Initialize call.' For the system prompt, enter something like 'You are a helpful assistant.' For the user message, enter 'Say hello in one sentence.' Click 'Send.' OpenAI returns a JSON response with a `choices` array — Bubble detects the structure. The AI response text is at `choices[0].message.content`.

1// API Connector: OpenAI → Chat Completion
2// Method: POST
3// URL: https://api.openai.com/v1/chat/completions
4//
5// Shared headers:
6// Authorization: Bearer sk-your-key  // mark Private
7// Content-Type: application/json
8//
9// JSON body:
10{
11  "model": "gpt-4o-mini",
12  "messages": [
13    {"role": "system", "content": "<dynamic_system_prompt>"},
14    {"role": "user", "content": "<dynamic_user_message>"}
15  ],
16  "max_tokens": 500,
17  "temperature": 0.7
18}
19
20// Response structure:
21// {
22//   "id": "chatcmpl-abc123",
23//   "object": "chat.completion",
24//   "model": "gpt-4o-mini-2024-07-18",
25//   "choices": [
26//     {
27//       "index": 0,
28//       "message": {
29//         "role": "assistant",
30//         "content": "Hello! How can I help you today?"
31//       },
32//       "finish_reason": "stop"
33//     }
34//   ],
35//   "usage": {
36//     "prompt_tokens": 12,
37//     "completion_tokens": 9,
38//     "total_tokens": 21
39//   }
40// }
41
42// AI response text path:
43// choices[0].message.content

Now build the core AI interaction. The pattern that sets Bubble AI apps apart is injecting live database data into the prompt before the call fires — creating responses that reference the actual user's situation. On a Bubble page, add: - A Text Input labeled 'Your question' - A Button labeled 'Ask AI' - A Text element to display the AI response (initially hidden) - A loading indicator (an icon or text element visible only during processing) In the workflow editor, create a workflow triggered by 'Button Ask AI is clicked.' **Action 1:** Show the loading indicator. Use 'Show element' or a Conditional on visibility. **Action 2:** Call the OpenAI Chat Completion API Connector action. Fill in the parameters: - `system_prompt`: Build a dynamic string using Bubble's text concatenation. Example: `'You are a helpful assistant for ' + Current User's company name + '. The user is on the ' + Current User's plan + ' plan. Be concise and helpful.'` - `user_message`: `Question Input's value` - `max_tokens`: 500 - `temperature`: 0.7 **Action 3:** Set a Custom State (or Page State) to the API result's `choices[0].message.content` value. **Action 4:** Hide the loading indicator. Make the response Text element visible (or set it to display the Custom State value). The response Text element's content: bind to the Custom State containing the AI response. This updates immediately when the state changes after the API call completes. Note: Bubble's API Connector does NOT support streaming (SSE). The response arrives as a single JSON object after GPT finishes generating — users see a loading state until the complete response arrives, then it appears all at once. For most use cases, this is acceptable. Communicate this with a clear 'Generating your answer...' loading message.

1// Bubble workflow: 'Ask AI' button clicked
2//
3// Action 1: Show element 'Loading Spinner'
4//
5// Action 2: Plugins → OpenAI → Chat Completion
6//   model: gpt-4o-mini
7//   system_prompt: 'You are a helpful assistant for '
8//               + Current User's company + '. '
9//               + 'User is on the ' + Current User's plan + ' plan. '
10//               + 'Answer concisely in 2-3 sentences.'
11//   user_message: Question Input's value
12//   max_tokens: 500
13//   temperature: 0.7
14//
15// Action 3: Set Custom State 'ai_response'
16//   Value: Result of step 2's choices[0].message.content
17//
18// Action 4: Hide element 'Loading Spinner'
19// Action 5: Show element 'Response Text'
20//
21// Response Text content:
22// [This Page's ai_response State]
23
24// System prompt template for personalizing AI responses:
25// 'You are [App Name]'s AI assistant. The current user is [name] 
26//  working at [company]. Their account status is [plan]. 
27//  Their last action was [last_action_date]. 
28//  Keep responses under 150 words.'

For a chatbot that maintains context across multiple messages, you need to store the conversation history and send it with every new GPT call. **Data model:** Create a 'Conversation' data type with fields: - `user` (User) - `created_at` (date) - `title` (text — optional, auto-generated from first message) Create a 'Message' data type with fields: - `conversation` (Conversation) - `role` (text — 'user' or 'assistant') - `content` (text) - `created_at` (date) **Chat UI:** Build a Repeating Group showing all Messages for the current Conversation, sorted by `created_at` ascending. Messages with role='user' display right-aligned, role='assistant' display left-aligned. **Sending a message workflow:** 1. Create a new Message record with role='user', content=Chat Input's value, conversation=current Conversation 2. Clear the Chat Input field 3. Build the messages array: do a search for all Messages in current Conversation sorted by created_at → format as the JSON messages array 4. Add a system message at the start of the array 5. Call OpenAI Chat Completion with the full messages array 6. Create a new Message record with role='assistant', content=API result's choices[0].message.content **Building the messages array in Bubble:** Bubble does not have a native 'join list of objects as JSON array' operator. Use a Repeating Group's source to feed individual message records, and build the JSON string manually: - System message string: `[{"role": "system", "content": "You are a helpful assistant."},` - For each message in history: `{"role": "` + message.role + `", "content": "` + message.content + `"},` - Current user message: `{"role": "user", "content": "` + user_input + `"}]` Alternatively, use the Toolbox plugin's 'List to JSON' or a similar approach to construct the array without manual string concatenation. For long conversations, limit the history: do a search for Messages sorted by created_at descending with a count limit of 10, then reverse — this keeps the last 10 messages as context, preventing the prompt from exceeding GPT's context window.

1// Bubble data types:
2// Conversation: user (User), title (text), created_at (date)
3// Message: conversation (Conversation), role (text), content (text), created_at (date)
4
5// Messages array for GPT (JSON body 'messages' parameter):
6// Build as a concatenated string in Bubble:
7[
8  {"role": "system", "content": "You are a helpful assistant. User: [Current User's name]"},
9  {"role": "user", "content": "First user message from history"},
10  {"role": "assistant", "content": "First AI response from history"},
11  {"role": "user", "content": "Second user message from history"},
12  {"role": "assistant", "content": "Second AI response from history"},
13  {"role": "user", "content": "Current new user message"}
14]
15
16// To avoid context window limits, limit history:
17// Do a search for Messages
18//   where conversation = Current Conversation
19//   sorted by created_at descending
20//   count: 10   <- last 10 messages only
21// Then reverse the list (oldest first) before building the array
22
23// Total token estimate for context management:
24// System prompt: ~50-100 tokens
25// Each message pair: ~50-200 tokens
26// 10 messages ≈ 500-2000 tokens input
27// Keep max_tokens to 500-1000 for responses
28// Total per call: ~1000-3000 tokens

Production AI features need robust error handling — GPT returns specific error codes that your Bubble workflows should handle gracefully. **Common OpenAI error codes:** - 401 — invalid API key (check the sk- key in your Private header) - 429 — rate limit exceeded (too many requests per minute or per day budget limit) - 500 — OpenAI server error (retry once after 5-10 seconds) - 400 — bad request (malformed JSON body, usually from unescaped quotes in dynamic content) **In Bubble, add error handling to the OpenAI API call action:** Click the action in the workflow editor → scroll to 'Only when' and add a fallback. Alternatively, in Bubble's 'Workflow' settings, look for the workflow error handling option. For 429 rate limit errors: add a workflow condition branch — if the API call returns an error, show a user-friendly message ('Our AI assistant is busy — please try again in a moment') and log the error to a Logs data type for monitoring. **Set max_tokens to avoid runaway costs:** Always include `max_tokens` in your API Connector body. Without it, GPT may generate very long responses — a 2000-token response costs 4x a 500-token response. For most use cases, 500-1000 tokens is sufficient. **Monitor usage:** Check platform.openai.com → Usage regularly during early deployment. Set a spending limit in platform.openai.com → Billing → Usage limits to cap monthly API spend automatically. **WU (Workload Unit) monitoring:** Each OpenAI API call from Bubble consumes Bubble Workload Units — one unit per API call action regardless of token count. If your app has many concurrent users each making AI calls, monitor Bubble's WU dashboard under Settings → Billing alongside your OpenAI token usage. RapidDev's team has built AI-powered Bubble apps across multiple industries — for complex AI workflow architecture or scaling guidance, reach out at rapidevelopers.com/contact.

1// OpenAI error response structure:
2// {
3//   "error": {
4//     "message": "Rate limit exceeded for ...",
5//     "type": "requests",
6//     "param": null,
7//     "code": "rate_limit_exceeded"
8//   }
9// }
10
11// Bubble workflow error handling pattern:
12// After OpenAI API call action:
13// → Add 'Only when' condition: This step returned no error
14//   YES path: set Custom State to response content
15//   NO path: show error message to user
16
17// Error message mapping:
18// HTTP 401 → 'Configuration error — contact support'
19// HTTP 429 → 'AI assistant is temporarily busy — try again in a moment'
20// HTTP 500 → 'OpenAI service error — try again in a few seconds'
21// HTTP 400 → 'Invalid request — check for special characters in your input'
22
23// Rate limit mitigation:
24// - Add a 'debounce' — disable the Ask AI button for 2 seconds after click
25// - Set per-user daily limits using a counter field on the User data type
26// - Use gpt-4o-mini instead of gpt-4o for non-critical features (10x cheaper)

Before going live, verify these critical security and quality checkpoints: **1. Privacy verification — the most important step:** Open your deployed Bubble app in a browser (not the editor preview). Open browser DevTools (F12 → Network tab). Trigger an AI call by clicking 'Ask AI.' Filter network requests by 'openai.com.' You should see **zero requests** going directly to api.openai.com from the browser. All OpenAI calls should go through Bubble's server infrastructure. If you see a direct request to api.openai.com in the browser network tab, your API key is exposed — check that the Authorization header has the Private checkbox enabled and that the call is not being made from a client-side JavaScript 'Run JavaScript' action. **2. Confirm the API key is Private in the Connector:** In Bubble's API Connector, open the OpenAI group → Chat Completion call → look at the Authorization shared header. The Private checkbox (🔒 or checkmark) must be enabled. If it is not checked, check it and re-deploy your app. **3. Test with real user data:** Log in as a test user with realistic data (name, plan, recent activity). Submit a question and verify the AI response correctly references the user's dynamic context from the system prompt. Check that the response text appears in the correct UI element. **4. Streaming awareness:** Bubble does not support SSE/streaming responses. The full GPT response arrives as a single JSON object after generation completes — which can take 3-10 seconds for longer responses. Show a clear loading state ('AI is generating your answer...') during this wait to avoid users thinking the app is frozen. **5. Add privacy rules to stored conversations:** If you store Message records in Bubble's database (recommended for conversation history), go to Data tab → Message type → Privacy → add rule: 'This Thing is visible to Current User when Message's conversation's user = Current User.' This prevents one user from reading another user's conversation history.

1// Privacy validation — open deployed app in browser:
2// DevTools → Network tab → filter: openai.com
3// Expected: 0 results (no direct browser-to-OpenAI requests)
4// If you see requests here: Authorization header is NOT marked Private
5//
6// To fix: Plugins → API Connector → OpenAI → Chat Completion
7//   → Authorization header → check 'Private' checkbox
8//   → Deploy changes
9
10// Bubble privacy rules for conversation data:
11// Data tab → Message type → Privacy
12// Add rule:
13//   'This Thing is visible to Current User'
14//   When: Message's conversation's user = Current User
15//
16// Data tab → Conversation type → Privacy
17// Add rule:
18//   'This Thing is visible to Current User'
19//   When: Conversation's user = Current User
20
21// Quick test: loading state workflow
22// Show 'AI is generating your answer...' spinner:
23//   Action 1: Set element visible (loading state)
24//   Action 2: API call (OpenAI) ← blocks until complete
25//   Action 3: Set Custom State to result
26//   Action 4: Hide loading state
27//   Action 5: Show response text