Campaigns

A campaign binds an agent to a list of contacts and a goal. On the voice channel, activating a campaign queues a call for every pending contact and dials them within the campaign’s schedule, retrying people who did not answer. On whatsapp and email, activation either sends an opening message to every contact or only arms the agent to answer people who write in, depending on how the campaign is configured. Campaigns start as drafts, so nothing reaches a customer until you activate one.

The Quickstart creates a first campaign end to end. This page is the full reference: the object, the state machine, how contacts are worked through, and the limits that apply.

How it works

1. Create the campaign. It is stored in draft and nothing is sent.
2. Add contacts to it, one at a time, in bulk or from a CSV file. See Contacts.
3. Activate it. Jelliu runs the channel’s preflight checks, flips the status to active and queues the outreach.
4. Workers process each contact. Before every dial or send they re-read the campaign, so a pause or a channel change takes effect on jobs that are already queued.
5. Completion is automatic. A campaign moves to completed when it has no pending contacts and no call still in progress. The check runs whenever a contact settles, and a background sweep asks again every 15 minutes.

Status transitions

Only two endpoints change the status: activate and pause. There is no endpoint that completes or archives a campaign.

Two other rules depend on the status:

• PATCH /api/campaigns/{campaignId} is refused for completed and archived campaigns.
• DELETE /api/campaigns/{campaignId} is refused for active campaigns. Pause first.

Channels

The agent must serve the campaign’s channel (its channels list). A mismatch is refused on create, on a channel change and again on activation, with 400 VALIDATION_FAILED.

How voice contacts are worked through

For every queued contact, the dialer checks, in order:

1. The campaign is still active and still a voice campaign. Otherwise the job ends and the contact stays pending.
2. The schedule. Outside the window, the dial is postponed to the start of the next enabled window, up to 14 times. A contact that exceeds that, or a schedule with no upcoming window at all, is marked failed.
3. The contact is still pending, and its current phone number is used, not the one it had when the campaign was activated.
4. The number is dialable. A value that is not E.164, or that the carrier lookup reports as unroutable, marks the contact invalid without spending an attempt.
5. Consent. If the workspace requires consent before calling, a contact without voice-call consent is marked invalid.
6. Claim. The contact is atomically moved to called, so two workers can never dial the same person.
7. The call. A contact blocked by compliance rules or the do-not-call list is marked dnc. See Calls for everything that happens once the call is placed.

Concurrency. A call is placed only if the campaign has fewer live calls than its max_concurrent_calls and the workspace has a free slot under its plan’s concurrent-call limit. When either limit is reached, the dial is not failed: the contact returns to pending and the dial is rescheduled with a backoff of 30 seconds growing to 10 minutes.

Retries. When a call ends without reaching the person (no answer, busy line, or a call that never connected), Jelliu schedules another dial after retry_interval_minutes. max_retry_attempts is the total number of dials per contact in a run, including the first one: with the default of 3, a contact is called at most three times. 0 disables retries. Retries go back through the same checks, so they also respect the schedule. Contacts that are converted, dnc or invalid are never retried.

Campaign context reaches the agent

name, productContext and targetAudience are not just labels. On every campaign call they are passed to the agent as the campaign_name, product_context and target_audience variables, together with the contact’s name and your company name. Text conversations (WhatsApp, email, web chat) with a contact that belongs to a campaign receive the same three variables. Write productContext as the brief you would give a human agent: what is being offered and what the conversation is for.

Paused by Jelliu

Some failures belong to the workspace, not to a contact. When a dial fails because the workspace has no phone number of its own (PHONE_NUMBER_REQUIRED) or because the campaign’s agent is paused (AGENT_PAUSED), Jelliu pauses the campaign, writes the reason to blocked_reason and leaves every remaining contact pending. Fix the cause and activate the campaign again to resume.

The campaign object

Campaign responses are the stored row, with snake_case field names, even though request bodies use camelCase.

Fields added by the list endpoint

GET /api/campaigns returns a lighter row. It includes id, tenant_id, agent_id, name, status, category, channel, max_concurrent_calls, max_retry_attempts, schedule, blocked_reason, created_at, updated_at and deleted_at, plus these aggregates. It does not include product_context, target_audience, retry_interval_minutes or the WhatsApp and email fields; fetch the campaign by ID for those.

Schedule

Hours are whole hours: startHour: 9, endHour: 18 allows calls to start from 09:00 up to 17:59. A day that does not appear in days is treated as disabled.

Template variables

WhatsApp templates contain numbered placeholders such as {{1}}. You can fill them two ways, and combine them:

• whatsappTemplateVariables: the same value for every contact. Either an array of up to 20 strings, or an object keyed by placeholder number (keys up to 8 characters). Values are up to 500 characters.
• whatsappTemplateVariableMap: a value resolved per contact, keyed by placeholder number (keys up to 3 characters). Each entry is either a token string, or { "token": "...", "fallback": "..." } with a fallback of up to 500 characters. Placeholders the map does not mention keep their campaign-wide value.

Email campaigns write the same tokens inline in emailSubject and emailBody, wrapped in double braces, for example Hola {{contact.first_name}}.

Unknown tokens are rejected when you save the campaign. A mapped placeholder number that the template does not have is rejected too.

Common tasks

Launch a voice campaign

curl -sS -X POST "https://api.jelliu.co/api/campaigns" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "name": "Renovaciones septiembre",
    "productContext": "Llamadas a clientes cuyo plan de internet hogar vence este mes para ofrecer la renovación con 20% de descuento.",
    "targetAudience": "Clientes residenciales con contrato por vencer",
    "channel": "voice",
    "category": "retention",
    "maxConcurrentCalls": 5,
    "maxRetryAttempts": 3,
    "retryIntervalMinutes": 120,
    "schedule": {
      "timezone": "America/Bogota",
      "days": [
        { "day": "monday",    "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "tuesday",   "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "wednesday", "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "thursday",  "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "friday",    "startHour": 9, "endHour": 17, "enabled": true },
        { "day": "saturday",  "startHour": 9, "endHour": 13, "enabled": false }
      ]
    }
  }'

{
  "data": {
    "id": "0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90",
    "tenant_id": "3e9a1c47-2b8d-4f60-a5c1-7d2e9b4f8a13",
    "agent_id": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "blocked_reason": null,
    "name": "Renovaciones septiembre",
    "product_context": "Llamadas a clientes cuyo plan de internet hogar vence este mes para ofrecer la renovación con 20% de descuento.",
    "target_audience": "Clientes residenciales con contrato por vencer",
    "status": "draft",
    "schedule": {
      "timezone": "America/Bogota",
      "days": [
        { "day": "monday", "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "tuesday", "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "wednesday", "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "thursday", "startHour": 9, "endHour": 18, "enabled": true },
        { "day": "friday", "startHour": 9, "endHour": 17, "enabled": true },
        { "day": "saturday", "startHour": 9, "endHour": 13, "enabled": false }
      ]
    },
    "max_concurrent_calls": 3,
    "max_retry_attempts": 3,
    "retry_interval_minutes": 120,
    "channel": "voice",
    "category": "retention",
    "retry_policy": {},
    "voicemail_action": "retry",
    "voicemail_message": null,
    "whatsapp_template_id": null,
    "whatsapp_template_variables": null,
    "whatsapp_template_variable_map": null,
    "email_subject": null,
    "email_body": null,
    "created_at": "2026-09-15T14:02:11.482Z",
    "updated_at": "2026-09-15T14:02:11.482Z",
    "deleted_at": null
  }
}

curl -sS -X POST "https://api.jelliu.co/api/campaigns/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90/contacts" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+573001234567", "name": "Ana Gómez" }'

curl -sS -X PATCH "https://api.jelliu.co/api/campaigns/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90/activate" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

Reach out on WhatsApp with per-contact values

This campaign sends an approved template whose body is Hola {{1}}, tu pedido de {{2}} está listo. Placeholder 1 is the contact’s first name, falling back to cliente. Placeholder 2 is the same for everybody.

curl -sS -X POST "https://api.jelliu.co/api/campaigns" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
    "name": "Pedidos listos para recoger",
    "productContext": "Avisar a clientes que su pedido está listo y resolver dudas sobre horarios de recogida.",
    "targetAudience": "Clientes con pedidos listos en tienda",
    "channel": "whatsapp",
    "category": "notifications",
    "whatsappTemplateId": "9b2e4d61-8f3a-4c7b-b1e5-2a6d9c0f4e87",
    "whatsappTemplateVariables": { "2": "Tienda Chapinero" },
    "whatsappTemplateVariableMap": {
      "1": { "token": "contact.first_name", "fallback": "cliente" }
    },
    "schedule": {
      "timezone": "America/Bogota",
      "days": [{ "day": "monday", "startHour": 8, "endHour": 20, "enabled": true }]
    }
  }'

On activation, contacts that have a valid E.164 phoneNumber but no WhatsApp number get their phone number copied into the WhatsApp field, so imported lists are reachable. The schedule is required by the schema but does not restrict WhatsApp sends.

Turn an email campaign into outreach

PATCH accepts every create field except agentId, all optional. This request adds a subject and body to an existing email campaign, so its next activation mails every contact.

