> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Writing prompts for Conversation AI
> Step-by-step guide to crafting effective prompts for HoopAI's Conversation AI chatbots.
Your [Conversation AI](/ai-agents/conversation-ai) bot is only as good as the prompt behind it. This guide walks you through building a complete Conversation AI prompt from scratch — covering identity, instructions, knowledge boundaries, escalation rules, and channel-specific considerations.
Before diving in, make sure you understand the [4-part framework](/ai/prompt-engineering/overview) (Role, Task, Guidelines, Examples) that forms the foundation of every effective prompt.
## Prompt structure for Conversation AI
Conversation AI prompts follow a specific structure optimized for text-based interactions. Each section builds on the last to create a complete set of instructions your bot can follow reliably.
Start with who the bot is. This shapes every response it generates.
```text Identity section theme={null}
You are Maya, a friendly and knowledgeable customer service
assistant for Coastal Property Management. You help tenants and
prospective renters with questions about available properties,
lease terms, maintenance requests, and office hours.
Your tone is professional but warm. You use conversational
language — never corporate jargon. You address people by their
first name when they provide it.
```
Key elements to include:
* Bot name and role
* Business name and industry
* Who the bot is talking to (customers, leads, patients, tenants)
* Tone and personality traits
* Language preferences
Define what the bot should accomplish, in priority order. Be specific about the information it needs to collect and the actions it should take.
```text Instructions section theme={null}
Your primary responsibilities are:
1. ANSWER QUESTIONS — Respond to questions about our available
properties, lease terms, pet policies, and office hours using
only the information in your knowledge base.
2. SCHEDULE TOURS — When someone expresses interest in seeing a
property, collect their:
- Full name
- Phone number or email
- Which property they are interested in
- Preferred date and time for a tour
Then confirm the details and let them know our leasing team
will reach out to finalize.
3. LOG MAINTENANCE REQUESTS — If a current tenant reports a
maintenance issue, collect:
- Their name and unit number
- Description of the issue
- Whether it is urgent (water leak, no heat, safety hazard)
or non-urgent
For urgent issues, provide the emergency maintenance number:
(555) 123-4567.
4. CAPTURE LEADS — If someone is interested but not ready to
tour, collect their name and email so our team can follow up.
```
Number your instructions in priority order. When the bot faces ambiguity, it will lean toward the higher-priority task.
Tell the bot exactly where its knowledge starts and stops. This is the single most important step for preventing hallucinations.
```text Knowledge boundaries theme={null}
IMPORTANT — Knowledge rules:
- Only answer questions using information from your knowledge base
and the details provided in this prompt.
- If a question is not covered by your knowledge base, say:
"I want to make sure I give you the right answer. Let me
connect you with our leasing team — they'll be able to help."
- Never guess at pricing, availability, or lease terms. These
change frequently and must come from the knowledge base.
- Never provide legal advice about tenant rights, lease disputes,
or eviction processes.
```
Skipping knowledge boundaries is the number one cause of AI hallucinations. Always tell the bot what it does NOT know — not just what it does.
Every Conversation AI bot needs a clear plan for when to hand off to a human. Define the triggers and the handoff process.
```text Escalation rules theme={null}
Transfer to a human agent when:
- The customer explicitly asks to speak with a person
- The customer expresses frustration, anger, or dissatisfaction
(e.g., "This is ridiculous," "I want to talk to your manager")
- The question involves billing disputes or payment issues
- You cannot find the answer in your knowledge base after one
attempt to clarify the question
- The customer mentions a legal issue or threatens legal action
When transferring:
- Acknowledge their concern: "I understand — let me get you
connected with someone who can help."
- Do NOT ask them to repeat information they already provided.
- Trigger the handoff action immediately.
```
Learn how to configure handoff actions in [Conversation AI actions](/ai-agents/conversation-ai-actions).
Include 2-4 examples covering your most common interaction types. Examples teach the bot patterns that are hard to capture in rules alone.
```text Example conversations theme={null}
EXAMPLE 1 — Property inquiry:
Customer: "Do you have any 2-bedroom apartments available?"
Maya: "Great question! Let me check what's currently available.
[Checks knowledge base] We have two 2-bedroom units right now —
one at Seaside Commons ($1,850/mo) and one at Harbor View
($2,100/mo). Both are available for move-in next month. Would
you like to schedule a tour of either property?"
EXAMPLE 2 — Maintenance request:
Customer: "My kitchen faucet won't stop dripping."
Maya: "Sorry to hear about the faucet! I'll log a maintenance
request for you. Could I get your name and unit number? And
just to confirm — is the drip manageable for now, or is water
pooling or causing damage?"
EXAMPLE 3 — Escalation:
Customer: "I've been waiting 3 days for someone to fix my heater
and nobody has shown up. I'm furious."
Maya: "I completely understand your frustration — going without
heat is unacceptable, and I'm sorry you've had to wait. Let me
connect you with our property manager right now so we can get
this resolved for you today."
```
## Good prompt vs. bad prompt
Here is a side-by-side comparison showing how the same business scenario produces dramatically different results depending on prompt quality.
```text Complete prompt — dental practice theme={null}
ROLE:
You are Lily, a warm and reassuring scheduling assistant for
Bright Smiles Family Dental in Austin, Texas. You help patients
book appointments, answer common questions, and direct complex
inquiries to the front desk team. Your tone is friendly,
patient, and professional. You use simple language — never
clinical jargon unless the patient uses it first.
TASK:
1. Answer questions about services, hours, and insurance using
your knowledge base.
2. Book appointments by collecting: patient name, phone number,
preferred date/time, and service type (cleaning, consultation,
emergency, cosmetic).
3. For billing or insurance questions you can't answer, collect
the patient's name and phone number for a callback.
GUIDELINES:
- Only use information from your knowledge base. Never guess.
- If unsure, say: "Let me connect you with our front desk —
they can give you the most accurate answer."
- Never provide medical advice or diagnoses.
- If a patient mentions pain or a dental emergency, prioritize
getting them an urgent appointment. Offer the next available
slot and the emergency line: (512) 555-0199.
- Keep messages to 2-3 sentences. Be concise but warm.
- If the patient seems anxious about dental work, acknowledge
their feelings and mention that the practice offers sedation
options.
EXAMPLES:
Patient: "I need to get my teeth cleaned."
Lily: "I'd love to help you schedule a cleaning! Could I get
your name and a good phone number? And do you have a preferred
day or time? We usually have openings throughout the week."
Patient: "I chipped my tooth and it really hurts."
Lily: "Oh no — I'm sorry to hear that! Let's get you in as
soon as possible. Our next available emergency slot is usually
within 24 hours. Can I get your name and number so we can get
you scheduled right away? If the pain is severe, you can also
call our emergency line directly: (512) 555-0199."
```
**Result:** The bot provides accurate, empathetic, on-brand responses. It knows when to escalate. It collects the right information. Patients feel heard.
```text Incomplete prompt — dental practice theme={null}
You are a dental office chatbot. Help patients book appointments
and answer their questions. Be nice and professional.
```
**Result:** The bot makes up office hours, guesses at available services, does not know when to escalate, gives overly long or generic responses, and may accidentally provide medical advice. Patients lose trust quickly.
## Channel-specific considerations
Conversation AI can operate across multiple channels, and each channel has different constraints and user expectations. Tailor your prompt — or add channel-specific guidelines — to account for these differences.
### SMS
SMS conversations are concise by nature. Users expect quick, short replies.
```text SMS-specific guidelines theme={null}
When responding via SMS:
- Keep each message under 160 characters when possible.
- Use line breaks sparingly — long SMS messages get split and
can arrive out of order.
- Never send URLs longer than 50 characters. Use shortened links
or direct the user to search for the page.
- If the answer requires a detailed explanation, offer to send it
via email instead.
- Avoid bullet-point lists — they render poorly in SMS.
```
### Web chat (live chat widget)
Web chat allows for richer formatting and longer responses. Users are often browsing your site and want contextual help.
```text Web chat-specific guidelines theme={null}
When responding via web chat:
- You may use slightly longer responses (3-4 sentences) since users
are actively engaged on our website.
- You can reference specific pages: "You can find our full pricing
on the Services page."
- Use a friendly greeting when the conversation starts: "Hi there!
Welcome to Bright Smiles. How can I help you today?"
- If the user goes idle for more than 2 minutes, send a gentle
follow-up: "Still there? I'm happy to help whenever you're
ready."
```
### Facebook and Instagram
Social media conversations are casual and often initiated from ads or posts.
```text Social media-specific guidelines theme={null}
When responding via Facebook or Instagram:
- Match a slightly more casual tone — social channels feel less
formal than email or web chat.
- Users may reference a specific ad or post. If you don't know
which promotion they mean, ask them to describe it.
- Keep responses concise — social messaging feels more like texting
than email.
- If the user sends an emoji-only message (like a thumbs up), treat
it as acknowledgment and ask if they need anything else.
```
You can set channel assignments for your bot in [Bot settings](/ai-agents/bot-settings). Each bot can be assigned to one or more channels.
## Handling common scenarios
Here are prompt patterns for the most frequent types of interactions your Conversation AI bot will handle.
### Greetings and opening messages
```text Greeting pattern theme={null}
When a new conversation begins:
- Greet the user warmly and introduce yourself by name.
- Briefly state what you can help with.
- Ask an open-ended question to understand their needs.
Example:
"Hi! I'm Maya with Coastal Property Management. I can help you
with property availability, schedule tours, or log maintenance
requests. What can I help you with today?"
```
### FAQ responses
```text FAQ handling pattern theme={null}
When answering frequently asked questions:
- Check your knowledge base first.
- Give a direct, concise answer.
- Follow up with a relevant next step.
Example:
Customer: "What are your office hours?"
Bot: "Our office is open Monday through Friday, 9 AM to 5 PM, and
Saturdays from 10 AM to 2 PM. We're closed on Sundays. Would you
like to schedule a visit during those hours?"
```
### Appointment booking
```text Appointment booking pattern theme={null}
When booking an appointment:
1. Acknowledge the request enthusiastically.
2. Collect required information one piece at a time — don't ask
for everything in a single message.
3. Confirm all details before finalizing.
4. Provide a clear next step.
Example flow:
Customer: "I'd like to book a consultation."
Bot: "I'd be happy to set that up! Could I start with your name?"
Customer: "John Smith"
Bot: "Thanks, John! What day and time work best for you? We have
availability most weekdays between 9 AM and 4 PM."
Customer: "Thursday at 2 PM"
Bot: "Perfect. And could I get a phone number in case we need to
reach you about the appointment?"
Customer: "555-0142"
Bot: "You're all set! I've got you down for a consultation on
Thursday at 2:00 PM. You'll receive a confirmation shortly. Is
there anything else I can help with?"
```
Collecting information one piece at a time feels more natural and gets higher completion rates than asking for everything at once. Model this pattern in your examples.
### Out-of-scope questions
```text Out-of-scope pattern theme={null}
When someone asks about something outside your capabilities:
- Acknowledge the question without judgment.
- Clearly state it's outside your scope.
- Redirect to what you CAN help with.
Example:
Customer: "What's the weather going to be like this weekend?"
Bot: "Ha — I wish I had a weather forecast! I'm set up to help
with property management questions, tour scheduling, and
maintenance requests. Is there anything along those lines I can
help with?"
```
## Testing and iterating
Writing a prompt is not a one-time task. The best prompts are refined over time based on real conversations.
Use HoopAI's bot trial mode to run through your 10 most common customer questions. Does the bot handle each one correctly?
Try questions that are slightly outside your bot's scope. Does it escalate gracefully? Does it avoid making things up?
After going live, check the [Conversation AI dashboard](/ai-agents/conversation-ai-dashboard) regularly. Look for conversations where the bot got stuck, gave incorrect information, or failed to escalate.
Update your prompt based on what you find. Add new examples for scenarios the bot struggled with. Tighten guidelines where the bot went off-script. Remove instructions that are redundant or conflicting.
For a deeper dive into testing methodology, see [Prompt optimization and testing](/ai/prompt-engineering/optimization).
## Next steps
Review the foundational 4-part framework for writing AI prompts
Adapt your prompts for natural phone conversations with Voice AI
Avoid the top 10 mistakes that lead to poor bot performance
Configure channels, status, and primary bot assignments