Batch Calls

API endpoints related to managing Batch Calls. Batch calls allow you to schedule automated outbound calls to multiple recipients simultaneously. Each batch call is linked to an Organization and uses the organization's primary Agent to conduct conversations.

Use Cases

Batch calls are ideal for:

Appointment reminders and confirmations
Customer surveys and feedback collection
Event notifications and invitations
Service updates and announcements
Scheduled follow-ups with customers
Mass notifications and alerts

Create Batch Call

Creates a new batch call with scheduled recipients.

POST /v1/organizations/{organizationId}/batch-calls

Path Parameters:

organizationId (string, required): The unique identifier of the organization making the batch calls.

Headers:

Content-Type (string, required): Must be set to application/json.
x-api-key (string, required): Your API key for authentication.

Request Body:

{
  "name": "Appointment Reminders - Week of Nov 11",
  "prompt": "You are calling to remind the customer about their upcoming appointment. Be polite and professional. Confirm their appointment time and ask if they need to reschedule.",
  "firstMessage": "Hi {{name}}, this is Benny calling from Example Corp. I'm calling to remind you about your appointment scheduled for {{appointmentTime}}. Can you confirm if you'll be able to make it?",
  "scheduledFor": 1699920000000,
  "recipients": [
    {
      "name": "John Smith",
      "phone_number": "+15551234567",
      "language": "en",
      "customVariables": {
        "appointmentTime": "November 11th at 2:00 PM",
        "serviceType": "Dental Cleaning"
      }
    },
    {
      "name": "Maria Garcia",
      "phone_number": "+15559876543",
      "language": "es",
      "customVariables": {
        "appointmentTime": "11 de noviembre a las 3:00 PM",
        "serviceType": "Consulta General"
      }
    }
  ]
}

Field Descriptions:

name (string, required): A descriptive name for this batch call campaign (1-255 characters).
prompt (string, optional): Instructions for the AI agent on how to conduct the conversation (max 3000 words). If not provided, the system will use the outbound prompt configured in your dashboard under Outbound Calls settings.
firstMessage (string, optional): The opening message the agent will use. Supports variable interpolation using {{variableName}} syntax (max 10000 characters). If not provided, the system will use the first message configured in your dashboard under Outbound Calls settings.
scheduledFor (number, optional): Unix timestamp in milliseconds when calls should begin. Defaults to 1 minute from now if not specified.
recipients (array, required): List of call recipients (minimum 1, maximum 10000).
- name (string, optional): Recipient's name for personalization.
- phone_number (string, required): Recipient's phone number in E.164 format (e.g., +15551234567).
- language (string, optional): Call language code. Options: en (English), es (Spanish), fr (French), de (German), pl (Polish). Defaults to en.
- customVariables (object, optional): Key-value pairs for message personalization. Can be referenced in firstMessage using {{key}} syntax.
settings (object, optional): Calling rules. Leave it out to call each recipient once, at any time.
- attempts (number, optional): The most calls each recipient gets, counting the first (1-6, default 1). A recipient is tried again after an unanswered, failed or voicemail call.
- retryDelayMinutes (number, optional): Minutes to wait before trying a recipient again (5-1440, default 60). Only used when attempts is more than 1.
- callingHours (object, optional): Calls only go out inside these hours. Calls due outside them wait for the next open window.
  - days (array, required): Any of mon, tue, wed, thu, fri, sat, sun.
  - start (string, required): 24-hour time, for example 09:00.
  - end (string, required): 24-hour time after start, for example 17:00 (24:00 for midnight).
  - timezone (string, optional): IANA time zone such as America/Toronto. Defaults to your organization's time zone.
- maxConcurrentCalls (number, optional): The most calls in progress at once (1-50).

Response:

200 OK: Batch call created successfully.

{
  "message": "Batch call created successfully",
  "body": {
    "id": "batch_123abc",
    "organizationId": "{organizationId}",
    "agentId": "agent_123abc",
    "name": "Appointment Reminders - Week of Nov 11",
    "prompt": "You are calling to remind the customer about their upcoming appointment...",
    "firstMessage": "Hi {{name}}, this is Benny calling from Example Corp...",
    "scheduledFor": 1699920,
    "totalRecipients": 2,
    "completedCalls": 0,
    "status": "scheduled",
    "recipients": [
      {
        "name": "John Smith",
        "phone_number": "+15551234567",
        "language": "en",
        "customVariables": {
          "appointmentTime": "November 11th at 2:00 PM",
          "serviceType": "Dental Cleaning"
        }
      },
      {
        "name": "Maria Garcia",
        "phone_number": "+15559876543",
        "language": "es",
        "customVariables": {
          "appointmentTime": "11 de noviembre a las 3:00 PM",
          "serviceType": "Consulta General"
        }
      }
    ],
    "createdAt": 1699919340000,
    "updatedAt": 1699919340000
  }
}