curl -sS -X PATCH "https://api.jelliu.co/api/campaigns/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emailSubject": "{{contact.first_name}}, tu renovación está lista",
    "emailBody": "Hola {{contact.first_name}}, responde a este correo y te ayudamos a renovar tu plan hoy mismo."
  }'

The response is 200 with the updated campaign. A PATCH with no recognized fields returns the campaign unchanged.

Pause and resume

Pausing does not delete queued work. Each queued dial or send checks the status when its turn comes and does nothing while the campaign is paused. Calls already in progress finish normally.

# Pause
curl -sS -X PATCH "https://api.jelliu.co/api/campaigns/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90/pause" \
  -H "Authorization: Bearer $JELLIU_API_KEY"
# Resume: activate again
curl -sS -X PATCH "https://api.jelliu.co/api/campaigns/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90/activate" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

A resumed voice campaign queues only the contacts still pending. People already called in the earlier run are not called again, except through the normal retry rules.

List campaigns and track progress

GET /api/campaigns uses page-number pagination: page (default 1) and limit (1 to 100, default 20), newest first.

curl -sS "https://api.jelliu.co/api/campaigns?page=1&limit=20" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": [
    {
      "id": "0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90",
      "tenant_id": "3e9a1c47-2b8d-4f60-a5c1-7d2e9b4f8a13",
      "agent_id": "7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4",
      "name": "Renovaciones septiembre",
      "status": "active",
      "category": "retention",
      "channel": "voice",
      "max_concurrent_calls": 3,
      "max_retry_attempts": 3,
      "schedule": {
        "timezone": "America/Bogota",
        "days": [{ "day": "monday", "startHour": 9, "endHour": 18, "enabled": true }]
      },
      "created_at": "2026-09-15T14:02:11.482Z",
      "updated_at": "2026-09-15T14:05:40.019Z",
      "deleted_at": null,
      "blocked_reason": null,
      "agent_name": "Laura - Renovaciones",
      "total_contacts": 250,
      "pending_contacts": 164,
      "called_contacts": 86,
      "converted_contacts": 12,
      "conversion_rate": 14
    }
  ],
  "meta": { "page": 1, "limit": 20 }
}

The response has no total count: stop when a page returns fewer than limit items. GET /api/campaigns/{campaignId} returns one campaign with every field from the campaign object, in data.

Read campaign results

GET /api/analytics/campaigns/{campaignId} summarizes the campaign’s calls. The optional direction query parameter accepts inbound, outbound or all (default).

curl -sS "https://api.jelliu.co/api/analytics/campaigns/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": {
    "campaignId": "0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90",
    "channel": "voice",
    "category": "retention",
    "totalInteractions": 131,
    "completedInteractions": 86,
    "successes": 12,
    "successRate": 13.95,
    "successRateLabel": "retentionRate",
    "averageDurationSeconds": 143,
    "avgSentiment": 0.21,
    "outcomeBreakdown": {
      "customer_retained": 11,
      "customer_reactivated": 1,
      "callback_scheduled": 9,
      "rejected": 31,
      "no_answer": 34
    },
    "excludedMetrics": []
  }
}

Results are cached for up to two minutes. For WhatsApp and email campaigns this endpoint reports zeros, because they produce conversations rather than calls; read those through Conversations. For call-by-call detail, list GET /api/calls?campaignId=....

Delete a campaign

Deletion is a soft delete: the campaign stops appearing in the API and its ID returns 404. An active campaign must be paused first.

curl -sS -X DELETE "https://api.jelliu.co/api/campaigns/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

A successful delete returns 204 No Content with an empty body.

Errors

Every error uses the standard envelope. Codes specific to campaigns:

Limits

Scopes

Adding contacts to a campaign needs only write. See Authentication.

Rate limits

• All campaign routes count against the general API limit.
• Create, update, delete, activate and pause also share the 10 per minute configuration-mutation budget with agent and webhook mutations.
• Routes under /api/campaigns/{campaignId}/contacts are limited to 5 per minute.
• GET /api/analytics/campaigns/{campaignId} is limited to 30 per minute.

Plan limits

• Only active campaigns use a slot. Drafts, paused and completed campaigns do not. Pausing a campaign frees its slot; activating one takes it.
• Creating a draft also needs a free slot. When your active campaigns already fill the plan, POST /api/campaigns is refused with 403 BILLING_ERROR even though the new campaign would start as a draft. Pause or finish a running campaign first.
• maxConcurrentCalls is clamped to your plan’s concurrent-call limit when you save it, so the stored value is the effective one.
• A workspace with no active plan cannot create or activate campaigns.

Request bounds

Webhooks

Narrow deliveries to specific campaigns with the campaignIds filter. See Webhooks.

Related