Call recipes for agents

Overview

Three things reliably surprise an agent placing its first real calls: half of them reach an answering machine, the shop’s name comes back from the transcriber as something else entirely, and there is no obvious knob for “hand this to a person if someone is there.” Each of these has an answer. Two are parameters on POST /v1/calls. The third is a pattern you assemble, and this page says so plainly rather than pretending otherwise. New to the call lifecycle itself? Start with the Agent quickstart.

Voicemail

By default, Bland hangs up on voicemail. If you dispatch a call and no one picks up, the agent detects the answering machine and ends the call without saying anything. Nothing is left behind. This is usually not what you want. Configure it with the voicemail object.

Leave a message
Message plus an SMS copy
Push through an IVR

Play a message after the beep, then end the call.

{
  "phone_number": "+15551234567",
  "task": "Ask whether they carry 10mm hex keys.",
  "voicemail": {
    "action": "leave_message",
    "message": "Hi, this is Ada calling about a parts question. I'll try again tomorrow, no need to call back."
  }
}

Leave the voicemail and text a copy, so there is something the recipient can act on without replaying audio. action is leave_message_and_sms. Inside sms, message is required and from is optional; from must be a number you own with SMS permissions. There is no to field, because the destination is resolved by Bland rather than set on the request.

{
  "phone_number": "+15551234567",
  "task": "Ask whether they carry 10mm hex keys.",
  "voicemail": {
    "action": "leave_message_and_sms",
    "message": "Hi, this is Ada calling about a parts question. I'm sending the details by text.",
    "sms": {
      "from": "+15559876543",
      "message": "Ada here, following up on 10mm hex keys. Reply any time."
    }
  }
}

ignore tells the agent to carry on as if nothing was detected. Use it when the “answering machine” is really a phone tree you intend to navigate, and do not pair it with a message.If the callee is a phone menu rather than a person, prefer ivr_mode: it sets this for you and also stops the agent responding on the conversational timing it uses with a human.

{
  "phone_number": "+15551234567",
  "task": "Navigate the phone menu to reach the parts department, then ask whether they carry 10mm hex keys.",
  "voicemail": {
    "action": "ignore"
  }
}

The action you pass is not always the action that runs

Bland derives the effective action from the whole request, not from action alone. This trips people up, so it is worth knowing before you debug a call that “ignored” your setting.

What you send	What actually runs
`ivr_mode: true`, with any `action`	`ignore`. A phone menu has no voicemail, so IVR mode suppresses voicemail handling entirely. The legacy `amd` alias sets the same switch.
A `message`, plus an `sms` config	`leave_message_and_sms`
A `message`, with no `sms` config	`leave_message`
No `message` and no `ivr_mode`	The `action` you passed

The practical rule: supplying a message implies leaving one, and ivr_mode overrides the action entirely. So {"action": "hangup", "message": "..."} leaves the message rather than hanging up, and {"action": "ignore", "message": "..."} abandons your IVR pushthrough. If you want hangup or ignore, send no message alongside it.

Retrying instead of leaving a message

If you would rather try again later than leave anything, the retry object redials after a delay and can use a different voicemail action on the second attempt.

{
  "retry": {
    "wait": 3600,
    "voicemail_action": "leave_message",
    "voicemail_message": "Second attempt, sorry to miss you. I'll stop calling after this one."
  }
}

Full parameter details are in the Send Call reference.

Proper nouns

Transcription is where a business name becomes something that is not a business name. “Carmine and Co” comes back as “Carmiano Bank”, your agent repeats it back on the call, and the conversation quietly derails. keywords is the lever. It boosts the words you list inside the transcription engine, so they win against phonetically similar alternatives.

{
  "phone_number": "+15551234567",
  "task": "Ask Carmine and Co whether the Vitale order shipped.",
  "keywords": ["Carmine and Co", "Vitale"]
}

Add a colon and a number for a stronger boost. The default factor is 2, and higher values push harder:

{
  "keywords": ["Carmine and Co:3", "Vitale"]
}

Practical guidance:

Seed it from what you already know. If your agent is calling a business, it knows the business name. If it is asking for a person, it knows the person’s name. Pass them before the first call rather than after the first bad transcript.
Boost the ones that actually matter. Company names, product SKUs, street names, surnames, anything invented or non-English.
Limits: at most 20 keywords per call, each under 100 characters, each formatted as word or word:boost.
Do not boost common words. Raising a word’s odds everywhere makes the transcript worse, not better.

