Copy page

Changelog

6 November 2026: The attention queue of a member

• Case queue: GET /v2/case-queue?memberId= (caseQueue.retrieve, scope cases:read) returns what a member has to look at, in three lists: waitingForPerson (the agent handed the case to a person and nobody took it, assigned to the member or without an owner, with waitColor green, yellow or red by the wait thresholds of the pipeline), waitingForReply (cases the member escalated, in a stage with attentionRole escalation) and answered (cases back in a stage with attentionRole answer that still need a reply to the customer). waitMinutes counts only the business hours of the pipeline, and each case appears once.
• Stages: config.attentionRole (escalation, answer or null) on POST and PATCH /v2/pipelines/{id}/stages. When a case enters an answer stage, its owner gets a notification.

6 November 2026: The API and the MCP do what the dashboard lets the role do

• Breaking, scopes: what the dashboard keeps for admins and the owner no longer hangs from cases:write, contacts:write and contacts:presence. It has scopes of its own, and a key acts with at most the role of whoever issued it:
  • cases:delete: DELETE /v2/cases/{id}, POST /v2/cases/{id}/archive, POST /v2/cases/{id}/unarchive and POST /v2/cases/{id}/messages/{messageId}/redact.
  • cases:reorganize: POST /v2/cases/move-batch, and POST /v2/cases/{id}/move when it changes the pipeline (a pipelineId, or a stageId of another pipeline). Moving between stages of the same pipeline stays in cases:write.
  • contacts:erase: DELETE /v2/contacts/{id}.
  • opt-outs:write: PUT and DELETE /v2/contacts/{contactId}/opt-outs/{channel}.
  • contact-fields:write: POST /v2/contact-fields and PATCH, DELETE /v2/contact-fields/{id}.
  • presence:configure: GET and PUT /v2/presence/settings. contacts:presence keeps only POST /v2/presence/signals.
• Existing keys and connections: the ones issued by an admin or the owner that had the old scope got the new ones, so their integrations keep working. The ones issued by a member did not: a member cannot hold them, as in the dashboard.
• Assigning: POST /v2/cases/{id}/assign records who assigned (the person who issued the key, or the person who connected through the MCP) and applies the rule of the dashboard: a member only assigns to people of their own team, and 403 forbidden otherwise. The MCP tool create_lead with assign_to follows the same rule.
• Scopes: conversations:route (POST /v1/external/conversations/{id}/derivar) now needs a key issued by an admin or the owner, like cases:reorganize.
• MCP: move_deal_to_pipeline also needs the cases:reorganize permission on the connection. The tools of the CRM check the role of the person on every call: move_deal_to_pipeline is for admins and the owner. A tool the role cannot use is not listed.

5 November 2026: Escalate a case to your technical team in Linear

• Linear: PUT, GET, PATCH and DELETE /v2/integrations/linear (linear.connect, linear.retrieve, linear.update, linear.disconnect) connect the Linear of the organization with its own API key, choose the team and project that receive the issues and save the signing secret of the Linear webhook. New scopes linear:read and linear:write, both for admins.
• Cases: POST /v2/cases/{id}/escalate-to-team (cases.escalateToTeam) creates an issue in Linear with the contact, the pipeline, the last messages and the link to the case, and never a second one while the first is open. GET /v2/cases/{id}/team-escalations lists the escalations with their issue, status and answer.
• Stages: a case that enters a stage with config.attentionRole escalation is escalated by itself when Linear is connected. When the team completes the issue, the case moves to the answer stage of the pipeline, the answer is left as an internal note and the owner of the case is notified (once). If Linear does not answer, the escalation stays pending and Lelemon retries. See Escalate a case to your technical team.

5 November 2026: Which cases a member sees, by API

• Members: PATCH /v2/members/{id}/case-scope (members.updateCaseScope) sets what a member sees: caseScope is all, unassigned_and_own, assigned, or null to follow the default of the organization. Same rule as the Team screen, capped by the role of whoever issued the key: it never touches someone with a higher role, and the owner and admins always see all. It needs members:manage and it is recorded in the audit log of members (member.scope_changed, with scopeBefore and scopeAfter).
• Members: members.list returns caseScope and effectiveCaseScope for each member. The MCP connector of Lelemon only works for people who see all cases; when it cannot connect someone, the consent screen and the token endpoint now say why (access_denied).

5 November 2026: A stage creates a task when a case does not move

• Stages: config.noProgress on POST and PATCH /v2/pipelines/{id}/stages. When a case stays in the stage for minutes (counted inside the business hours of the pipeline, when it has them), Lelemon creates a reminder of type call for the assignee of the case, or for fallbackAssigneeId when the case has no assignee, with your title and description, and can add a tag to the contact. One task per pass of the case through the stage. If the case leaves the stage or closes, the task closes by itself. See Settings of a stage.

5 November 2026: Triggers without a message

• Triggers: templateId is optional. A trigger with only onEvent opens or moves the case of the contact when the event arrives and sends nothing. POST /v2/contact-events answers 202 with sent empty, caseActions and reason set to null. A trigger with neither templateId nor onEvent is rejected with 400, and variables is now optional when there is no template. See Message on events.

4 November 2026: Organization settings and company profile

• Organization: GET, PATCH /v2/organization, GET, PATCH /v2/organization/settings and GET, PATCH /v2/organization/company-profile. They read and change the business hours, the inactivity closing, presence, branding, the company profile and the name, with the same validation as the dashboard.
• Scopes: organization:read, settings:write and organization:write. A key acts with at most the role of whoever issued it, so only a key issued by an owner can use organization:write.

