Terminal
Terminal/Skill
Creates, schedules, duplicates, cancels, and troubleshoots persistent outbound calling campaigns across many contacts in Vapi.
By Vapi
Works with
npx skills add vapiai/skills --skill create-campaignUse Campaigns for a persistent outbound run whose contacts, lifecycle, and results must be managed together. Creating a campaign launches it immediately or schedules it; there is no draft or separate start action.
The current public API uses /v2/campaign. The unversioned /campaign endpoints are legacy and have different behavior. Use /v2/campaign for new integrations, and touch /campaign only when the user explicitly asks to maintain an existing legacy integration.
/v2/campaign to legacy /campaign behavior.VAPI_API_KEY; never print it, request it in chat, or put it in client-side code, examples, logs, or committed files.POST /v2/campaign does not prove failure. Search for the intended campaign before retrying so the audience is not called twice.Choose the API and execution mode.
POST /call and the create-call skill for one call or a simple one-off batch that does not need campaign-level lifecycle, reporting, cancellation, duplication, or webhooks.VAPI_API_KEY is available.Resolve the caller and outbound number.
assistantId or squadId. Do not use deprecated Workflows for a new campaign.phoneNumberId. Vapi Free Numbers cannot launch campaigns. The current /v2/campaign API does not support legacy dialPlan routing across multiple outbound numbers.Prepare and validate contacts.
+14155550100. In an API request, an intentional non-E.164 SIP-trunk destination requires numberE164CheckEnabled: false on that customer; the number must still contain only an optional leading + followed by letters or digits. The Dashboard CSV importer cannot set this customer-level flag, so use E.164 numbers for that path.number; lowercase name is optional. Every other populated column becomes a case-sensitive dynamic variable. Prefer lowercase snake_case headers.assistantOverrides.variableValues for an assistant campaign or squadOverrides.variableValues for a squad campaign. Do not copy arbitrary source columns into unrelated configuration fields.Set timing and concurrency.
schedulePlan for a new campaign that should dispatch as soon as capacity is available.schedulePlan.earliestAt and optional latestAt as ISO 8601 date-times. When the user gives local time, establish the IANA time zone, convert it, and show both local and ISO values.latestAt is later than earliestAt. The Dashboard schedules up to seven days ahead in 15-minute increments; recheck current API constraints when implementing outside the Dashboard.maxConcurrency at or below the organization's available concurrency. It limits this campaign but does not reserve slots or increase the organization's shared call capacity.latestAt is reached.Configure campaign webhooks only when needed.
server before using predialPlan or serverMessages. Prefer a saved credential over inline secrets and use an intentional timeout and backoff plan.predialPlan: { "enabled": true } for a blocking check immediately before each contact is dialed. The endpoint must return JSON containing Boolean eligible; false skips the contact, while timeout, non-2xx, or invalid JSON produces contact.predial-failed.serverMessages for selected asynchronous campaign and contact lifecycle events. Make the receiver idempotent and do not depend on event ordering.end-of-call-report on the relevant assistant when the integration also needs transcripts, recordings, or analysis, and join records by callId.Build and review the request.
name, exactly one of assistantId or squadId, phoneNumberId, a non-empty customers array, and maxConcurrency.name and duplicateFromCampaignId, then send only intentional replacements. Omit customers to inherit the source audience; a supplied customers array replaces it.assistantOverrides or squadOverrides, schedulePlan, server, serverMessages, and predialPlan only when intentional.Create once and verify.
POST /v2/campaign. Treat the returned campaign ID as the durable identifier.GET /v2/campaign/{id}?includeCounters=true before claiming creation succeeded. Report the actual status and schedule; creation does not prove any contact was reached.GET /v2/campaign with narrow supported filters and creation-time context to look for the campaign. Do not automatically repeat the POST.Inspect and diagnose from contact evidence.
includeCounters=true. Use contactCounters for pending, dispatched, completed, failed, skipped, and pre-dial-failed totals; use callMetrics.dialed and callMetrics.connected for pickup analysis.GET /v2/campaign/{id}/contacts and paginate when needed. Contact status is the source of truth for each audience member.callId exists, retrieve that call and inspect its ended reason, transcript, recording, analysis, and logs before proposing a root cause.Duplicate to rerun or replace compatible configuration.
duplicateFromCampaignId and a new name. Omitted configuration and contacts are copied from the source; provided fields override the source, and provided customers replace copied contacts. The source must also use the current /v2/campaign API.assistantId and squadId inherits the old mutually exclusive caller and produces an invalid request. Create a fresh campaign when changing caller type or when an inherited option must be removed rather than replaced.schedulePlan.earliestAt immediately before the request with enough future margin to remain valid during transport and server validation, such as current UTC time plus 60 seconds. State the resulting delay.Cancel or archive deliberately.
PATCH /v2/campaign/{id} with only { "status": "cancelled" }. Pending work stops; calls already in progress may finish. Cancellation is final for that campaign.endedReason. Do not describe cancellation as reversing calls already placed.DELETE /v2/campaign/{id} archives rather than permanently erases campaign records. If active, the campaign is cancelled first. Archive only when the user separately asks to remove it from active campaign views.400: report the rejected field and compare it with the current /v2/campaign schema. Correct one unambiguous request-shape issue before at most one safe retry.401 or 403: stop for authentication, scope, entitlement, frozen subscription, or permission failure.404: report the exact missing campaign, assistant, squad, or phone number ID.409: re-fetch the campaign; an immutable or terminal lifecycle conflict requires a duplicate or no further action, not a repeated patch.429 or 5xx: report the service condition. Never retry campaign creation until duplicate creation has been ruled out.Return only what the request needs: