Calls Overview

This section of the API reference covers the APIs for managing voice calls. The APIs provide methods to create and manage calls, retrieve recordings, handle user inactivity, and access conversation history through stages and messages. The system supports features like call recording, language hints, and maximum duration limits to help manage the conversation flow.

Calls → At the core are Calls, which represent complete conversations between users and AI agents, configured with parameters like system prompts, voice settings, and language preferences.

Stages → Calls can be broken down into Stages, which represent distinct segments of conversation where different parameters (like prompts or tools) may be used.

Messages → Within each stage, Messages capture the back-and-forth dialogue between users and agents.

​

More Info

This section contains additional details for some properties.

​

inactivityMessages

Inactivity messages allow your agent to gracefully handle periods of user silence and end the call after a period of user inactivity. This feature helps maintain engagement and ensures calls don’t remain open indefinitely when users have disconnected or finished their interaction.

• Messages are Ordered → Messages are delivered by the agent in the order provided.
• Message Durations are Cumulative → The first message is delivered when the user has been inactive for its duration. Each subsequent message m is delivered its duration after message m-1 (provided the user remains inactive).
• User Interactions Reset → Any activity from the user will reset the message sequence.
• Different Behaviors → Messages can have different end behaviors and can terminate the call.

• Keep messages concise and natural-sounding.
• Start with friendly check-in messages before moving to call termination.
• Provide clear context in messages if the call will be terminated.

When creating a new call, inactivityMessages are an array of message objects.

​

Example: Adding Inactivity Messages

Let’s look at how we could add inactivity messages to a call.

{
  "systemPrompt": "You are a helpful assistant.",
  "inactivityMessages": [
    {
      "duration": "30s",
      "message": "Are you still there?"
    },
    {
      "duration": "15s",
      "message": "If there's nothing else, may I end the call?"
    },
    {
      "duration": "10s",
      "message": "Thank you for calling. Have a great day. Goodbye.",
      "endBehavior": "END_BEHAVIOR_HANG_UP_SOFT"
    }
  ]
}

​

initialMessages

When creating a new call or a new call stage, you can provide messages to the agent via initialMessages. By default, new calls don’t have initial messages and call stages inherit the prior stage’s messages. New calls will inherit messages if priorCallId is set.

These messages can serve the purpose of giving the agent call history or to give examples for few-shotting (e.g. if you want the agent to learn how to respond in a specific way to user input).

​

Message Format

initialMessages must be an array of message objects where each message contains a role and text.

See “Response” under List Call Messages for more details.

{
  "systemPrompt": "You are a helpful assistant.",
  "initialMessages": [
    {
      "role": "MESSAGE_ROLE_USER",
      "text": "My name is Steve"
    },
    {
      "role": "MESSAGE_ROLE_AGENT",
      "text": "Great to meet you, Steve! How can I help?"
    },
  ]
}