4 November 2026: Teams by API

• New, teams: teams.list, teams.retrieve, teams.create, teams.update, teams.delete and teams.merge, plus teams.members.set, teams.members.remove and teams.pipelines.set to assign members and pipelines. They need the new teams:read and teams:write scopes. teams:write needs a key issued by an admin or the owner.

3 November 2026: Keys are managed only from the dashboard

• Breaking, keys: GET, POST /v2/api-keys and PATCH, DELETE /v2/api-keys/{id} and POST /v2/api-keys/{id}/rotate are removed, with apiKeys.* in the SDK and the MCP. They answer 404. Create, rotate and revoke keys from the dashboard.
• Breaking, scopes: api-keys:write no longer exists. Keys that carried it lose it.

3 November 2026: Case closed event

• Events: case.closed fires once when a case changes from open to closed. Its data has case, reason, status, closedBy and closedAt. closedBy is system, stage, agent, api or user. It covers the inactivity sweeps, closing stages, end_conversation, POST /v2/cases/{id}/close and the closes of the dashboard. See React when a case closes.

3 November 2026: Scheduled tasks for agents

• Scheduled tasks: POST /v2/agents/{id}/schedules, GET /v2/schedules, GET, PATCH and DELETE /v2/schedules/{id}. On each date of a cron, in the timezone you send, the agent gets the goal as an unattended run and writes first by email to a contact, with a file from one of its granted actions if it needs one. Ids are sch_…. They need the new scopes schedules:read and schedules:write. See Scheduled tasks.
• email_contact: a new tool you grant to the agent. It writes to the contact of the task and takes up to three attachments from HTTP actions already granted to that agent: .csv, .pdf, .xlsx or .txt, up to 5 MB each.
• Runs: Run has schedule, the id of the task that started it, or null. GET /v2/runs takes scheduleId.
• Events: schedule.fired, schedule.skipped and schedule.paused.
• Errors: invalid_cron, invalid_timezone and schedule_limit_reached.
• Fire now: POST /v2/schedules/{id}/fire starts one run right now to try a task. It does not move nextRunAt, it needs schedules:write and an Idempotency-Key, and it sends a real email.
• Email: a first email that names an agent in onReply.agentId reuses an open case of the contact only if that case is attended by the same agent. Before, it reused the contact's open case whoever attended it, so the answer went to the other agent.

2 November 2026: Runs no longer show cost

• Breaking, Run: costUsd and limits.maxCostUsd are removed from the run object and from the run.* event payloads. Token cost is internal; rounds, limits.maxRounds and limits.maxMinutes remain.
• Breaking, POST /v2/agents/{id}/runs: limits.maxCostUsd is no longer accepted. Sending it answers 400 unknown_field. To cap a run, use limits.maxRounds and limits.maxMinutes.

2 November 2026: Claude as your team's assistant

