Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.uponai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This guide covers how to make outbound calls with your UponAI agents. Before proceeding, ensure you have:
  • Created and configured an agent
  • Purchased or imported phone numbers
  • Set up your API credentials

​
Step 1: Bind Agents to Phone Numbers

Before making calls, assign agents to your phone numbers. This configuration determines how your number handles both inbound and outbound calls.
SettingPurposeUse Case
Inbound AgentHandles incoming calls to this numberCustomer support, callbacks
Outbound AgentUsed when making calls from this numberSales outreach, notifications
Flexible agent assignment:
  • Different agents — Use specialized agents for inbound vs outbound
  • Outbound only — Leave inbound agent unset to prevent callbacks
  • Inbound only — Configure only an inbound agent for receive-only numbers
After binding an inbound agent, your number is immediately ready to receive calls. See A/B Testing to split outbound traffic across multiple agents.

​
Step 2: Make Outbound Calls

​
International Calling Restrictions

  • UponAI-purchased numbers — Supports calling to 15 countries
  • Imported numbers — International calling depends on your telephony provider’s settings

​
Call Parameters

When making outbound calls, these parameters are supported:
ParameterTypeDescription
from_numberstring (E.164)Your UponAI-managed or imported number
to_numberstring (E.164)Destination number
override_agent_idstringOverride the agent used for this call (optional)
override_agent_versionintegerVersion of the override agent; defaults to latest if omitted
agent_overrideobjectPer-call partial overrides for agent behavior (optional)
metadataobjectFree-form metadata stored with the call
retell_llm_dynamic_variablesobjectKey-value strings injected into prompts/tools (optional)
custom_sip_headersobjectOutbound SIP headers forwarded to your provider (optional)
ignore_e164_validationbooleanBypass E.164 validation for custom telephony only
const registerCallResponse = await uponai.call.createPhoneCall({
  from_number: '+14157774444', // replace with your number
  to_number: '+12137774445',   // replace with the number to call
  // Optional: per-call agent selection and overrides
  override_agent_id: 'agent_abc123',
  override_agent_version: 0, // or omit to use latest
  agent_override: {
    agent: {
      voice_speed: 1.1,
      enable_backchannel: true,
    },
  },
  retell_llm_dynamic_variables: {
    name: 'John Doe',
    blood_group: 'B+',
  },
  custom_sip_headers: {
    'X-Custom-Header': 'Custom Value',
  },
});

console.log(registerCallResponse);

​
Step 3: Configure CPS (Calls Per Second)

CPS controls how many outbound calls you can initiate per second. This prevents system overload and ensures call quality.
ProviderDefault CPSMaximum CPSNotes
Twilio15Changes take up to 10 minutes
Telnyx116Instant updates
Custom Telephony1Concurrency ÷ 20Based on your concurrency limit
Exceeding CPS limits results in rejected calls. Start low and scale gradually based on actual needs.
Best practice — implement retry logic with exponential backoff: 
const maxRetries = 3;
let retryDelay = 1000; // Start with 1 second

for (let i = 0; i < maxRetries; i++) {
  try {
    await makeCall();
    break;
  } catch (error) {
    if (error.code === 'rate_limited') {
      await sleep(retryDelay);
      retryDelay *= 2; // Exponential backoff
    }
  }
}

​
Step 4: Monitor Call Details

API Polling

Use the Get Call API to retrieve the full transcript, call recording, latency metrics, function call logs, and call duration/status.

Real-time Webhooks

Set up webhooks to receive instant notifications for: call started, call ended, call analyzed, and call failed events. Ideal for production systems.