Chat Injection

Dynamically override assistant instructions and pre-populate chat history when embedding. Useful for personalizing behavior per user, per page, or per context — without creating separate assistants.

Prerequisites

• Enable Injection under Additional Permissions in Dashboard → Assistant → Deployment.
• The assistant must use a Custom Persona (not a preset template).

Overview

Chat Injection lets you pass two optional payloads when loading the chat embed:

Field	Purpose
instructionOverrides	Override or extend the assistant’s Custom Instructions and/or Opening Instructions (greeting). These affect LLM behavior.
prefillMessages	Pre-populate the chat with visual-only speech bubbles. These are not sent to the LLM — they only appear in the UI.

Here’s a combined example showing both fields:

{
  "instructionOverrides": {
    "customInstructions": {
      "value": "Always respond in formal English. Focus on enterprise pricing plans.",
     "mode": "append"
    },
    "openingInstructions": {
      "value": "Welcome! I see you're interested in our Enterprise plan.",
      "mode": "replace"
    }
  },
  "prefillMessages": [
    { "type": "message", "role": "assistant", "content": "Hi there! How can I help you today?" },
    {
      "type": "message",
      "role": "user",
      "content": "I'd like to learn about your Enterprise plan."
    }
  ]
}

Instruction Overrides

Each field in instructionOverrides accepts a value (string) and a mode:

Field	Description	Max length
customInstructions	Maps to the Custom Instructions textarea on the Personality tab. Shapes overall LLM behavior.	7,500 characters
openingInstructions	Maps to the Opening Instructions field. Controls the assistant’s greeting message.	2,000 characters

Replace vs. Append

The mode field controls how the injected value interacts with the value already configured in the dashboard:

// "replace" — completely overrides the assistant's configured value
{
  "customInstructions": {
    "value": "You are a billing support agent. Only answer billing questions.",
    "mode": "replace"
  }
}

// "append" — adds to the end of the existing value (separated by a newline)
{
  "customInstructions": {
    "value": "\nAdditional context: the user is on the Pro plan, billed annually.",
    "mode": "append"
  }
}

Mode	Behavior
replace	Completely replaces the dashboard-configured value with the injected value.
append	Appends the injected value to the existing value, separated by a newline.

Both fields are optional — you only need to include the ones you want to override.

Prefill Messages

prefillMessages renders speech bubbles in the chat UI as if a conversation already occurred. These messages are purely visual — they are never included in the conversation history sent to the LLM.

// Current format — text messages only
[
 { "type": "message", "role": "assistant", "content": "Hello! What can I help with?" },
 { "type": "message", "role": "user", "content": "Tell me about your API." }
]

// The "type" field allows future extensions, e.g.:
// { "type": "choices", "options": ["Option A", "Option B"] }
// { "type": "card", "title": "...", "body": "..." }

Property	Type	Description
type	"message"	Message type. Currently only "message" is supported (extensible for future types).
role	"user" | "assistant"	Determines which side the bubble appears on.
content	string	The text displayed in the bubble. Max 2,000 characters per message.

Limits: Maximum 50 prefill messages. Messages exceeding 2,000 characters are truncated.

Delivery: POST Body

The recommended approach — pass injection fields as hidden form fields (JSON strings) alongside your external variables:

<iframe
 name="ragtime-chat"
 width="100%"
 height="700"
 style="border: none; border-radius: 12px;"
 allow="microphone"
></iframe>

<form
 id="ragtime-form"
 method="POST"
 action="https://your-ragtime-instance.com/chat/org-slug/assistant-slug/device-slug"
 target="ragtime-chat"
 style="display:none;"
>
 <!-- Instruction overrides (JSON string) -->
 <input
  type="hidden"
  name="instructionOverrides"
  value='{
    "customInstructions": {
      "value": "Focus on Enterprise pricing.",
      "mode": "append"
    }
  }'
 />

 <!-- Prefill messages (JSON string) -->
 <input
  type="hidden"
  name="prefillMessages"
  value='[
    { "type": "message", "role": "assistant", "content": "Welcome back! Ready to continue?" }
  ]'
 />

 <!-- You can also include external variables alongside injection -->
 <input type="hidden" name="user_name" value="John" />
</form>

<script>
 document.getElementById('ragtime-form').submit();
</script>

Delivery: Query Parameters

For GET requests (static iframe src), base64-encode the JSON values:

// Build the URL with base64-encoded injection params
const instructionOverrides = btoa(
 JSON.stringify({
  customInstructions: {
   value: 'Always respond in formal English.',
   mode: 'append'
  }
 })
);

const prefillMessages = btoa(
 JSON.stringify([{ type: 'message', role: 'assistant', content: 'Welcome!' }])
);

const url = new URL('https://your-ragtime-instance.com/chat/org-slug/assistant-slug/device-slug');
url.searchParams.set('instructionOverrides', instructionOverrides);
url.searchParams.set('prefillMessages', prefillMessages);

// Use as iframe src
document.querySelector('iframe').src = url.toString();

Note: Query parameters are visible in the URL bar and browser history. For sensitive instructions, prefer POST body or use HMAC signing.

Signing Injection Requests

When Security is enabled in Deployment settings, injection parameters must be included in the HMAC signature. Generate URLs server-side:

import crypto from 'crypto';

// Generate a signed URL with injection parameters
function buildSignedInjectionUrl(
  baseUrl: string,
  secret: string,
  overrides: object,
  prefill: object[]
) {
  const params = new URLSearchParams();

  // Add injection (base64-encoded JSON)
  params.set('instructionOverrides', btoa(JSON.stringify(overrides)));
  params.set('prefillMessages', btoa(JSON.stringify(prefill)));

  // Add timestamp and sign
  params.set('timestamp', Date.now().toString());
  params.sort();
  const payload = params.toString();
  const signature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  params.set('signature', signature);

  return `${baseUrl}?${params.toString()}`;
}

See the Embedding section for full HMAC signing details.

Error Handling

Status	Cause
400	Malformed JSON in instructionOverrides or prefillMessages.
403	Injection is not enabled in deployment config (allow_injection.enabled is false).
403	Assistant uses a preset persona template (injection requires Custom Persona).
422	A field value exceeds the character limit.
429	Rate limit exceeded (standard chat rate limits apply).

Injection data rides on the existing chat endpoints, so standard IP-based (60 req/min) and organization-wide (200 req/min) rate limits apply automatically.

Tips

• Use append mode to layer context on top of carefully tuned dashboard instructions, rather than replacing them entirely.
• Prefill messages are great for onboarding flows — show the user a simulated conversation before they type their first message.
• Instruction overrides are applied per embed load. They don’t persist between sessions.
• The same character limits that apply on the Personality tab apply to injected values. Keep custom instructions under 7,500 chars and opening instructions under 2,000.
• Combine injection with External Variables for maximum flexibility — use variables for user data and injection for behavior tuning.