TidyCal is simple and easy calendar management and booking tool.

TidyCal

The unique identifier for the call to be analyzed.

This is the overall purpose of the call. Provides context for the analysis to guide how the questions/transcripts are interpreted.

An array of questions to be analyzed for the call.

Each question should be an array with two elements: the question text and the expected answer type (e.g., “string”, “boolean”).

Fairly flexible in terms of the expected answer type, and unanswerable questions will default to `null`.

Examples:

```
[["Who answered the call?", "human or voicemail"], ["Positive feedback about the product: ", "string"]]
```

This is the phone number of the person or company you want to call.

International numbers: must include the country code and may not include additional formatting (like parentheses and dashes). E.g. ‘+447700900077’.

U.S. numbers: may include formatting, but we recommend stripping all additional characters.

Define how the AI should behave. Provide the AI context about the interaction, and give it instructions.

Note: you should continually test and iterate prompts to get the best output from your AI.

The voice of the AI agent to use. Accepts any form of voice ID, including custom voice clones and voice presets. Default voices can be referenced directly by their name instead of an id.
Usage example: voice: "maya"

A key value store that the AI can retrieve information from during the phone call. When you want your AI to “know” a specific fact - like the caller’s name, etc. add that information to the parameters field.

If you want the AI to navigate a phone tree (like calling insurance or banks) or want the AI to leave voicemails, set amd to true.

Otherwise, if you’re calling a human and need quicker response times for the first reply, set amd to false.

Functionally: We use ML to detect if we are talking to a human or machine. If we detect a machine theres an additional 1.3 second delay in between replies.

The webhook should be a http / https callback url. We will send the call_id and transcript to this URL after the call completes. This can be useful if you want to have real time notifications when calls finish.

If you've purchased a fixed outbound phone number, you can select it using this field

A phone number that the agent can transfer to under specific conditions, such as when the caller/callee asks to speak to a human.

For best results, specify the exact conditions to transfer under in the task parameter. Refer to the action as “transfer”, any other phrasing such as “swap” or “switch” can cause unexpected behavior.

Example: +12223334444, +44770090000, +61491550156.

Should the AI phone agent wait for the other person to speak first?

A phrase that your call will start with instead of a generating one on the fly. This works both with and without `wait_for_greeting`. Can be more than one sentence, but must be less than 200 characters.

Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings.

Supported Languages and their codes: English (`eng`), Spanish (`esp`), French (`fre`) and Polish (`pol`).

When the call starts, a timer is set for the max_duration minutes. At the end of that timer, if the call is still active it will be automatically ended.

Example Values: 20, 2

Make dynamic requests to external APIs and use the data in your AI’s responses.

Refer to the Bland AI documentation (docs.bland.ai) to learn how to structure your dynamic data.

When you increase the interruption latency, you force the AI phone agent to listen longer before responding. In practice, increasing the threshold results in less interruptions and more latency.

Try setting the threshold to `500` milliseconds. You’ll encounter higher latency, but you’ll be interrupted much less frequently.

Enables machine detection when the call starts to determine whether the call was answered by a person or a voicemail.

Best Practices (when enabled):

Since the determination is made at the beginning of the call, use wait_for_greeting to try and coax a human response.
If combined with first_sentence, try wording it so the person answering says something back - ex. "Hello?" or "Is this \{\{name\}\}?".

Price: $0.02 per call, however there is no charge for unanswered calls or calls that failed to send.

The time you want the call to start. If you don’t specify a time (or the time is in the past), the call will send immediately.

Set your time in the format YYYY-MM-DD HH:MM:SS -HH:MM (ex. 2021-01-01 12:00:00 -05:00).

The timezone is optional, and defaults to UTC if not specified.

Note: Scheduled calls can be cancelled with the POST /v1/calls/:call_id/stop endpoint.

Select a model to use for your call.

Options: `base`, `turbo` and `enhanced`.

In nearly all cases, `enhanced` is the best choice for now.

Set the temperature of the underlying model (between `0` and `1`). E.g. `0.8`.

This is the pathway ID for the pathway you have created on our dev portal. You can access the ID of your pathways by clicking the ‘Copy ID’ button of your pathway: See `https://app.bland.ai/dashboard?page=home`.
Note: Certain parameters do not apply when using pathways.
Unused Parameters:
task - The pathway substitutes as the agent’s instructions.
model - We use our own fine-tuned models under the hood.
tools - Replaced by ‘Webhook’ Node in Pathways.
transfer_list - Replaced by ‘Transfer Call’ Node in Pathways.
transfer_phone_number - Replaced by ‘Transfer Call’ Node in Pathways.

This is the node ID for the node you want the pathway to start from. You can access the ID of your nodes here: See `https://docs.bland.ai/api-v1/get/convo_pathway`.

Note: This parameter is only used when pathway_id is provided

Select an audio track that you’d like to play in the background during the call. The audio will play continuously when the agent isn’t speaking, and is incorporated into it’s speech as well.

