Trigger Calls

Programmatically trigger individual outbound calls using API campaigns. This is the simplest way to integrate voice calls into your application.

Overview

API campaigns provide a clean way to trigger individual calls without managing contact lists. Create an API campaign once as a configuration template, then trigger calls anytime with a single API call.

Two-Step Setup

Step 1: Create an API campaign with type: "api" (one-time setup).
Step 2: Call POST /campaigns/:id/trigger whenever you need to make a call.

Step 1: Create an API Campaign

Create a campaign with type: "api". This acts as a configuration template with your default agent and phone number.

curl -X POST https://vocalis.io/api/v1/campaigns \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmations",
    "type": "api",
    "agentId": "your-agent-uuid",
    "provisionedPhoneNumberId": "your-phone-uuid"
  }'

Step 2: Trigger Calls

Simple Trigger

The simplest call just needs a phone number:

curl -X POST https://vocalis.io/api/v1/campaigns/CAMPAIGN_ID/trigger \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155551234" }'

With Context Injection

Pass variables and additional context to customize the call:

const response = await fetch(
  `https://vocalis.io/api/v1/campaigns/${campaignId}/trigger`,
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      phoneNumber: '+14155551234',
      calleeName: 'John Doe',
      promptAppend: 'Order #123 shipped today via UPS.',
      variables: {
        customerName: 'John',
        orderNumber: '123',
        trackingNumber: '1Z999AA10123456784',
      },
      metadata: { orderId: '123', source: 'shopify' },
      callbackUrl: 'https://myapp.com/webhooks/call-complete',
    }),
  }
);

const { data } = await response.json();
console.log('Call queued:', data.callId);

With Full Prompt Override

For complete control, provide a systemPrompt to bypass the agent's prompt entirely:

curl -X POST https://vocalis.io/api/v1/campaigns/CAMPAIGN_ID/trigger \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155551234",
    "systemPrompt": "You are a friendly appointment reminder. Call the patient and remind them of their appointment tomorrow at 2pm with Dr. Smith.",
    "callbackUrl": "https://myapp.com/webhooks/call-complete"
  }'

You cannot provide both systemPrompt and agentId in the same request. Use systemPrompt for full control, or agentId to use a different agent template.

Daily Run Batching

All calls triggered on the same UTC day are automatically grouped into a single campaign run. This provides clean analytics: 50 calls throughout the day = 1 run with 50 calls. A new run is created automatically at the start of each new UTC day.

Polling Call Status

Use the existing GET /api/v1/calls/:callId endpoint to poll for call status updates:

curl https://vocalis.io/api/v1/calls/CALL_ID \
  -H "x-api-key: YOUR_API_KEY"

Call status progresses: queued → initiated → ringing → in_progress → completed.

Webhook Callbacks

Instead of polling, provide a callbackUrl to receive a webhook when the call completes. See the Webhooks Guide for payload format and signature verification details.

API Reference

Trigger Call

POST/api/v1/campaigns/{campaignId}/trigger

Trigger a single outbound call via an API campaign. The call is queued and processed asynchronously.

Request Body

Parameter	Type	Required	Description
`phoneNumber`	string	Yes	Phone number in E.164 format
`calleeName`	string	No	Name of the person being called
`agentId`	string	No	Override the campaign's default agent
`systemPrompt`	string	No	Full prompt override (bypasses agent)
`promptAppend`	string	No	Additional context appended to the agent prompt
`variables`	object	No	Key-value pairs injected into the agent prompt template
`fromPhoneNumberId`	string	No	Override the outbound caller ID phone number
`metadata`	object	No	Custom key-value pairs stored with the call and returned in webhooks
`callbackUrl`	string	No	HTTPS URL to receive a webhook when the call completes

Response (202 Accepted)

{
  "data": {
    "callId": "8f14e45f-ceea-467f-a830-cf60f5e5a214",
    "campaignId": "357b188c-c618-4f95-84b1-cbe26b8ce3e0",
    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phoneNumber": "+14155551234",
    "status": "queued",
    "createdAt": "2024-01-15T14:30:00Z"
  }
}