> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.jelliu.co/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.jelliu.co/_mcp/server. # Activate a campaign PATCH https://api.jelliu.co/api/campaigns/{campaignId}/activate Moves a `draft` or `paused` campaign to `active` and starts outreach. **This contacts real people.** No request body. What happens depends on the channel: * **`voice`:** every `pending` contact is queued for the dialer. The dialer calls only inside the campaign `schedule` (hours in its timezone, `startHour` inclusive, `endHour` exclusive), at most `max_concurrent_calls` at once (and never above the plan's ceiling). Before each call it checks the workspace's consent policy and compliance rules. Unanswered, busy or unconnected calls are redialed after `retry_interval_minutes` until the contact has had `max_retry_attempts` dials. If the workspace has no phone number, or the agent is paused, the system pauses the campaign and fills `blocked_reason`. * **`whatsapp` with `whatsapp_template_id`:** one approved-template message per `pending` contact is queued. Placeholders are filled per contact, and a missing `whatsapp_number` is copied from an E.164 `phone_number`. Sending is paced, and opted-out/`dnc` contacts are skipped. * **`email` with both `email_subject` and `email_body`:** one email per `pending` contact with an `email`, rendered per contact and sent from the workspace's own mailbox, paced and filtered by opt-outs and daily caps. * **Anything else** (`webchat`, WhatsApp without a template, email without content): the campaign is inbound-only; activation only arms the agent to answer whoever writes. Contacts a WhatsApp or email run cannot reach (no address, a placeholder that does not resolve and has no fallback) are marked `invalid` and counted in the in-app notification. If that leaves no work at all, the campaign can complete within seconds, even though this response still shows `active`. Refused **before** anything is queued when: * the status is not `draft`/`paused` (400); * a voice campaign has no `pending` contacts, or a non-voice campaign has no contacts (400); * the agent no longer serves the channel (400); * the WhatsApp template is missing or not approved by WhatsApp, its placeholders are not all covered, or the business WhatsApp sender is offline (400); * the email subject/body is half-filled or the mailbox has a sending issue (400), or no own mailbox is selected (409); * pending contacts exceed the plan's contact limit (400), or the plan's active-campaign cap is full (403). **Side effects.** Places outbound calls through the telephony carrier and the voice engine (billed as voice minutes) or sends WhatsApp/email messages (billed as messages), enqueues background jobs, sends an in-app notification and writes an audit entry. **Idempotency.** Safe to retry: activating a campaign that is already `active` returns it with 200 and queues nothing again. That also means contacts added **after** activation are not queued. To reach them, pause and activate again: only `pending` contacts are queued, so nobody already called or messaged is contacted twice. Two concurrent activations of the same campaign resolve to one winner; the other gets 409. **Webhook events.** Voice calls emit `call.completed` / `call.failed`; the campaign emits `campaign.completed` (`{ campaignId, campaignName }`) when it finishes; plus `audit.log_recorded`. See [Webhooks](/webhooks). **Access** * **Required scope:** `full`. Admin-only route: `read`/`write` keys get 403; signed-in users need the admin or owner role. * **Rate limit:** Configuration mutations — 10 requests/min per workspace, shared with agent mutations, on top of the general API limit (120 to 600 requests/min by plan). See [Rate limits](/rate-limits). * **Plan:** Active-campaign cap: Starter 1, Growth 3, Business and Enterprise unlimited (the system `manual` campaign does not count). Pending contacts must not exceed the plan's contact limit (Starter 500, Growth 2,000, Business 20,000). Reference: https://developer.jelliu.co/api-reference/campaigns/patch-campaigns-by-campaign-id-activate ## Authentication - `Authorization` header (bearer token, required) — Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication). ## Request ### Path parameters - `campaignId` (string, required) — UUID of the campaign to activate. An unknown, deleted or foreign campaign answers 404; a value that is not a UUID answers 400. ## Response ### 200 The campaign is `active` (or already was). - `data` (object, required) — A campaign row as returned by the retrieve, create, update, activate and pause endpoints. Keys are snake_case, exactly as stored. The list endpoint returns a lighter `CampaignListItem` instead. - `id` (string, optional) — Unique identifier of the campaign. - `tenant_id` (string, optional) — Workspace that owns the campaign. - `agent_id` (string, optional) — Agent that calls or chats with the contacts. Set at creation and cannot be changed. - `name` (string, optional) — Display name of the campaign. - `product_context` (string, optional) — What the campaign offers or is about. It is given to the agent as context for every conversation. - `target_audience` (string, optional) — Who the contacts are, given to the agent as context. - `status` (enum, optional) — Lifecycle state, changed only by activate, pause and the system: `draft` (created, nothing sent), `active` (running), `paused` (stopped, resumable), `completed` (no pending work left; frozen) or `archived` (frozen). - Allowed values: `draft`, `active`, `paused`, `completed`, `archived` - `channel` (enum, optional) — How the campaign reaches contacts: `voice` (phone calls), `whatsapp` (WhatsApp messages), `email` (email from the workspace's own mailbox) or `webchat` (inbound web chat only). - Allowed values: `voice`, `whatsapp`, `webchat`, `email` - `category` (enum, optional) — Purpose of the campaign; it decides how call and conversation outcomes are classified. One of `sales`, `support`, `scheduling`, `surveys`, `collections`, `retention`, `notifications`, `interview`, `language_assessment`, `general`, or the system-only `manual`. - Allowed values: `sales`, `support`, `scheduling`, `surveys`, `collections`, `retention`, `notifications`, `interview`, `language_assessment`, `general`, `manual` - `schedule` (object, optional) — Weekly calling window, stored and returned exactly as sent (camelCase inside the object). The dialer starts a call only when the local hour in `timezone` is `>= startHour` and `< endHour` on an enabled day; outside it, the call is rescheduled to the next window. A call that started inside the window may run past `endHour`. Days that are left out count as disabled. Validation: `timezone` must be a valid IANA zone (`Invalid IANA timezone`), every enabled day needs `startHour < endHour`, and at least one day must be enabled (`At least one day must be enabled`). WhatsApp and email sends are not bound to this window. - `timezone` (string, required) — IANA timezone the hours are expressed in. - `days` (list of object, required) — One entry per weekday. Only the first entry for a given day is used. - `day` (enum, required) — Day of the week, lowercase English. - Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` - `startHour` (integer, required) — First hour (inclusive) in which calls may start. - `endHour` (integer, required) — Hour (exclusive) at which calls stop starting. `18` means the last call starts before 18:00. - `enabled` (boolean, required) — Whether calls may be placed on this day. - `max_concurrent_calls` (integer, optional) — Maximum simultaneous calls for this campaign. The stored value is already lowered to the plan's ceiling (Starter 3, Growth 10, Business 25). - `max_retry_attempts` (integer, optional) — Maximum dial attempts per contact, counting the first. An unanswered, busy or unconnected call is redialed until this many calls exist; `0` or `1` means no redial. Voice only. - `retry_interval_minutes` (integer, optional) — Minutes to wait before redialing an unanswered contact (still subject to `schedule`). - `blocked_reason` (string, optional, nullable) — Why the **system** paused the campaign, in Spanish, naming the fix (for example, the workspace has no phone number, or the agent is paused). `null` when a person paused it or it was never blocked. It is not cleared on reactivation, so read it only while `status` is `paused`. - `retry_policy` (map from string to any, optional) — Legacy column, always `{}` for campaigns created through this API. Not used by the dialer. - `voicemail_action` (string, optional) — Legacy column, defaults to `retry`. Not settable and not used today; unanswered calls follow `max_retry_attempts`. - `voicemail_message` (string, optional, nullable) — Legacy column, always `null` for campaigns created through this API. - `whatsapp_template_id` (string, optional, nullable) — Approved WhatsApp template used for outbound sends. `null` keeps a WhatsApp campaign inbound-only. - `whatsapp_template_variables` (list of string or map from string to string, optional, nullable) — Campaign-wide values for the template placeholders, as an array (`{{1}}` is index 0) or an object keyed by placeholder index. The same value reaches every contact. - `whatsapp_template_variable_map` (map from string to any, optional, nullable) — Placeholders filled per contact, keyed by placeholder index. The value is a token, or `{ token, fallback }`. Indexes not in the map use `whatsapp_template_variables`. - `email_subject` (string, optional, nullable) — Subject of the outbound email, may contain `{{tokens}}`. Outbound email needs both subject and body. - `email_body` (string, optional, nullable) — Plain-text body of the outbound email, may contain `{{tokens}}`. - `created_at` (datetime, optional) — When the campaign was created. - `updated_at` (datetime, optional) — Last change to the row, including status changes. - `deleted_at` (datetime, optional, nullable) — Always `null` in responses; deleted campaigns are not returned. ## Errors ### 400 Bad Request Error The campaign cannot be activated in its current state. The message says what to fix. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 401 Unauthorized Error No usable credential. Either the `Authorization` header is missing or is not a well-formed `Bearer jl_…` key, or the key is unknown, revoked or expired. Do not retry with the same key. See [Authentication](/authentication#401-unauthorized). - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 403 Forbidden Error API key without the `full` scope, a user without the admin/owner role, or the plan's active-campaign cap is full. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 404 Not Found Error The campaign or its agent was not found. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 409 Conflict Error Another request changed the status at the same moment, or an email campaign has no own mailbox selected. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 429 Too Many Requests Error The configuration-mutation limit or the general API limit was exceeded. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ## Examples **Response** ```json { "data": { "id": "5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10", "tenant_id": "0e9d7c3b-8a1f-4c55-b7a2-3c4d5e6f7a8b", "agent_id": "9f1e2d3c-4b5a-4968-8776-655443322110", "name": "Renovaciones septiembre", "product_context": "Plan de datos móviles con 20 GB y llamadas ilimitadas por $59.900 al mes. Oferta válida hasta el 30 de septiembre.", "target_audience": "Clientes con plan vencido en los últimos 60 días", "status": "active", "channel": "voice", "category": "sales", "schedule": { "timezone": "America/Bogota", "days": [ { "day": "monday", "startHour": 9, "endHour": 18, "enabled": true }, { "day": "tuesday", "startHour": 9, "endHour": 18, "enabled": true } ] }, "max_concurrent_calls": 3, "max_retry_attempts": 3, "retry_interval_minutes": 120, "blocked_reason": null, "retry_policy": {}, "voicemail_action": "retry", "voicemail_message": null, "whatsapp_template_id": null, "whatsapp_template_variables": {}, "whatsapp_template_variable_map": {}, "email_subject": null, "email_body": null, "created_at": "2026-09-10T14:02:11.000Z", "updated_at": "2026-09-15T08:00:03.000Z", "deleted_at": null } } ``` **SDK Code** ```python Campaigns_patchCampaignsByCampaignIdActivate_example import requests url = "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate" headers = {"Authorization": "Bearer "} response = requests.patch(url, headers=headers) print(response.json()) ``` ```javascript Campaigns_patchCampaignsByCampaignIdActivate_example const url = 'https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate'; const options = {method: 'PATCH', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Campaigns_patchCampaignsByCampaignIdActivate_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate" req, _ := http.NewRequest("PATCH", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Campaigns_patchCampaignsByCampaignIdActivate_example require 'uri' require 'net/http' url = URI("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Campaigns_patchCampaignsByCampaignIdActivate_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate") .header("Authorization", "Bearer ") .asString(); ``` ```php Campaigns_patchCampaignsByCampaignIdActivate_example request('PATCH', 'https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Campaigns_patchCampaignsByCampaignIdActivate_example using RestSharp; var client = new RestClient("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Campaigns_patchCampaignsByCampaignIdActivate_example import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/activate")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```