• Knowledge search: POST /v2/knowledge-collections/search (knowledgeCollections.search) returns the passages of your documents that answer a question, with the collection and document of each one. It is the search the agents use. It needs knowledge:read and changes nothing.
• Context of a team question: GET /v2/team-questions/{id}/context (teamQuestions.context) returns the question with the last lines of the conversation and the data of the case. Every sensitive value comes covered. It needs team-questions:read, conversations:read and cases:read.
• Sensitive values covered: GET /v2/team-questions and GET /v2/team-questions/{id} (and the answer route's response) now cover every sensitive value of the case in question, context and answer, as the dashboard does. The value is replaced by [dato oculto].
• MCP: both routes are tools of the MCP server, marked read only. See Use Claude as your team's assistant.

2 November 2026: Usage and budgets count conversations

Usage and budgets now measure conversations, the unit Lelemon bills: a window per case of up to 10 agent turns or 24 hours, whichever comes first. The next turn opens another conversation. The model does not change the count. Token cost is internal and no response shows it.

• Breaking, budgets: monthlyLimitUsd is now monthlyLimitConversations (an integer from 1) in POST /v2/budgets and PATCH /v2/budgets/{id}, and in the Budget object. spentUsd is now usedConversations. No budget created before this change is kept: the dollar limits have no equivalent in conversations. Create them again in conversations.
• Breaking, 402 budget_exceeded: budget.limitUsd and budget.spentUsd are now budget.limitConversations and budget.usedConversations. The error answers only when the message would open a new conversation. A case whose conversation is already open keeps answering.
• Breaking, events: budget.threshold_reached and budget.exceeded carry monthlyLimitConversations and usedConversations instead of monthlyLimitUsd and spentUsd.
• Usage: GET /v2/usage adds conversations to totals and to the groups by day, agent and subaccount. It counts from 2 November 2026 on; earlier days show zero. The groups by model do not carry it.

1 November 2026: Test mode removed

• Keys: only lel_live_ keys exist. lel_test_ keys stop working, and POST /v2/api-keys no longer takes livemode.
• livemode: removed from every object, event and webhook payload.
• Test helpers: POST /v2/test-helpers/whatsapp/inbound and the other /v2/test-helpers routes are gone. Use a number you connected.
• Errors: test_mode_limit and test_mode_only no longer exist.

1 November 2026: Erasure reaches stored responses and opt-outs hold

• Idempotency: the response stored for an Idempotency-Key is erased when the person in it is suppressed. A retry with that key answers 409 idempotency_key_reused.
• Queues: the WhatsApp history and pipeline job queues are purged when a contact is erased.
• Opt-outs survive erasure: an opt-out keeps a keyed hash of the phone and the email, so a new contact with the same number or address is still opted out.
• One rule for WhatsApp: an opt-out blocks every send to the number, including replies from the team and the test send of a template (422 contact_opted_out). The dashboard disables the send button and says why.

1 November 2026: Safer inputs

• Nesting limit: a body or a query string with objects or arrays nested more than 32 levels deep answers 400 invalid_request with param set to body or query. It used to answer 500 internal_error.
• Test send and opt-outs: POST /v2/whatsapp/templates/{id}/test checks opt-outs by phone number. A number that belongs to a contact who opted out of whatsapp answers 422 contact_opted_out and nothing is sent. dryRun=true answers the same.
• Case attachments: POST /v2/cases/{id}/attachments reads the type from the whole content and compares it with the declared Content-Type, as /v2/files does. A file that is not of its declared type, or that carries HTML or SVG with scripts, answers 400 invalid_request with param: "file".

1 November 2026: Limits that hold under load

• Webhook endpoints: an organization can have up to 16. The next POST /v2/webhook-endpoints answers 422 webhook_endpoint_limit. See Receive events.
• Limits per organization: POST /v2/actions/{id}/test (10 per minute), POST /v2/data-connectors/{id}/check (20) and POST /v2/mcp-servers/{id}/discover (20) are counted for the whole organization across all servers, and answer 429 rate_limited with Retry-After. See Rate limits.
• Pipelines and stages: deleting a pipeline or a stage while cases are being opened or moved into it can no longer leave a case in a deleted stage or pipeline, and a stage can no longer point to a stage that was just deleted.

1 November 2026: One MCP server, at api.lelemon.cl/mcp

• Remote MCP with OAuth: https://api.lelemon.cl/mcp exposes the tools of the v2 API. Paste the URL in Claude, Cursor or ChatGPT, sign in and choose the organization, the permissions and real or test data. There is no API key to copy. See MCP server.
• Permissions you grant: a connection lists only the tools its scopes cover, and each call goes through the same rules as a call with an API key. Creating API keys, new actions, approvals, revealing values, webhooks, connectors and the recipient allowlist are never granted through the MCP.
• Connections in the dashboard: Developers lists each connection with its client, permissions and last use, and removes its access at once.
• Security: PKCE S256, tokens bound to the server with resource (RFC 8707), refresh tokens that rotate, and no token forwarded to another service. Client registration is rate limited, the consent screen shows the host the client returns to, and permissions that change data are confirmed apart. A member can only grant the reads the dashboard lets a member see.
• The CRM tools stay: find_contact, send_message and the rest keep their names and work on deals.
• @lelemon-ai/mcp: it stays for environments without a browser (CI, scripts, servers) and only needs LELEMON_API_KEY.

1 November 2026: Pipeline settings and stage configuration

• Pipeline settings: POST /v2/pipelines and PATCH /v2/pipelines/{id} take settings: autoClose, businessHours, waitThresholds, askFor, timezone, stageOnTakeControl and stageOnHandoff. Every pipeline returns them, null when not set. The dashboard shows and changes the same settings. See Pipeline settings.
• Stages that close: a stage takes closes, closingOutcome and statusType. A case that arrives at a stage that closes ends and gets the outcome of the stage.
• Next stage and transitions: nextStageId and transitions on a stage, with targets in the same pipeline.
• Stage config: config takes agentMode, followUp, maxDurationSeconds, minDurationSeconds and delayMinutes. Webhooks, sources and the other keys of the panel are not part of it, and a key that is not documented answers 400 unknown_field.
• WhatsApp number by stage: whatsappPhoneNumberId on PATCH /v2/pipelines/{id}/stages/{stageId} starts the cases of a number in that stage. A number feeds one pipeline only (409 conflict).

1 November 2026: Operate cases from the API

• Tags and fields: PATCH /v2/cases/{id} takes tags (replaces the list of the contact) and writes fields of any source, not only system. Case adds tags, archivedAt and muted.
• Reveal: POST /v2/cases/{id}/fields/{key}/reveal returns a sensitive field. It needs the new scope cases:reveal, audits the key that revealed it in the same trail the dashboard writes to, never stores the value and answers 422 field_not_sensitive for any other field. In the MCP it is in the hidden keys group.
• Archive: POST /v2/cases/{id}/archive and /unarchive, and GET /v2/cases?archived=.
• Move: POST /v2/cases/move-batch moves up to 100 cases and says why each of the others did not move. POST /v2/cases/{id}/move takes pipelineId as an alternative to stageId.
• Mute and escalate: POST /v2/cases/{id}/mute, /unmute and /escalate. Escalating fires case.control_changed with escalated: true.
• Reminders: /v2/cases/{id}/reminders and /v2/reminders/{id}, with complete and dismiss. Ids are rem_….
• Notes: Note adds pinned, and PATCH /v2/cases/{id}/notes/{noteId} takes pinned.
• History of a person: the cases are GET /v2/cases?contactId=… and the messages of each one GET /v2/cases/{id}/messages. New: GET /v2/contacts/{id}/events lists the events reported for the contact. It needs triggers:read, like GET /v2/contact-events/{id}.

1 November 2026: Contact fields, contact search and companies

• Contact fields: /v2/contact-fields defines the data every contact can hold (text, textarea, email, phone, url, number, date, boolean or select). POST, PATCH and PUT /v2/contacts/by-external-ref/{externalRef} take fields, every value is checked against its type, and contacts answer fields. The contact page of the dashboard shows and edits them and the Contacts list filters by them.
• Search contacts: GET /v2/contacts takes q (name, email, phone, externalRef and contact fields, with match saying what matched), pipelineId, hasOpenCases=true, order (activity or name), and fieldKey with fieldValue. It is the search of the Contacts screen, and adds caseCount, openCaseCount and lastActivityAt to each contact.
• Companies: GET /v2/companies and GET /v2/companies/{id} with contacts:read. POST /v2/companies, PATCH /v2/companies/{id} and DELETE /v2/companies/{id} need the new scope companies:write, which asks for the same role as the dashboard (owner or admin). A rut already used by a live company answers 409 conflict with param: "rut". Deleting a company keeps its contacts and clears their companyId.
• Company of a contact: Contact adds companyId. POST /v2/contacts, PATCH /v2/contacts/{id}, PUT /v2/contacts/by-external-ref/{externalRef}, the contact of POST /v2/cases and the contact of POST /v2/contact-events take it (null unlinks, except in cases and events) with contacts:write, and a company that does not exist is a 400 with param: "companyId".
• Account in the contact page: a contact with an externalRef shows its account in your active data connector, live, with the connector's permissions and masking.

1 November 2026: Scheduling tools for the agent, delete a budget

• System tools: check_availability, schedule_meeting and cancel_meeting can be granted with PUT /v2/agents/{id}/tools/{toolId}. They book on the default agenda, so an agent no longer needs actions of your own to schedule.
• Action names: POST /v2/actions answers 409 when the name is the name of a Lelemon tool (cancel_meeting, send_email...). The agent ran the Lelemon tool instead of your action. If an action with such a name already exists, the agent is offered and runs the Lelemon tool.
• Data connector tools: a connector you create, check or delete shows up in the tools of an agent right away. A copilot could answer Unknown tool for up to five minutes after a turn had loaded the tools of the organization. The change reaches every API and worker process.
• Budgets: DELETE /v2/budgets/{id} answers 204. The dashboard has the same action.
• Subaccounts: fromTemplates.agents takes ids from GET /v2/agent-templates.

31 October 2026: Examples in every request body, how a run ends and a typed MCP

• Unknown fields: a body field the route does not document answers 400 unknown_field, and param names the first one. It was invalid_request.
• Idempotency: once a request starts running, its final response is stored whether it is 2xx, 4xx or 5xx, and a retry with the same Idempotency-Key gets the same response without repeating the effect. A request rejected before it runs, such as a body that fails validation, leaves the key free. A replayed create does not repeat the secret. See Idempotency.
• MCP servers shared with subaccounts: a platform connects a server with sharedWithSubaccounts: true, or turns it on with PATCH /v2/mcp-servers/{id}. A subaccount lists it with sharedByPlatform: true and grants its tools, but cannot change it. See Platforms.
• Usage: GET /v2/usage adds cases to totals, and to the groups by day, agent and subaccount: the cases where the agent wrote at least one reply.
• Connector in the contract: the webhooks section of openapi.json declares the four requests your connector serves, with the schemas of the format as components (ConnectorManifest, ConnectorAccountSearch, ConnectorAccount, ConnectorView).
• Runs: the completed status is gone from the contract. Nothing produced it; a run that finishes is completed_unverified.
• Contract: AgentModel and its fallback in agent answers now describe the v2 model (model, thinking, effort...). The published contract carried a v1 schema under that name.
• Cancel: POST /v2/runs/{id}/cancel on a run that is waiting_for_answer answered 500 internal_error. It now ends canceled, with question back to null, and fires run.canceled. The same applies to the v1 routes.
• Runs: the runs guide says how a run ends. The agent ends it by calling its finish action after using at least one tool. An agent that only answers in text ends stopped with stopReason: "no_conclusion" and its answer in result.partial. rounds, cost and time are limits; no_conclusion and loop are not. Every stopReason is now described in the contract and in the run.* events.
• Examples: every JSON request body in the contract has a valid example. Bodies that accept several shapes (agents.create, cases.create, caseMessages.create, whatsapp.messages.create, email.messages.create and others) have one named example per shape in examples, and each branch of a oneOf or anyOf has its own example. Postman and Insomnia import them instead of "<string>".
• MCP: each tool whose success answer has a body declares an outputSchema and returns the answer as structuredContent. Calls now wait 50 seconds, under the 60 seconds an MCP client waits by default, so the client receives the timeout error with the idempotencyKey to retry. New error code invalid_response.

31 October 2026: Case metrics and action variables in v2

• GET /v2/case-metrics: one row per case that changed in a range of up to 31 days, with when it came in, was handed off, was taken and was closed, who closed it (agent, human or system), whether the agent resolved it alone and the seconds with the agent and with a person. It needs cases:read, paginates with cursor and reads one subaccount with Lelemon-Subaccount. It replaces GET /v1/external/metrics/conversations, and the dashboard shows the same numbers on the home page, to owners and admins.
• variables on actions: POST /v2/actions and PATCH /v2/actions/{id} take variables, the fields Lelemon fills when it calls your endpoint (case.id, contact.phone or a field of the case), and every read of an action returns them. A variable that cannot be saved answers 400 invalid_request with the param that failed, 400 action_variable_in_query when it would go in a GET action, and 400 action_variable_needs_authorization when contact.phone or contact.whatsapp_id lack the authorization of the destination. authorization.dataSent names the data in English.
• Moving from v1: the conversation metrics are no longer listed as missing in v2.

31 October 2026: Agendas, meetings and team availability

• Scheduling: GET /v2/scheduling/agendas and GET /v2/scheduling/agendas/{id}, GET /v2/scheduling/availability?agendaId=… and the meetings: POST /v2/scheduling/meetings (idempotent, with dryRun), GET /v2/scheduling/meetings, GET /v2/scheduling/meetings/{id}, POST …/cancel and POST …/reschedule. Ids are agd_… and mtg_…. They need scheduling:read and scheduling:write, and scheduling:read now also reads the meetings, which carry the attendee. Meetings booked by an agent or in the dashboard show up too, and the dashboard lists the ones booked by API in Mi Negocio. See Schedule meetings.
• Events: meeting.scheduled, meeting.rescheduled and meeting.canceled, for every meeting whoever creates it.
• Team availability: GET and PUT /v2/members/{id}/availability, with status available or away and availableForAssignment. Reading needs members:read; setting needs the new scope members:write, which only sets availability. The v1 scopes miembros:read and miembros:write keep working on the v1 routes only.
• Errors: new codes slot_not_available and meeting_not_active.
• Moving from v1: scheduling and team availability leave the list of what v2 does not have yet.

31 October 2026: Runs, jobs an agent does on its own

• Runs: POST /v2/agents/{id}/runs gives an agent a goal that it works on outside your request, with limits for rounds, spending and minutes. GET /v2/runs, GET /v2/runs/{id}, POST /v2/runs/{id}/cancel and POST /v2/runs/{id}/answer list, read, cancel and answer it. Scopes runs:write and runs:read. POST takes Idempotency-Key and dryRun.
• No signature: the run works for the actor your key declares, recorded as declared by the key and sent signed by Lelemon to every action and MCP server. Without actor it works as the key. There is no shared secret and no pedidoPor. A role above the key answers 403 actor_role_above_key.
• Statuses: running, waiting_for_answer, completed_unverified (the agent says it finished and nobody checked), stopped (with stopReason), failed and canceled.
• Events: run.started, run.waiting_for_answer, run.completed, run.stopped, run.failed and run.canceled.
• Errors: new codes run_finished and run_not_waiting.
• Dashboard: the runs of an agent show under it, in Activity, and a run that asks something is answered there.
• Migration: runs leave the list of what v2 does not have yet.

30 October 2026: Talk to a copilot, ordered stages and truthful statuses

• Copilot cases: POST /v2/cases accepts the agentId of a copilot (audience: "internal") with a pipelineId or stageId for the case to live in. The copilot answers the messages written with author: "contact" and the case shows agentId of the copilot, fires the same events and shows in the dashboard. A copilot cannot open email cases or work a stage, and activating it does not ask for a stage: readiness only checks the api channel.
• Stages: GET /v2/pipelines/{id}/stages lists the stages in funnel order, from position 0 up, and its pages follow that order.
• MCP servers: a successful discovery, including the one PATCH /v2/mcp-servers/{id} runs after new credentials, puts the server back to connected.
• Data connectors: 422 data_connector_invalid_response names the failing paths and the rule each one breaks in its detail. The check endpoint reads the manifest only.
• Docs: the key can be created in the dashboard or by API, and GET /v2/actions/authorization is listed as available in v2.

30 October 2026: One naming, a stricter contract and SDKs for external developers

• Names: every single-object read is retrieve (budgets.retrieve, usage.retrieve, recipientAllowlist.retrieve, email.domains.retrieve). WhatsApp routes are whatsapp.connections.* and whatsapp.phoneNumbers.* (with commerceSettings.retrieve and update), email domains are email.domains.*, knowledgeCollections.documents.delete and subaccounts.apiKeys.create. The paths did not change.
• Fields: the key of POST /v2/subaccounts/{id}/api-keys is in secret, like every other secret the API returns once. The id of an agent tool is id, not toolId.
• Contract: every operation declares the scopes it needs (x-required-scopes, also as the scopes of its security requirement), the Idempotency-Key on every POST that uses it and the Lelemon-Subaccount header. dryRun answers declare dryRun. Recipients, case messages, interactive messages, agent bodies and approval conditions are oneOf or anyOf unions, and a body with required content is required.
• Errors in the headers: a Lelemon-Subaccount that is not a sub_… id answers 400 with param: Lelemon-Subaccount, and 404 only when the id is well formed and is not one of your subaccounts. A missing required Idempotency-Key answers 400 before the subaccount is looked up, and a method that a fixed route does not have (for example PATCH /v2/actions/authorization) answers 405. Every operation documents the 400, 404 and 409 its headers can cause.
• Webhooks: Lelemon-Delivery-Id is the whd_ id of the attempt.
• agents.activate accepts dryRun.
• Errors: every code has a concrete cause, and the generic ones have a fix.
• TypeScript SDK and MCP server: the SDK ships ESM and CommonJS, runs on Web Crypto, throws one class per error family and takes one options object (query, idempotencyKey, subaccount, signal). The MCP server filters its tools by the scopes of the key and returns the idempotency key it used. Neither is on npm yet.

30 October 2026: Rules for approvals, and automated decisions with any mode

• Rules: approval.mode accepts rules, an ordered list. The first rule whose when applies decides, with the effect allow, require_approval (its own approvers and deadlines) or reject (a hard cap that never asks). Policies saved before keep working unchanged. A platform floor still applies on top of the rules.
• Roles include the roles above them: an approval assigned to role: admin is seen and decided by owners too.
• Automated decisions (Ley 21.719, art. 8 bis): automatedDecision no longer requires mode: always. Calls that nobody approved, or that a rule rejected, are recorded and read with GET /v2/automated-decisions and GET /v2/automated-decisions/{id}. POST /v2/automated-decisions/{id}/request-review and POST /v2/approvals/{id}/request-review store what the person said (reviewReason). New event automated_decision.review_requested, and reasonCode can be policy_rule (with ruleIndex) or policy_not_required.
• approve with dryRun answers status: "preview" and the decision it would record, instead of status: "executed" with no decision.
• Erasing a contact cancels its pending approvals (event approval.canceled) and discards its open team questions, which before stayed pending with their arguments emptied.
• actions.test on a noPersist action no longer leaves the input or the answer in the request log or in the idempotency store.
• What the agent is told: a call that waits says pending_approval, approved_running or rejected_by_policy, and the action did not run. The state shows in the output of the step in GET /v2/cases/{id}/turns.
• Errors: agent_not_ready and unprocessable carry a fix; new code review_not_available.

30 October 2026: Files for messages, campaigns and templates

• POST /v2/files: upload a file once (multipart, with purpose message_media, campaign_media or template_header) and get a fil_… id. GET /v2/files, GET /v2/files/{id} and DELETE /v2/files/{id} list, read and delete. New scopes files:read and files:write. ?dryRun=true validates the file and stores nothing.
• Use it as fileId: in document, components.headerImage, components.headerVideo and the cards of a media carousel, in messages and campaigns, and as exampleFileId in the header and the carousel cards of a template. Lelemon uploads the file to WhatsApp by media id (messages) or resumable upload (template samples). A URL keeps working.
• Limits per purpose are the ones in Meta's media table, and the type is read from the content. A wrong type or content is 400 invalid_request with param: "file", a file too big is 413 payload_too_large, and a file used in the wrong place names the field. Deleting a file that a campaign that has not finished uses answers 409 resource_in_use.
• Person data: a message_media file uploaded with contactId can only be sent to that contact and is erased with them. The files of a case (/v2/cases/{id}/attachments) are a different thing and stay as they were.

30 October 2026: Approvals and team questions

• Approvals: PUT /v2/agents/{id}/tools/{toolId} accepts an approval policy. A call that meets it becomes an approval that waits; only POST /v2/approvals/{id}/approve runs it. GET /v2/approvals, reject and request-review complete the resource, with the scopes approvals:read and approvals:write.
• Who decides: a member, or an API key that the policy names. The key that proposed the action never decides it. Every decision needs a reason.
• Limits: a condition on the arguments, an accumulated limit per contact and period, an expiry and an escalation. Events approval.requested, approval.decided, approval.expired, approval.escalated and approval.review_requested.
• Team questions: the ask_team system tool, GET /v2/team-questions and POST /v2/team-questions/{id}/answer, with the scopes team-questions:read and team-questions:write. Events team_question.created and team_question.answered. The dashboard shows both queues and edits the policy of each tool. A platform can set an approval floor on a shared action with PUT /v2/actions/{id}/approval-floor. See Approve agent actions.

30 October 2026: Every WhatsApp format available in Chile

• New interactive types: cta_url, flow, location_request, contact_request, call and carousel in interactive of POST /v2/cases/{id}/messages. buttons and cta_url take headerMedia. Limits and fields are in the WhatsApp guide.
• What the person sends back: a shared location, the answer of a Flow and a phone shared for a contact_request arrive as a message of the case (location, flowResponse, contact) and as message.received with type location, flow_response or contact. The event carries no personal data.
• Failures: a message with status: "failed" has error: { code, message }.
• Catalog and commerce: catalogId on phone numbers, and GET and PATCH /v2/whatsapp/phone-numbers/{id}/commerce-settings (isCartEnabled, isCatalogVisible). A message that uses a catalog answers 422 catalog_not_connected when the number has no catalog or the id differs.
• Templates: image and video headers (components.headerImage, components.headerVideo), a variable at the end of a link button, catalog, mpm and flow buttons, and carousel (media and product cards). The sends take components; campaigns and POST /v2/whatsapp/templates/{id}/test too.
• System tools: send_carousel, send_cta_url, send_flow and request_location can be granted with PUT /v2/agents/{id}/tools/{toolId}.
• Not available in Chile: order_details, order_status and payment inside WhatsApp (Kapso Pix is only for Brazil), and the address message (India only). Payment stays an external link: use cta_url.

30 October 2026: A contract with nothing pending

• Nothing deprecated: the provider field and the AWS model ids are gone, strict bodies apply to every key. An unknown field answers 400 unknown_field, a model that is not in GET /v2/models answers 422 model_not_supported.
• dryRun on everything that sends, charges or configures: whatsapp.messages.create, email.messages.create, caseMessages.create, contactEvents.create, whatsapp.templates.test, apiKeys.rotate, campaigns.create and update, actions.create and update, triggers.create and update. It runs the same checks as the real call and answers 200 with dryRun: true, the object as it would be created and an id that is not saved. A route that sends messages or costs money must accept it: the contract tests fail otherwise.
• estimatedCost of a campaign is never null: it is the list price from the WhatsApp Business Platform rate card published by Meta (https://developers.facebook.com/docs/whatsapp/pricing), by the category of the template and the country of each phone, with effectiveFrom. Utility and authentication volume tiers are not applied, so the real charge can be lower.
• Errors that say what to do: agent_not_ready names what the agent lacks, thinking_not_supported replaces model_not_supported when a model cannot turn thinking off and points at thinking, and a trigger or campaign variable written as {{contact.name}} is a 400 that shows the right form, contact.name.
• Data connectors: http://localhost is accepted while developing, under the same rule as webhook endpoints.
• OpenAPI 3.1 with webhooks: GET /v2/openapi.json is OpenAPI 3.1. Each of the 27 event types is a webhook with its payload (the Event envelope plus the data of that type) and the webhook-signature scheme (Lelemon-Signature). nullable is now a JSON Schema type list (["string", "null"]), so the TypeScript SDK types of fields that can be null include null.

30 October 2026: Copilots and MCP from the API

• Run identity of an MCP server: GET, POST and DELETE /v2/mcp-servers/{id}/run-identity turn on, rotate and read the signed context. The secret comes once. ?dryRun=true checks it. The org and srv claims of the JWT are public ids (org_…, mcp_…), not UUIDs. The TypeScript SDK adds verifyMcpAssertion.
• Copilots: POST /v2/agents takes audience: "internal" with the new scope agents:internal. You manage and use it like any agent, and GET /v2/agents/{id}/tools lists the dct_ tools of your data connector. A turn that read data of the connector gets no tool that writes or calls another system. The assistant of the owner stays out of the API.
• Connector documents: POST /v2/data-connectors/format/validate checks a manifest, card, search answer or view page and names the failing paths.
• MCP server status: GET /v2/mcp-servers/{id} shows error and lastError when the last tool call failed, not only the last discovery. A 401 or 403 is told apart by its status, and mcp_server.failed fires on every move to rejected credentials.
• Effects: revealing a value and getting the link of an account action are write, not read, because they return personal data and write an audit row.
• Budget: 402 budget_exceeded carries budget (id, scope, subjectId, limitUsd, spentUsd, resetsAt) and Retry-After. Limits under one cent no longer read US$0.00.
• Presence: GET and PUT /v2/presence/settings turn presenceEnabled on or off.
• Actions: Action returns the authorization that is in force, or null.
• Errors: a problem in a nested body names the whole path in param, a missing field says it is missing, a fix with set names the field, and a subaccount key with bad scopes names scopes or authorName.
• Cases and campaigns: POST /v2/cases takes contact to find or create the person by externalRef or phone. schedule.at accepts "now".
• dryRun: also on rotating the signing secret of webhook endpoints, actions and connectors, and on launching and resuming a campaign.
• Usage: groupBy=subaccount counts the platform itself as the group with subaccountId: null.
• Scopes: miembros:read and miembros:write are the availability of one person; members:read lists the team. Their descriptions say so.
• Docs: the SDK page no longer says that the MCP server does not exist.

30 October 2026: Retries, events and tools

• Idempotency of tool calls: the Idempotency-Key that Lelemon sends to an action or an MCP server is now one per operation (turn, tool and arguments). If the model retries the same call, your service receives the same key and can answer once. Before, each retry came with another key.
• Agents created through the API: a contact who writes to the WhatsApp number of an agent that you put in a pipeline stage with agentId gets an answer. Before, the turn failed with Agent not found. A stage now names its agent only through agentId.
• Events of a subaccount: every event of a subaccount (message.*, case.*, budget.* and the rest) reaches the endpoints with scope: customers of its platform, with customerId. Before, only some did.
• System tools: send_buttons, send_list and send_products can be granted with PUT /v2/agents/{id}/tools/{toolId}.
• POST /v2/actions/{id}/test: signs the request like a turn.
• GET /v2/cases/{id}/turns: system tools show their public name, such as save_case_data.
• case.escalated: contact.externalRef is included.
• budget.exceeded: fires when a budget with enforcement stop runs out, not only when the next message is refused.

30 October 2026: Public model ids

• llmConfig.model: takes a public id from GET /v2/models, such as anthropic/claude-sonnet-4.6, deepseek/deepseek-v3.2 or amazon/nova-2-lite. It is the same in llmConfig.fallback. provider is no longer needed: it comes from the id.
• GET /v2/models: returns id, name, capabilities (thinkingCanBeOff and contextWindow) and deprecated. The provider field is gone and id is no longer an AWS id.
• Responses: agents, GET /v2/usage, GET /v2/cases/{id}/turns and the case.turn_completed event return the public id. llmConfig no longer has provider.
• Only public ids: the provider field and the AWS ids (us.anthropic.claude-sonnet-4-6, global.anthropic.claude-sonnet-5-5) are not accepted. See Versioning.

30 October 2026: docs

• New guides: Track usage and cap spending, Show who is online and Keep tool data out of storage.
• Objects you can open: the guides show the fields of Case, Contact, Budget and more, read from the contract.
• Diagrams: the main flows are drawn step by step. Each page says what you will do and what you need.
• Errors: every error page has the cause and how to fix it.

30 October 2026: Tools inside subaccounts

• Platform key with Lelemon-Subaccount: POST /v2/actions and POST /v2/mcp-servers create the tool inside the subaccount, checked against the sites of your key. Before, they answered 403 action_origin_not_allowed.
• Subaccount keys: accept actions:write and allowedActionOrigins, a subset of the sites of the platform key. A rejected request names the parameter.
• Shared tools: sharedWithSubaccounts on an action lets the agents of your subaccounts use it. Calls carry Lelemon-Subaccount-Id. See Run Lelemon for your customers.

30 October 2026: Hand off to a person

• System tools: PUT /v2/agents/{id}/tools/transfer_to_human and .../save_case_data let an agent hand a case to a person and write case fields. GET /v2/agents/{id}/tools lists them with kind: system and their config.
• Handoff: the stage, the business hours and the farewell are set on the grant. The farewell is written by the tool. A reply that promises a handoff on a case that was not handed over is corrected once and, if it persists, the case is handed over. See Actions and MCP in v2.

29 October 2026: API v2

Version 2 of the API is available at https://api.lelemon.cl/v2. Its API version for webhooks is 2026-10-29.

• New resources: subaccounts, agents and agent versions, actions, MCP servers, skills, knowledge collections, pipelines with stages, fields and handoff rules, contacts, cases with messages, notes and attachments, WhatsApp connections, numbers, templates and messages, email domains and messages, contact events, triggers, campaigns, opt-outs, the recipient allowlist, webhook endpoints, events and API keys.
• Conventions: prefixed ids, cursor lists, RFC 9457 errors with stable codes, Idempotency-Key on every POST, and a Request-Id on every response.
• Platforms: subaccounts with the Lelemon-Subaccount header, and webhook endpoints with scope: customers.
• Email: cases can run over email, with verified sender domains and threaded replies.
• Webhooks: signed deliveries with Lelemon-Signature, retries for up to 72 hours and a catalog of events.
• Contract: GET /v2/openapi.json is public and generated from the code.
• TypeScript SDK: generated from the contract. Not published yet.
• Docs: this site, with llms.txt, llms-full.txt and a Markdown version of every page.

29 October 2026: Built for agents

• fix on errors: when a code has a known remedy, the error carries fix with an action (set, remove, retry, call or stop). See Errors.
• ?dryRun=true: validates and answers what would happen without saving or sending anything, and does not use the Idempotency-Key. PUT /v2/recipient-allowlist accepts it first. A route that does not accept it answers 400.
• x-lelemon-effect: every operation in the contract declares read, write, destructive or money.
• MCP server for the API: generated from the contract, with annotations taken from the effect. It does not offer approvals, API keys or erasure by default. See Actions and MCP in v2.
• Strict bodies: unknown body fields are rejected with 400 unknown_field, and param names the field. metadata is not affected, and neither are responses or events. See Versioning.
• Request size: a body over 1 MB answers 413 payload_too_large.
• Docs: v1 guides moved from /guias/ to /legacy/guides/; the old addresses redirect.

30 October 2026: the context of the turn in actions and MCP servers

• Actions: every call carries Lelemon-Case-Id, Lelemon-Contact-Id, Lelemon-Contact-External-Ref, Lelemon-Subaccount-Id, the actor and an Idempotency-Key, signed in Lelemon-Signature. Verify it with verifyRequest of the SDK. The Lelemon- prefix is now reserved. See Actions and MCP in v2.
• Secret: GET /v2/actions/{id}/signing-secret and POST /v2/actions/signing-secret/rotate.
• Actor: POST /v2/cases/{id}/messages accepts actor with author: contact.
• MCP: the context travels in the claims of the run identity and in _meta, also outside runs and when an approval resumes a call.

30 October 2026: events that open cases, and cadences

• Triggers: onEvent opens or moves the case when the event arrives, and cadence repeats the template up to 5 times until the contact replies, opts out, or the case changes stage or closes. See Message on events.
• Contact events: the response carries caseActions, and two new reasons: cadence_active and outside_window.
• Webhooks: new event trigger.attempted.

30 October 2026: erasure

• Erase a contact: DELETE /v2/contacts/{id} now erases the contact, its cases, messages, files and logs, and answers 202 with a suppression. Before, it only hid the contact. Use dryRun=true to preview, closeOpenCases=true to include open cases and legalHold=true to record a request you must keep.
• Follow the job: GET /v2/suppressions/{id}.
• Redact a message: POST /v2/cases/{id}/messages/{messageId}/redact.
• Events: contact.suppressed and message.redacted, with ids only.

30 October 2026: interactive WhatsApp

• Buttons, lists and products: POST /v2/cases/{id}/messages takes interactive with type buttons, list, product, product_list or catalog. See Send buttons, lists and products.
• Template buttons: POST /v2/whatsapp/templates takes buttons of type quick_reply and url. They were ignored before; now a template that cannot be built with them answers 400 invalid_request with param: buttons.
• What the person sends back: a tap on a button or a list row arrives as a message with reply: { id, title }, and a cart from the WhatsApp catalog as a message with order. message.received carries type, reply and order.
• New error: 422 interactive_unsupported_channel, when the case is not on WhatsApp.
• Agents: the tools send_buttons, send_list and send_products.

2 November 2026: v1 deprecated

v1 (/v1/external) keeps working. Its responses carry Deprecation and a Link to Moving from v1. A Sunset header will appear when a shutdown date is set.