Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheCodeStudioxyz/sniko-conversational-ai/llms.txt

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

Batch calls let you launch a bulk outbound calling campaign. You choose an agent, a phone number, and a list of recipients — Sniko submits the campaign to ElevenLabs, which dials each contact and runs the AI conversation automatically.

​
How batch calls work

  1. You create a campaign with a name, an agent, a phone number, and a recipient list.
  2. Sniko schedules the campaign in ElevenLabs with a scheduled_time_unix timestamp.
  3. ElevenLabs dials each recipient and conducts the conversation using the assigned agent.
  4. Progress is tracked via total_calls_scheduled, total_calls_dispatched, total_calls_completed, and total_calls_failed counters.
You must accept the ElevenLabs batch calling Terms & Conditions before submitting your first campaign. Submitting without acceptance returns a batch_calling_agreement_required error.

​
Creating a campaign

1

Navigate to Batch Calls

Open Batch Calls from the sidebar and click New Campaign.
2

Fill in campaign details

FieldRequiredDescription
NameYesA descriptive name for the campaign
AgentYesThe AI agent that will conduct each call
Phone numberYesA number assigned to that agent
Scheduled timeNoDate and time to start (defaults to immediate)
TimezoneNoYour local timezone for scheduling
3

Upload your contact list

Import recipients by uploading a CSV file or entering numbers manually.
4

Submit

Click Start Campaign. Sniko submits the campaign to ElevenLabs and redirects you to the campaigns list.

​
CSV format

Each row represents one recipient. The minimum required column is phone_number. 
phone_number,first_name,account_id
+12025550101,Alice,ACC001
+12025550102,Bob,ACC002
+12025550103,Carol,ACC003
Additional columns beyond phone_number are passed as conversation_initiation_client_data to the agent, making them available as dynamic variables during the conversation.
Phone numbers must be in E.164 format (e.g. +12025550100). Rows with an invalid format will fail during dialing.

​
Validated recipient fields

FieldTypeRequired
phone_numberstring (E.164)Yes
conversation_initiation_client_dataobjectNo
Sniko automatically generates a UUID for each recipient before submitting to ElevenLabs.

​
Scheduling

If you provide a scheduled time, Sniko converts it from your local timezone to UTC before sending to ElevenLabs. If no time is provided, the campaign starts immediately (scheduled_time_unix defaults to the current Unix timestamp). 
// Example payload submitted to ElevenLabs
{
  "call_name": "[customer-uuid] Q2 Outreach",
  "agent_id": "agent_abc123",
  "agent_phone_number_id": "pn_xyz789",
  "scheduled_time_unix": 1748736000,
  "recipients": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+12025550101"
    }
  ]
}

​
Monitoring progress

Open a campaign from the list to see its detail page. The detail page shows:
MetricDescription
Statuspending, in_progress, completed, or failed
ScheduledDate and time the campaign is set to run
Total scheduledNumber of contacts in the campaign
DispatchedCalls that have been initiated so far
CompletedCalls that finished successfully
FailedCalls that could not connect
ProgressPercentage of dispatched vs. scheduled
The list view shows a progress bar and a human-readable time since creation (e.g. “3 hours ago”).

​
Filtering campaigns

From the campaigns list, you can filter by:
  • Name — partial text search across campaign name and agent name
  • Status — show only campaigns in a specific state
Results are paginated at 12 campaigns per page.

​
Cancelling a campaign

A campaign that has not yet completed can be cancelled from its detail page. 
POST /batch-calls/{id}/cancel
Cancellation stops further outbound dialing. Calls already in progress are not interrupted.

​
Retrying a failed campaign

If a campaign ends with failures, you can retry it: 
POST /batch-calls/{id}/retry
Retrying re-submits the campaign to ElevenLabs to attempt the failed contacts again.

​
Quota limits

Submitting a new campaign requires the quota.check:batch_calls middleware to pass. If your plan’s batch call quota is exhausted, the POST /batch-calls request returns a 403 error.
Quota is checked at submission time, not at scheduling time. If your quota runs out between creating a scheduled campaign and its scheduled start time, the campaign may still be accepted but may not run.

​
Campaign isolation

Each campaign name is prefixed with your customer UUID internally (e.g. [uuid] Campaign Name). The UI strips this prefix on display. When loading the detail page, Sniko verifies the prefix matches your account before rendering — unauthorized access returns a “not found” error.

Build docs developers (and LLMs) love

Get started for freeTalk to us