400 Bad Request: Invalid input data, validation errors, or an invalid/expired API key.

{
  "error": "Validation failed",
  "details": {
    "errors": [
      {
        "path": ["recipients", 0, "phone_number"],
        "message": "Invalid phone number format"
      }
    ]
  }
}

401 Unauthorized: The API key does not belong to the organization in the path.
404 Not Found: Organization not found or no agent configured for the organization.

Try it yourself

POST/v1/organizations/{organizationId}/batch-calls

API Key

Request Body

{
  "name": "Appointment Reminders - Week of Nov 11",
  "prompt": "You are calling to remind the customer about their upcoming appointment. Be polite and professional. Confirm their appointment time and ask if they need to reschedule.",
  "firstMessage": "Hi {{name}}, this is Benny calling from Example Corp. I'm calling to remind you about your appointment scheduled for {{appointmentTime}}. Can you confirm if you'll be able to make it?",
  "scheduledFor": 1699920000000,
  "recipients": [
    {
      "name": "John Smith",
      "phone_number": "+15551234567",
      "language": "en",
      "customVariables": {
        "appointmentTime": "November 11th at 2:00 PM",
        "serviceType": "Dental Cleaning"
      }
    },
    {
      "name": "Maria Garcia",
      "phone_number": "+15559876543",
      "language": "es",
      "customVariables": {
        "appointmentTime": "11 de noviembre a las 3:00 PM",
        "serviceType": "Consulta General"
      }
    }
  ]
}

Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/batch-calls

Best Practices

Using Dashboard Prompts

You can configure a default outbound prompt in your dashboard under Outbound Calls settings. This allows you to:

Omit the prompt field from API requests for simpler integrations
Maintain consistent messaging across all batch calls
Update prompts centrally without modifying API integrations

If you need different prompts for specific campaigns, simply include the prompt field in your request to override the dashboard setting.

Message Personalization

Use custom variables to personalize messages for each recipient:

{
  "firstMessage": "Hi {{name}}, your order #{{orderNumber}} is ready for pickup!",
  "recipients": [
    {
      "name": "Sarah",
      "phone_number": "+15551234567",
      "customVariables": {
        "orderNumber": "12345"
      }
    }
  ]
}

Phone Number Format

Always use E.164 format for phone numbers:

✅ Correct: +15551234567 (country code + number, no spaces or dashes)
❌ Incorrect: (555) 123-4567, 555-1234567, 15551234567

Scheduling

scheduledFor accepts Unix timestamps in milliseconds
If omitted, calls start 1 minute from now
Schedule calls during appropriate business hours for better answer rates
Consider time zones when scheduling international calls

Language Support

Benny supports multiple languages for batch calls:

English (en): Default language
Spanish (es): Full support with native voice
French (fr): Full support with native voice
German (de): Full support with native voice
Polish (pl): Full support with native voice

Ensure your prompt and firstMessage match the recipient's language.

Rate Limits

Maximum 10,000 recipients per batch call
Calls are placed sequentially with appropriate delays
Monitor your organization's monthly call quota

Common Error Codes

Status Code	Error	Solution
400	Invalid or expired API key	Verify the `x-api-key` header value
400	Invalid phone number format	Use E.164 format (+15551234567)
400	Prompt must be less than 3000 words	Shorten your prompt text
400	At least one recipient is required	Include recipients array with at least one recipient
400	Maximum 10000 recipients allowed	Split into multiple batch calls
401	Organization not authorized	Verify API key and organizationId match
404	No agent found for organization	Create an agent for the organization first
404	Organization not found	Verify organizationId is correct

Monitoring Batch Calls

After creating a batch call, you can monitor its progress using the Call Logs API:

GET /v1/organizations/{organizationId}/call-logs

Each call from the batch will appear as an individual call log entry with status, transcript, and summary.

Use Cases​

Create Batch Call​

Try it yourself​

Best Practices​

Using Dashboard Prompts​

Message Personalization​

Phone Number Format​

Scheduling​

Language Support​

Rate Limits​

Common Error Codes​

Monitoring Batch Calls​