Use this to provide a more natural, seamless, engaging experience for the conversation. We’ve found this creates a significantly smoother call experience by minimizing the stark differences between total silence and the agent’s speech.

Options:

null - Default, will play audible but quiet phone static.

office - Office-style soundscape. Includes faint typing, chatter, 

clicks, and other office sounds.

cafe - Cafe-like soundscape. Includes faint talking, clinking, and other cafe sounds.

restaurant - Similar to cafe, but more subtle.

none - Minimizes background noise

When set to true, the AI will not respond or process interruptions from the user.

These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed.

For example, if the word “Reece” is frequently transcribed as a homonym like “Reese” you could do this:

The pronunciation guide is an array of objects that guides the agent on how to say specific words. This is great for situations with complicated terms or names.

[
  {
    "word": "example",
    "pronunciation": "ex-am-ple",
    "case_sensitive": "false",
    "spaced": "false"
  },
  {
    "word": "API",
    "pronunciation": "A P I",
    "case_sensitive": "true",
    "spaced": "true"
  }
]

Give your agent the ability to transfer calls to a set of phone numbers.

Overrides transfer_phone_number if a transfer_list.default is specified.

Will default to transfer_list.default, or the chosen phone number.

Example usage to route calls to different departments:

Set the timezone for the call. Handled automatically for calls in the US.

This helps significantly with use cases that rely on appointment setting, scheduling, or behaving differently based on the time of day.

Interact with the real world through API calls.

Detailed tutorial here: See `https://docs.bland.ai/tutorials/custom-tools`.

When the AI encounters a voicemail, it will leave this message after the beep and then immediately end the call.

Warning: If amd is set to true or voicemail_action is set to ignore, then this will still work for voicemails, but it will not hang up for IVR systems.

This is processed separately from the AI’s decision making, and overrides it.

Options:
hangup

leave_message

ignore

Examples:

Call is answered by a voicemail (specifically with a beep or tone):

If voicemail_message is set, that message will be left and then the call will end.
Otherwise, the call immediately ends (regardless of amd)
Call is answered by an IVR system or phone tree:

If amd is set to true, the AI will navigate the system and continue as normal.
If voicemail_action is set to ignore, the AI will ignore the IVR and continue as normal.
Otherwise, if voicemail_message is set then it’ll leave that message and end the call.
Finally, if none of those conditions are met, the call will end immediately.
Note: If voicemail_message is set, then the AI will leave the message regardless of the voicemail_action.

If the call goes to voicemail, you can set up the call to retry, after a configurable delay. You can also update the voicemail_action, and voicemail_message in the retry object, for the re-tried call.

Takes in the following parameters:

wait (integer): The delay in seconds before the call is retried.
voicemail_action (enum): The action to take when the call goes to voicemail. Options: hangup, leave_message, ignore.
voicemail_message (string): The message to leave when the call goes to voicemail.

Example:


{
    "retry": {
        "wait": 10,
        "voicemail_action": "leave_message",
        "voicemail_message": "Hello, this is a test message."
    }
}

Specify which events you want to stream to the webhook, during the call.

Options:

queue

call

latency

webhook

tool

dynamic_data

Example Payload:

  {
    "message": "LLM: 411ms",
    "call_id": "0fb3c518-e941-48fd-a32c-67d59c541336",
    "category": "latency",
    "log_level": "performance"
  }

Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls.

Anything that you put here will be returned in your webhook or in the call details under metadata.

Example:


{
  "metadata": {
    "campaign_id": "1234",
    "source": "web"
  }
}

At the end of each call, a summary is generated based on the transcript - you can use this field to add extra instructions and context for how it should be summarized.

For example: "Summarize the call in French instead of English."

Guides the output and provides additional instructions and clarifications for the analysis_schema.

When the call ends, the transcript and call details will be analyzed by the AI.

Define a JSON schema for how you want to get information about the call - information like email addresses, names, appointment times or any other type of custom data.

In the webhook response or whenever you retrieve call data later, you’ll get the data you defined back under analysis.

For example, if you wanted to retrieve this information from the call:


{
  "analysis_schema": {
    "email_address": "email",
    "first_name": "string",
    "last_name": "string",
    "wants_to_book_appointment": "boolean",
    "appointment_time": "YYYY-MM-DD HH:MM:SS"
  }
}

A special key for using a BYOT (Bring Your Own Twilio) account. Only required for sending calls from your own Twilio account.

Bland is a platform for AI phone calls. Our API enables anyone to send or receive phone calls where an AI speaks to a human.

Bland AI

Keep track of your TidyCal bookings and stay connected with clients using Bland AI. Every new booking from TidyCal triggers a phone call via Bland AI, ensuring you're always updated without manually checking your calendar. This workflow provides the advantage of real-time updates, enhancing communication and efficiency.

Bland AI + TidyCal

Send Bland AI phone calls when new bookings are made in TidyCal

Supported triggers and actions

Cancelled Booking

New Contact

Send Phone Call

Get Transcript

New Booking

Analyze Call With AI

End Phone Call

About Bland AI

Related categories

About TidyCal

Related categories