See keywords for the full parameter.

Escalating to a human during open hours

This one is a pattern, not a platform knob. There is no business_hours field, and no setting that means “transfer if someone is at the desk.” What Bland gives you is the transfer itself: deciding when it is allowed is yours to assemble. Written down, it is short. You need two pieces: a way to transfer, and a decision about whether transferring is allowed right now.

The transfer

Agent type	How to transfer
Prompt-based (`task`)	`transfer_phone_number`, or `transfer_list` for several destinations with a `default`.
Pathway (`pathway_id`)	A Transfer Call node. `transfer_phone_number` is ignored for pathways.

If you need the human to be briefed before the caller is handed over, that is a warm transfer. When you use transfer_phone_number, the task has to say when to use it, and it has to use the word “transfer”. Alternate phrasing like “switch” or “hand off” can cause the agent to skip the action entirely.

The decision

Decide before you dial (recommended)

Your code knows the wall clock and the on-call roster. Bland does not. So resolve “is anyone there?” at dispatch time and send a different call depending on the answer:

const open = isWithinBusinessHours(new Date(), "America/New_York");

await fetch("https://api.bland.ai/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLAND_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+15551234567",
    timezone: "America/New_York",
    task: open
      ? "Answer the caller's question. If they ask for a person, or you cannot resolve it, transfer the call."
      : "Answer the caller's question. The office is closed, so do not offer to transfer. Take a message and confirm a callback tomorrow morning.",
    ...(open && { transfer_phone_number: "+15559876543" }),
  }),
});

Omitting transfer_phone_number when you are closed is the important half. A prompt that says “do not transfer” is a request the agent can misread. A call with no transfer destination cannot transfer at all.

Or decide during the call

Sometimes the boundary falls mid-call, or the answer depends on something the agent learns while talking (which department, whether the caller is an existing customer). Then the decision has to happen live.Pass the facts in request_data and set timezone so the agent’s sense of “now” matches yours:

{
  "phone_number": "+15551234567",
  "timezone": "America/New_York",
  "transfer_phone_number": "+15559876543",
  "request_data": {
    "desk_staffed": true,
    "desk_closes_at": "5:00 PM Eastern"
  },
  "task": "You are the front desk for Rossi Hardware. If the caller asks for a person and {{desk_staffed}} is true, transfer the call. Otherwise offer to take a message."
}

Give the agent a decision it can read, not arithmetic it has to perform. desk_staffed: true is reliable. “Work out whether 4:55 PM Pacific is inside 9 to 5 Eastern” is not. In pathways, {{now_utc}} is available at every node, but the same advice holds: branch on a precomputed flag wherever you can.

Confirm it happened

The transfer shows up in the post-call payload and in GET /v1/calls/{call_id}: transferred_to holds the number and transferred_at the timestamp. If both are null on a call where the caller clearly asked for a person, the prompt wording is the first thing to check.

Next steps

Agent quickstart

Place a call, learn how it ended, read the transcript.

Send Call API reference

Every parameter these recipes use, in full.

Conversational Pathways

Structured flows when a prompt stops being enough.

Post call webhooks

The payload that tells you how each call went.

Docs for agents: llms.txt

Welcome

Core Bland Features

MCP & AI Agents

Basic Tutorials

Advanced Features

Platform Information

SDKs & Tools

Bland Enterprise

Call recipes for agents

Overview

Voicemail

The action you pass is not always the action that runs

Retrying instead of leaving a message

Proper nouns

Escalating to a human during open hours

The transfer

The decision

Confirm it happened

Next steps

Agent quickstart

Send Call API reference

Conversational Pathways

Post call webhooks

​Overview

​Voicemail

​The action you pass is not always the action that runs

​Retrying instead of leaving a message

​Proper nouns

​Escalating to a human during open hours

​The transfer

​The decision

​Confirm it happened

​Next steps

Agent quickstart

Send Call API reference

Conversational Pathways

Post call webhooks

Overview

Voicemail

The action you pass is not always the action that runs

Retrying instead of leaving a message

Proper nouns

Escalating to a human during open hours

The transfer

The decision

Confirm it happened

Next steps