Prompting guide

A prompt that reads well on a page can still sound wrong on the phone. The caller hears one sentence at a time, cannot scroll back, and may talk over the agent. This guide covers how Dialgem uses your prompt, then practical advice for writing one.

It has two kinds of statement. How Dialgem works is what the product does. Advice is general voice-prompt practice: it usually helps, but language models are not guaranteed to follow any instruction, so always test (Testing agents).

How Dialgem uses your prompt

• System prompt. The system_prompt is the instruction the model receives on every turn, together with the conversation so far. See Prompt agents.
• First message. first_message is spoken as written when the call connects. If it is empty, the agent waits for the caller. begin_message_delay_ms adds a pause first.
• Variables. {{name}} placeholders are filled in when the string is used, from three places. Highest priority first: values sent with the call, then default_dynamic_variables on the agent, then built-in variables. They work in the system prompt and the first message.
• A missing variable stays visible. If no value exists, the placeholder is left as typed ({{customer_name}}) and would be spoken that way. An empty string, by contrast, is replaced with nothing.
• Built-in variables. {{current_time}}, {{current_hour}} and {{current_calendar}} accept a time zone suffix, such as {{current_time_America/Chicago}}, and give the time as a 12-hour clock like 2:07 PM CST. Others include {{call_id}}, {{call_type}} (phone_call or web_call), {{direction}}, {{user_number}}, {{agent_number}} and {{session_duration}} (seconds so far).
• Functions. The model chooses a function from its name and description. Every agent already has end_call. A transfer_call function connects the caller to a number; see Voicemail and call transfer.
• Knowledge base. On each turn the agent retrieves the passages closest to what the caller just said. See Knowledge base.
• Interruptions. If the caller talks over the agent, it stops and listens. interruption_sensitivity and responsiveness tune this, and reminder_trigger_ms and end_call_after_silence_ms control silence. Voice and pace come from Voices and voice_speed.

Advice for writing the prompt

1. Open with role and goal. Two sentences: who the agent is, who it talks to, what a good call achieves.
2. Write for the ear. Ask for short sentences and one or two sentences per turn. Avoid bullet lists, markdown and emoji in what is spoken.
3. One question at a time. Say so explicitly, and list the details to collect in order.
4. Spell out how to say things. Tell the agent to read phone numbers digit by digit, say times as "two thirty in the afternoon", and spell emails out letter by letter when confirming. Use pronunciation_dictionary for names and brand terms.
5. Confirm important details. Repeat names, dates and numbers back before acting on them.
6. Plan for silence and confusion. Say what to do if the caller is quiet, speaks unclearly, or asks the same thing twice.
7. Add guardrails. State what the agent must not do (give medical advice, quote prices not in the knowledge base) and what to do instead.
8. Name each function and say when to use it. The model reads the function description too, so keep the prompt and the description consistent. Say when to end the call and when to transfer.
9. Keep facts out of the prompt. Put prices and hours in the knowledge base so the prompt stays short.

Example: dental front desk

Set first_message to Thanks for calling {{business_name}}. How can I help? and put business_name in default_dynamic_variables. Add a transfer_call function named transfer_to_front_desk.

You are the phone receptionist for {{business_name}}, a dental clinic. You talk to patients who call in, and your goal is to book, move or cancel appointments and answer simple questions.

Today is {{current_calendar_America/Chicago}} and the time is {{current_time_America/Chicago}}. The caller's number is {{user_number}}.

How to speak
- Use short, friendly sentences. One or two sentences per turn.
- Ask one question at a time.
- Say times in words, for example "two thirty in the afternoon". Read phone numbers one digit at a time.

Booking
1. Ask what the visit is for.
2. Ask for the caller's full name. Repeat it back.
3. Ask which day suits them, then offer at most two times.
4. Before you finish, repeat the day, time and name and ask if that is right.

Answering questions
- Use the knowledge base for prices, hours and insurance. If it does not contain the answer, say you are not sure and offer a transfer.
- Never give medical advice. For pain or an emergency, say so kindly and use transfer_to_front_desk.

If the caller is silent, ask once whether they are still there. If you cannot understand them after two tries, offer a transfer.
When the caller says they are done, say goodbye and use end_call.

Example: outbound survey

Start the call with customer_name set in the call's dynamic variables, and give the agent a first message such as Hi, is this {{customer_name}}?.

You are calling {{customer_name}} on behalf of {{business_name}} to ask three short questions about a recent visit. You are polite, brief and never pushy.

Start by confirming you are speaking to {{customer_name}}. If it is someone else, apologise, say you will try again later, and use end_call.
Say the survey takes under two minutes and ask if now is a good time. If not, thank them and use end_call.

Ask these one at a time, and wait for each answer:
1. On a scale of one to five, how was your visit?
2. What did we do well?
3. What could we do better?

Acknowledge each answer in a few words before moving on. Do not argue with feedback. If the caller asks to be removed from calls, say it will be noted, apologise, and use end_call.
When all three are answered, thank them and use end_call.

Before and after

Weak:

You are a helpful assistant. Help customers with appointments. Be professional and make sure to collect their name, phone number, email, date and reason, and give them accurate pricing information. Always be polite.

Better:

You are the receptionist for {{business_name}}. Your goal is to book appointments. Keep replies to one or two short sentences and ask one question at a time.
Collect, in order: full name, reason for visit, preferred day. Repeat the name and day back to confirm.
Do not quote prices; use the knowledge base, and if it has no answer, offer a transfer.

The rewrite names a goal, an order, a speaking style and what to do when the answer is missing.

Troubleshooting

After each change, run your test cases again and publish a new version once they pass.