Create a campaign
After this guide, your agent will be calling, WhatsApp-ing, or emailing a whole list of contacts on its own. You'll build the campaign in a step-by-step wizard — we'll walk through every screen.
phone_number column for voice and WhatsApp, an email column for emailPick the right channel first
The channel decides how the campaign runs and which steps the wizard shows. Voice campaigns dial each contact live; WhatsApp and email campaigns send a message and wait for replies.
| Channel | How it runs | Wizard steps |
|---|---|---|
| Voice Call | Real-time dialer. The agent calls each contact within an operating-hours window and can retry failed or unanswered calls. | 5 — Channel, Sender & Agent, Recipients, Schedule, Review |
| Sends an approved WhatsApp template, then optional follow-ups if there is no reply. A reply hands the conversation to the agent. | 6 — Channel, Sender & Agent, Message, Recipients, Send Rules, Review | |
| Sends a subject + body email from your inbox, then optional follow-up emails in the same thread until the contact replies. | 6 — Channel, Sender & Agent, Message, Recipients, Send Rules, Review |
In the dashboard, click Campaigns in the sidebar (Workspace group), then New Campaign at the top-right. The first screen shows three cards: Voice Call, WhatsApp, and Email. Your pick sets the rest of the wizard.
Enter a Campaign Name (required, up to 100 characters) and an optional Description. Pick the sender — a Phone Number and Default Country for voice, a WhatsApp Channel for WhatsApp, or an Email Inbox for email. Then choose the agent that will handle the conversations. Its required and optional prompt variables appear as pills, so you know which CSV columns you'll need.
For WhatsApp, enter the Template Name and Language Code (for example en or ar), then map the template's {{1}}, {{2}} variables to CSV column names. For email, write a Subject and Body using {{column}} placeholders. Both show a live preview as you type.
Upload your CSV — the Template button downloads a starter file with the right columns. A name column is optional, and any extra columns become per-contact data your agent and messages can use:
phone_number,name,appointment_time
0501234567,Sara,"Tuesday 3pm"
0559876543,Omar,"Wednesday 11am"
+971501112233,Layla,"Thursday 5pm"The right-hand pane previews every parsed contact and flags each row as valid, invalid, duplicate, or assumed (a local number converted using your Default Country). You can upload up to 50,000 contacts per campaign.
Voice campaigns get a Schedule step: send immediately or schedule for later, set Operating Hours for the daily call window, and optionally turn on Retry Failed Calls. WhatsApp and email get a Send Rules step: a Send Window, a Campaign Expiry, and an optional follow-up cadence. The details for both are just below.
The final step shows a Campaign Summary table. Check the details, then click Launch Campaign. You land back on the campaigns list with the new campaign running.
Picking the sender
| Channel | Sender field | Notes |
|---|---|---|
| Voice | Phone Number + Default Country | The number must be active and owned by your organization. GCC countries are listed first; Default Country converts local numbers (for example 05xxxxxxx → +966xxxxxxx). |
| WhatsApp Channel | The list shows your connected WhatsApp channels. | |
| Email Inbox | Shown as display name <address>. |
Timing for voice campaigns
- Send immediately or Schedule for later — scheduling adds a Timezone and a Start Date & Time, which must be in the future.
- Operating Hours — a daily call window (start and end). Set both or neither; calls outside the window are held until the next window opens.
- Retry Failed Calls — when on, set Max Attempts (1–5) and Wait Between Retries (5 minutes to 24 hours). Only failed and no-answer calls are retried.
Send rules for WhatsApp and email
- Send Window — quiet hours that hold messages until an allowed time.
- Campaign Expiry — choose No expiry or 3, 7, 14, or 30 days.
- Follow-up cadence — toggle Follow up if no reply to add up to 10 steps. Each step has a wait (minutes, hours, or days; minimum 5 minutes) and its own content: WhatsApp steps take their own approved Template Name, Language Code, and variable mapping; email steps take an optional Subject and a Body sent in the same thread.
Follow-ups stop automatically as soon as a contact replies, opts out, bounces, or fails. A reply is the goal — it hands the conversation to your agent and cancels any pending nudges. For the full guide to cadences, see Contacts & follow-ups.
For developers
The wizard posts to POST /campaigns. The request body is keyed on channel, so voice, WhatsApp, and email each require different fields — voice needs callWindowStart and callWindowEnd together, WhatsApp needs a messagingChannelId plus template config, and email needs an emailInboxId plus subject and body. The endpoint requires the campaigns:write permission, and invalid phone numbers are rejected with the offending rows listed.
curl -X POST https://api.qalyb.ai/campaigns \
-H "Authorization: Bearer sk-live-..." \
-H "Content-Type: application/json" \
-d '{
"channel": "voice",
"name": "Eid Renewal Reminders",
"description": "Call lapsed members about Eid offers.",
"agentId": "agt_abc123",
"phoneNumberId": "pn_966xxxxxxxx",
"defaultCountry": "SA",
"callWindowStart": "09:00",
"callWindowEnd": "18:00",
"retry": { "maxAttempts": 3, "waitMinutes": 60 },
"contacts": [
{ "phone_number": "0501234567", "name": "Sara" },
{ "phone_number": "0559876543", "name": "Omar" }
]
}'