{ "api-reference/operations/getme": { "routeSlug": "api-reference/operations/getme", "operationId": "getMe", "method": "GET", "path": "/me", "summary": "Identify the calling key", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": null, "responses": [ { "code": "200", "description": "Key identity", "example": { "data": { "team_id": "", "key": { "id": "", "name": "", "scopes": [] } } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listleads": { "routeSlug": "api-reference/operations/listleads", "operationId": "listLeads", "method": "GET", "path": "/leads", "summary": "List leads", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "type": "string", "enum": [ "qualified", "in_progress", "not_interested", "cold", "pending", "stopped", "queued" ], "example": "" }, { "name": "campaign_id", "in": "query", "required": false, "description": "Filter by campaign. Accepts the campaign's `campaign_id` slug or its document `id` (both returned by `GET /campaigns`).", "type": "string", "example": "" }, { "name": "phone", "in": "query", "required": false, "description": "Exact lookup by phone (international format, e.g. `+33612345678`).", "type": "string", "example": "" }, { "name": "external_reference", "in": "query", "required": false, "description": "Exact lookup by the id you sent on `POST /campaigns/{id}/leads`. The supported way to resolve \"which WhatSetter lead is my record #4471?\".", "type": "string", "example": "" }, { "name": "channel", "in": "query", "required": false, "description": "Only leads reached on this channel. `whatsapp` also returns leads created before the channel column existed, so it always means \"everything that is not Instagram\".", "type": "string", "enum": [ "whatsapp", "instagram" ], "example": "" }, { "name": "since", "in": "query", "required": false, "description": "Only leads active after this ISO-8601 date (on `last_message_at`).", "type": "string", "example": "" }, { "name": "source", "in": "query", "required": false, "description": "Where the lead came from (see the `source` field). Exact match on the stored value — leads created before origins were recorded stay out of a filtered listing.", "type": "string", "enum": [ "instagram", "facebook", "tiktok", "youtube", "linkedin", "x", "snapchat", "pinterest", "google", "website", "email", "sms", "qr", "ads", "other", "direct", "list", "api", "webhook", "inbound", "manual" ], "example": "" }, { "name": "tracked_link_id", "in": "query", "required": false, "description": "Only leads brought by this tracked WhatsApp link (Dashboard → Liens).", "type": "string", "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of leads", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/getlead": { "routeSlug": "api-reference/operations/getlead", "operationId": "getLead", "method": "GET", "path": "/leads/{id}", "summary": "Get a lead", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The lead", "example": { "data": { "id": "", "phone": "", "whatsapp_id": "", "name": "", "status": "qualified", "qualified": false, "qualified_at": "", "replied": false, "campaign_id": "", "list_id": "", "source": "instagram", "source_confidence": "certain", "tracked_link_id": "", "external_reference": "", "channel": "whatsapp", "ig_username": "", "email": "", "tags": [], "messages_count": 0, "booking_status": "", "assigned_to": "", "stage": "contacted", "deal_status": "open", "lost_reason": "price", "next_action_at": "", "next_action_label": "", "first_contact_at": "", "last_message_at": "", "last_message_direction": "inbound", "created_at": "", "updated_at": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/updatelead": { "routeSlug": "api-reference/operations/updatelead", "operationId": "updateLead", "method": "PATCH", "path": "/leads/{id}", "summary": "Update a lead", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": { "required": true, "example": { "assigned_to": "66a1f2c3d4e5f60718293a4b", "next_action_at": "2026-09-22T09:00:00.000Z", "next_action_label": "Call back", "deal_status": "open" } }, "responses": [ { "code": "200", "description": "The updated lead", "example": { "data": { "id": "68e0a1b2c3d4e5f6a7b8c9d0", "phone": "33612345678", "whatsapp_id": "33612345678@c.us", "name": "Marie Dupont", "status": "in_progress", "qualified": false, "qualified_at": null, "replied": true, "campaign_id": "auto24-maroc-4-bu76", "list_id": null, "source": "instagram", "source_confidence": "certain", "tracked_link_id": "68d9aa11bb22cc33dd44ee55", "external_reference": "4471", "channel": "whatsapp", "ig_username": null, "email": "marie@acme.fr", "tags": [ "hot" ], "messages_count": 7, "booking_status": null, "assigned_to": "66a1f2c3d4e5f60718293a4b", "stage": "conversation", "deal_status": "open", "lost_reason": null, "next_action_at": "2026-09-22T09:00:00.000Z", "next_action_label": "Call back", "first_contact_at": "2026-09-15T10:02:11.000Z", "last_message_at": "2026-09-18T16:40:03.000Z", "last_message_direction": "inbound", "created_at": "2026-09-15T10:02:11.000Z", "updated_at": "2026-09-19T08:12:45.000Z" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid field, unknown member id, or nothing to update", "example": { "error": { "code": "validation_error", "message": "\"assigned_to\" must be the id of a member of this workspace (see GET /team/members), or null." } } } ], "dangerous": false }, "api-reference/operations/handofflead": { "routeSlug": "api-reference/operations/handofflead", "operationId": "handoffLead", "method": "POST", "path": "/leads/{id}/handoff", "summary": "Take the conversation over (stops the AI agent)", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "The WhatSetter lead id — the `id` from `GET /leads`, and the `contact.id` you receive on webhooks.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The agent is now stopped on this conversation", "example": { "data": { "id": "", "external_reference": "", "agent_active": false, "manual_override": false, "status": "", "dashboard_synced": false, "updated_at": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "409", "description": "`invalid_state`: the lead has no conversation to hand over — it has not been contacted yet (queued or pending), or the workflow found no conversation row for it.", "example": { "error": { "code": "invalid_state", "message": "Handoff applies to leads the agent has already engaged. This one is \"queued\" — it has not been contacted yet." } } }, { "code": "500", "description": "Agent control is not configured on this deployment (`internal_error`)", "example": { "error": { "code": "", "message": "" } } }, { "code": "502", "description": "`upstream_error`: the agent-control workflow was unreachable or refused the change. Safe to retry.", "example": { "error": { "code": "upstream_error", "message": "The agent-control workflow is unreachable. Try again in a moment." } } } ], "dangerous": false }, "api-reference/operations/resumelead": { "routeSlug": "api-reference/operations/resumelead", "operationId": "resumeLead", "method": "POST", "path": "/leads/{id}/resume", "summary": "Give the conversation back to the AI agent", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "The WhatSetter lead id (same as `contact.id` on webhooks).", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The agent is active again on this conversation", "example": { "data": { "id": "", "external_reference": "", "agent_active": false, "manual_override": false, "status": "", "dashboard_synced": false, "updated_at": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "409", "description": "`invalid_state`: the lead has no conversation yet (not contacted).", "example": { "error": { "code": "", "message": "" } } }, { "code": "500", "description": "Agent control is not configured on this deployment (`internal_error`)", "example": { "error": { "code": "", "message": "" } } }, { "code": "502", "description": "`upstream_error`: the agent-control workflow was unreachable or refused the change. Safe to retry.", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listleadnotes": { "routeSlug": "api-reference/operations/listleadnotes", "operationId": "listLeadNotes", "method": "GET", "path": "/leads/{id}/notes", "summary": "List a lead's notes", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The notes, newest first", "example": { "data": [ { "id": "68ed11aa22bb33cc44dd55ee", "text": "Wants a call after the 25th, budget confirmed.", "author": "API · HubSpot sync", "created_at": "2026-09-19T08:14:02.000Z" }, { "id": "68ec0099aa88bb77cc66dd55", "text": "Asked for the brochure, sent.", "author": "Julien Martin", "created_at": "2026-09-17T15:20:41.000Z" } ] } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/createleadnote": { "routeSlug": "api-reference/operations/createleadnote", "operationId": "createLeadNote", "method": "POST", "path": "/leads/{id}/notes", "summary": "Add a note to a lead", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": { "required": true, "example": { "text": "Wants a call after the 25th, budget confirmed." } }, "responses": [ { "code": "201", "description": "The note", "example": { "data": { "id": "68ed11aa22bb33cc44dd55ee", "text": "Wants a call after the 25th, budget confirmed.", "author": "API · HubSpot sync", "created_at": "2026-09-19T08:14:02.000Z" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Empty or too long", "example": { "error": { "code": "validation_error", "message": "\"text\" is required (1 to 2000 characters)." } } } ], "dangerous": false }, "api-reference/operations/listconversations": { "routeSlug": "api-reference/operations/listconversations", "operationId": "listConversations", "method": "GET", "path": "/conversations", "summary": "List conversations (inbox)", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "campaign_id", "in": "query", "required": false, "description": "Filter by campaign. Accepts the campaign's `campaign_id` slug or its document `id` (both returned by `GET /campaigns`).", "type": "string", "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of conversation summaries", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listconversationmessages": { "routeSlug": "api-reference/operations/listconversationmessages", "operationId": "listConversationMessages", "method": "GET", "path": "/conversations/{leadId}/messages", "summary": "Get a conversation transcript", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "leadId", "in": "path", "required": true, "description": "", "type": "string", "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of messages", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listlists": { "routeSlug": "api-reference/operations/listlists", "operationId": "listLists", "method": "GET", "path": "/lists", "summary": "List lead lists", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": null, "responses": [ { "code": "200", "description": "The workspace's lists", "example": { "data": [] } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/createlist": { "routeSlug": "api-reference/operations/createlist", "operationId": "createList", "method": "POST", "path": "/lists", "summary": "Create a list", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": { "required": true, "example": { "name": "" } }, "responses": [ { "code": "201", "description": "Created", "example": { "data": { "id": "", "name": "", "status": "", "total_rows": 0, "valid_leads": 0, "invalid_leads": 0, "created_at": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } }, { "code": "429", "description": "The workspace already holds 200 lists", "example": { "error": { "code": "quota_exceeded", "message": "List limit reached (200 per workspace). Delete unused lists first." } } } ], "dangerous": false }, "api-reference/operations/importleads": { "routeSlug": "api-reference/operations/importleads", "operationId": "importLeads", "method": "POST", "path": "/lists/{id}/leads", "summary": "Push leads into a list", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": { "required": true, "example": { "leads": [ { "phone": "+33612345678", "name": "Marie Dupont", "email": "marie@acme.fr", "custom_variables": { "offre": "Pack Pro", "ville": "Lyon" } }, { "phone": "not a phone" } ] } }, "responses": [ { "code": "201", "description": "Import result (valid rows imported, the rest listed in `rejected`)", "example": { "data": { "imported": 1, "duplicates_in_list": 0, "rejected": [ { "index": 1, "reason": "invalid_phone: expected international format, e.g. +33612345678" } ], "lead_ids": [ "68f0aa11bb22cc33dd44ee55" ] } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "`leads` is not an array of 1–500 objects, or no row is importable", "example": { "error": { "code": "validation_error", "message": "No importable lead in the batch (2 rejected). First reason: duplicate_in_batch." } } } ], "dangerous": false }, "api-reference/operations/listcampaigns": { "routeSlug": "api-reference/operations/listcampaigns", "operationId": "listCampaigns", "method": "GET", "path": "/campaigns", "summary": "List campaigns", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": null, "responses": [ { "code": "200", "description": "The workspace's campaigns", "example": { "data": [] } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/sendmessage": { "routeSlug": "api-reference/operations/sendmessage", "operationId": "sendMessage", "method": "POST", "path": "/messages", "summary": "Send a WhatsApp message to a lead", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": { "required": true, "example": { "lead_id": "", "text": "", "humanize": true } }, "responses": [ { "code": "201", "description": "Message sent", "example": { "data": { "id": "68f2bb33cc44dd55ee66ff77", "message_id": "true_33612345678@c.us_3EB0C8A1B2C3D4E5F6", "lead_id": "68e0a1b2c3d4e5f6a7b8c9d0", "text": "Bonjour Marie, je vous confirme notre appel de demain à 10h.", "sent_at": "2026-09-19T08:12:45.000Z", "humanized": true, "typing_ms": 4200, "quota": { "limit": 250, "used": 41, "remaining": 209, "resets_at": "2026-09-20T00:00:00.000Z" } } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "409", "description": "Either the lead was never contacted (`lead_not_contacted`: cold\noutreach must go through lists + campaigns) or a request with the\nsame Idempotency-Key is still in flight (`request_in_flight`).\n", "example": { "error": { "code": "lead_not_contacted", "message": "This lead has never been contacted. First contact must go through a list + campaign (the anti-ban pipeline) — see POST /v1/lists/{id}/leads." } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } }, { "code": "429", "description": "Daily anti-ban quota reached for this number (`quota_exceeded`, resets at midnight UTC)", "example": { "error": { "code": "quota_exceeded", "message": "Daily WhatsApp quota reached for this number (250 messages — anti-ban protection). It resets at midnight UTC." } } }, { "code": "500", "description": "Messaging backend not configured on this deployment (`internal_error`)", "example": { "error": { "code": "", "message": "" } } }, { "code": "502", "description": "`send_failed`: the WhatsApp engine refused the message, or did not\nconfirm it in time. With an `Idempotency-Key`, retrying is safe\n(an ambiguous send keeps the key so the retry can never\ndouble-deliver); without one, do not blindly retry.\n", "example": { "error": { "code": "send_failed", "message": "The message could not be sent. Retry shortly." } } }, { "code": "503", "description": "`agent_disconnected`: the campaign has no WhatsApp number, or the\nnumber is currently disconnected. Reconnect it in the dashboard.\n", "example": { "error": { "code": "agent_disconnected", "message": "The WhatsApp number for this campaign is currently disconnected. Reconnect it in the dashboard." } } } ], "dangerous": true }, "api-reference/operations/pausecampaign": { "routeSlug": "api-reference/operations/pausecampaign", "operationId": "pauseCampaign", "method": "POST", "path": "/campaigns/{id}/pause", "summary": "Pause a campaign", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The paused campaign", "example": { "data": { "id": "", "campaign_id": "", "name": "", "status": "active", "purpose": "setter", "whatsapp_connected": false, "created_at": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "409", "description": "Campaign is not active", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/resumecampaign": { "routeSlug": "api-reference/operations/resumecampaign", "operationId": "resumeCampaign", "method": "POST", "path": "/campaigns/{id}/resume", "summary": "Resume a paused campaign", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The reactivated campaign", "example": { "data": { "id": "", "campaign_id": "", "name": "", "status": "active", "purpose": "setter", "whatsapp_connected": false, "created_at": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "402", "description": "Active-campaign plan limit reached", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "409", "description": "Campaign is not paused", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/addcampaignlead": { "routeSlug": "api-reference/operations/addcampaignlead", "operationId": "addCampaignLead", "method": "POST", "path": "/campaigns/{id}/leads", "summary": "Add an opt-in lead (sends their first message)", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "Campaign document id, or its `campaign_id` slug.", "type": "string", "example": "" } ], "requestBody": { "required": true, "example": { "phone": "+33612345678", "name": "Marie Dupont", "email": "marie@acme.fr", "source_url": "crm:hubspot", "external_reference": "4471", "additional_data": { "offre": "Pack Pro", "ville": "Lyon", "budget": "500-1000" } } }, "responses": [ { "code": "202", "description": "Lead accepted into the first-contact pipeline", "example": { "data": { "status": "", "campaign_id": "", "phone": "", "external_reference": "", "note": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "409", "description": "`invalid_state`: the campaign is not active (pause / draft /\narchived), or it has never been opened in the dashboard and has no\nfunnel identifiers yet (open it once, or contact support).\n", "example": { "error": { "code": "invalid_state", "message": "Leads can only be pushed to an active campaign (current status: paused)." } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } }, { "code": "502", "description": "`upstream_error`: the first-message pipeline is unreachable or did not accept the lead. Safe to retry in a moment.", "example": { "error": { "code": "upstream_error", "message": "The first-message pipeline is unreachable. Try again in a moment." } } } ], "dangerous": true }, "api-reference/operations/listbookings": { "routeSlug": "api-reference/operations/listbookings", "operationId": "listBookings", "method": "GET", "path": "/bookings", "summary": "List bookings", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "status", "in": "query", "required": false, "description": "Exact match on the booking status.", "type": "string", "enum": [ "booked", "canceled", "rescheduled", "failed", "no_show" ], "example": "" }, { "name": "campaign_id", "in": "query", "required": false, "description": "Filter by campaign. Accepts the campaign's `campaign_id` slug or its document `id` (both returned by `GET /campaigns`).", "type": "string", "example": "" }, { "name": "since", "in": "query", "required": false, "description": "Only bookings starting after this ISO-8601 date.", "type": "string", "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of bookings", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listgroups": { "routeSlug": "api-reference/operations/listgroups", "operationId": "listGroups", "method": "GET", "path": "/groups", "summary": "List WhatsApp groups", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "status", "in": "query", "required": false, "description": "", "type": "string", "enum": [ "active", "paused", "archived", "left" ], "example": "" }, { "name": "community_id", "in": "query", "required": false, "description": "Only groups that belong to this WhatsApp Community (`community.id` of a group).", "type": "string", "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of groups", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/getgroup": { "routeSlug": "api-reference/operations/getgroup", "operationId": "getGroup", "method": "GET", "path": "/groups/{id}", "summary": "Get a WhatsApp group", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The group", "example": { "data": "" } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listgroupmembers": { "routeSlug": "api-reference/operations/listgroupmembers", "operationId": "listGroupMembers", "method": "GET", "path": "/groups/{id}/members", "summary": "List group members", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" }, { "name": "status", "in": "query", "required": false, "description": "", "type": "string", "enum": [ "active", "left" ], "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of members", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listgroupmessages": { "routeSlug": "api-reference/operations/listgroupmessages", "operationId": "listGroupMessages", "method": "GET", "path": "/groups/{id}/messages", "summary": "List group messages", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" }, { "name": "since", "in": "query", "required": false, "description": "ISO-8601 — only messages sent at or after this instant.", "type": "string", "example": "" }, { "name": "until", "in": "query", "required": false, "description": "ISO-8601 — only messages sent at or before this instant.", "type": "string", "example": "" }, { "name": "sender", "in": "query", "required": false, "description": "One member's phone, international digits (e.g. `33612345678`).", "type": "string", "example": "" }, { "name": "from_agent", "in": "query", "required": false, "description": "`true` = only messages WhatSetter sent (AI or manual); `false` = only members' messages.", "type": "boolean", "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of messages", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listgroupevents": { "routeSlug": "api-reference/operations/listgroupevents", "operationId": "listGroupEvents", "method": "GET", "path": "/groups/{id}/events", "summary": "List group join / leave events", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" }, { "name": "type", "in": "query", "required": false, "description": "", "type": "string", "enum": [ "join", "leave" ], "example": "" }, { "name": "since", "in": "query", "required": false, "description": "ISO-8601 — only events at or after this instant.", "type": "string", "example": "" }, { "name": "until", "in": "query", "required": false, "description": "ISO-8601 — only events at or before this instant.", "type": "string", "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Page of events", "example": { "data": [], "pagination": { "has_more": false, "next_cursor": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listwebhooks": { "routeSlug": "api-reference/operations/listwebhooks", "operationId": "listWebhooks", "method": "GET", "path": "/webhooks", "summary": "List webhook subscriptions", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": null, "responses": [ { "code": "200", "description": "The workspace's subscriptions", "example": { "data": [] } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/createwebhook": { "routeSlug": "api-reference/operations/createwebhook", "operationId": "createWebhook", "method": "POST", "path": "/webhooks", "summary": "Create a webhook subscription", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": { "required": true, "example": { "url": "", "events": [], "description": "" } }, "responses": [ { "code": "201", "description": "Created, note the one-time `secret`", "example": { "data": "" } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/deletewebhook": { "routeSlug": "api-reference/operations/deletewebhook", "operationId": "deleteWebhook", "method": "DELETE", "path": "/webhooks/{id}", "summary": "Delete a webhook subscription", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Deleted", "example": null }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/testwebhook": { "routeSlug": "api-reference/operations/testwebhook", "operationId": "testWebhook", "method": "POST", "path": "/webhooks/{id}/test", "summary": "Send a test delivery now", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "Delivery attempt result", "example": { "data": { "delivered": false, "endpoint_status": "", "error": "", "event_id": "" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listblockedcontacts": { "routeSlug": "api-reference/operations/listblockedcontacts", "operationId": "listBlockedContacts", "method": "GET", "path": "/blocked-contacts", "summary": "List blocked numbers and prefixes", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "kind", "in": "query", "required": false, "description": "", "type": "string", "enum": [ "number", "prefix" ], "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 50 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The rules", "example": { "data": [ { "id": "68f1a0b1c2d3e4f5a6b7c8d9", "kind": "number", "value": "33612345678", "phone": "+33612345678", "label": "Spammer", "reason": null, "campaign_id": null, "created_at": "2026-09-15T12:00:00.000Z" }, { "id": "68f1a0b1c2d3e4f5a6b7c8da", "kind": "prefix", "value": "91", "phone": null, "label": "India", "reason": "Out of market", "campaign_id": null, "created_at": "2026-09-15T12:01:00.000Z" } ], "pagination": { "has_more": false, "next_cursor": null } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/createblockedcontact": { "routeSlug": "api-reference/operations/createblockedcontact", "operationId": "createBlockedContact", "method": "POST", "path": "/blocked-contacts", "summary": "Block a number or a dial prefix", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": { "required": true, "example": { "kind": "prefix", "prefix": "+91", "label": "India", "reason": "Out of market" } }, "responses": [ { "code": "201", "description": "The rule", "example": { "data": { "id": "68f1a0b1c2d3e4f5a6b7c8da", "kind": "prefix", "value": "91", "phone": null, "label": "India", "reason": "Out of market", "campaign_id": null, "created_at": "2026-09-15T12:01:00.000Z" } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "409", "description": "This number or prefix is already blocked", "example": { "error": { "code": "already_blocked", "message": "The +91 prefix is already blocked in this workspace." } } }, { "code": "422", "description": "Invalid kind, phone, prefix, label or reason", "example": { "error": { "code": "validation_error", "message": "\"prefix\" must be a dial code of 1 to 4 digits, e.g. +91." } } }, { "code": "429", "description": "The workspace already holds 500 rules", "example": { "error": { "code": "quota_exceeded", "message": "This workspace already has 500 blocked entries. Remove some first." } } } ], "dangerous": false }, "api-reference/operations/deleteblockedcontact": { "routeSlug": "api-reference/operations/deleteblockedcontact", "operationId": "deleteBlockedContact", "method": "DELETE", "path": "/blocked-contacts/{id}", "summary": "Unblock (remove a rule)", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "204", "description": "Removed", "example": null }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listteammembers": { "routeSlug": "api-reference/operations/listteammembers", "operationId": "listTeamMembers", "method": "GET", "path": "/team/members", "summary": "List team members", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [], "requestBody": null, "responses": [ { "code": "200", "description": "The members", "example": { "data": [ { "id": "66a1f2c3d4e5f60718293a4b", "name": "Alexis Dubain", "email": "alexis@acme.com", "role": "owner", "is_owner": true }, { "id": "66b2e3d4c5f6a7b8c9d0e1f2", "name": "Julien Martin", "email": "julien@acme.com", "role": "responder", "is_owner": false } ] } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/listlinks": { "routeSlug": "api-reference/operations/listlinks", "operationId": "listLinks", "method": "GET", "path": "/links", "summary": "List tracked links", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "campaign_id", "in": "query", "required": false, "description": "Campaign document id or `campaign_id` slug.", "type": "string", "example": "" }, { "name": "status", "in": "query", "required": false, "description": "", "type": "string", "enum": [ "active", "inactive" ], "example": "" }, { "name": "limit", "in": "query", "required": false, "description": "", "type": "integer", "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's `pagination.next_cursor`.", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The links", "example": { "data": [ { "id": "68d9aa11bb22cc33dd44ee55", "slug": "insta-bio", "name": "Instagram bio", "url": "https://app.whatsetter.com/l/insta-bio", "campaign_id": "auto24-maroc-4-bu76", "status": "active", "channel": "auto", "clicks": 128, "last_click_at": "2026-09-18T10:00:00.000Z", "created_at": "2026-09-01T08:00:00.000Z" } ], "pagination": { "has_more": false, "next_cursor": null } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "422", "description": "Invalid parameter or body (also an invalid or expired `cursor`)", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false }, "api-reference/operations/getlink": { "routeSlug": "api-reference/operations/getlink", "operationId": "getLink", "method": "GET", "path": "/links/{id}", "summary": "Get a tracked link with its stats", "servers": [ "https://app.whatsetter.com/api/v1" ], "params": [ { "name": "id", "in": "path", "required": true, "description": "", "type": "string", "example": "" } ], "requestBody": null, "responses": [ { "code": "200", "description": "The link and its stats", "example": { "data": { "id": "68d9aa11bb22cc33dd44ee55", "slug": "insta-bio", "name": "Instagram bio", "url": "https://app.whatsetter.com/l/insta-bio", "campaign_id": "auto24-maroc-4-bu76", "status": "active", "channel": "auto", "clicks": 128, "last_click_at": "2026-09-18T10:00:00.000Z", "created_at": "2026-09-01T08:00:00.000Z", "stats_30d": { "clicks": 128, "by_channel": { "instagram": 90, "tiktok": 30, "direct": 8 }, "leads": 41, "qualified": 12 } } } }, { "code": "401", "description": "Missing, unknown or revoked API key", "example": { "error": { "code": "", "message": "" } } }, { "code": "403", "description": "The key lacks the required scope", "example": { "error": { "code": "", "message": "" } } }, { "code": "404", "description": "Resource not found in this workspace", "example": { "error": { "code": "", "message": "" } } } ], "dangerous": false } }