Hamla

Run the video checker (HyperFrames lint) on a project: broken timing, animations that fight the layout, media that will not play or export. createVideo and editVideo already return lint. After creation or material visual edits, pass visual with the creative brief and up to four playhead times to inspect actual rendered frames (opening, representative scenes, ending); fix visible findings with editVideo and check the affected times again. A clean lint is not visual approval. Visual review is sampled stills, not audio/playback verification or a prediction of marketing performance.

checkVideo

Create one saved DRAFT campaign from the supplied trigger, audience, and channel message data. actions is an ordered list of campaign message steps, not a tool dispatcher: toolType selects the channel content schema. All accepted fields are declared in this input schema. This call does not run the steps, publish, schedule, or send messages. Read getCampaignChannelReadiness for compatible channel types first, then getChannelSchema for each step's toolType. Request owner approval separately before going live.

createCampaign

Create a draft Hamla Link: a hosted lead-capture page (hamla.io/f/<slug>) whose every submission becomes a contact with mapped fields and tags, and can trigger a follow-up campaign. Provide the goal, headline and questions; optionally a `canvas` page design (the html MUST carry one empty <div data-hamla-slot="form"></div> — the structured questions render there). Publishing requires the business owner in the link editor; publish=true saves the draft and returns the editor link, but never publishes it.

createHamlaLink

Get a way to put a file you hold — an image or video the person shared with you, a file on your disk — into the business's media library, when it has no public link (with a public link, or a file the app passes, use addMedia). If you can make web requests (run curl or code): PUT the file to partUrl in parts of at most 4 MB numbered from 0, then POST { parts, mimeType, name } to completeUrl; the answer's url and type go straight into mediaRefs on a draft*Post or editSocialPost. The returned steps are those commands. If you cannot make web requests, give the person personUploadUrl: it opens Hamla's Media page to upload from their device; then find the file with searchMediaLibrary. Images (JPEG, PNG, GIF, WebP, SVG), videos (MP4, WebM, MOV) and PDFs (for LinkedIn document posts) up to 50 MB. The links work for 30 minutes. Nothing is published.

createMediaUpload

Set up a task that runs on a clock — either REPEATING ("every Friday tell me how sales went", "every morning check stock") or ONCE ("remind me in twenty minutes", "check this again tonight"). Pass `schedule` for repeating, `runAt` for once — exactly one. For something they want NOW, just do it now instead; if they want it now AND later, do it and create the task. Pass their instruction through in their own words. The task runs on time, writes its answer into its own thread, and only notifies them when there is something worth saying.

createScheduledTask

Create a live, rule-driven customer segment. Use this when business wants to: - "Create a VIP segment for customers who spent over $500" - "Segment my at-risk customers" - "Make a segment for high-intent visitors" - "Group customers from Riyadh" Rules filter contacts by identity (firstName, lastName, email, phone, country, city, language, timezone), commerce (totalSpent, totalOrders, avgOrderValue, first/lastOrderDate), lifecycle (journeyStage, intentScore, churnRisk, firstSeenAt, lastActivityDate), activity (activityCount, daysSinceLastActivity, capturedBy), where a person stands on one campaign (field: "campaign" + campaignId + ladderStep, e.g. ENGAGED within_days 7 with CONVERTED not_exists: "clicked the email, did not buy"; people who opted out of that campaign are left out by themselves; check the group's size against readCampaignLadder's count for that step, and if a day window left people out, say how many and offer to include them), and business-defined custom fields (field: "custom" + customFieldKey). Date fields support within_days / older_than_days ("ordered in the last 30 days"). The segment stays live: new matching contacts join automatically.

createSegment

Make a new video in Video Studio: start a project and write its compositions (HyperFrames HTML). Read the video-craft guide first with readVideoGuide, and video-recipes for the kind of video (promo, explainer, slideshow, short motion piece). The result includes lint: fix every error with editVideo, then use checkVideo with visual to inspect real frames before telling the person it is ready, then share the returned absolute url as a clickable Markdown link (relative routes are blocked in chat). Nothing is published or sent; the person exports it from the editor.

createVideo

Delete a scheduled task so it stops running. Its thread and everything it has already told the business are kept — deleting a schedule is a statement about the future. If they only want it to stop for now, use editScheduledTask with active: false instead.

deleteScheduledTask

Delete a customer segment (memberships are removed with it; contacts themselves are untouched). Identify the segment by segmentId or its exact segmentName. If ACTIVE campaigns target the segment, the deletion is refused and the blocking campaigns are returned — pause or retarget them first, or ask the business to delete from the dashboard.

deleteSegment

Get full context for a specific contact — identity, profile, metrics, custom field values, scores, recent activities (last 20), list/segment memberships, connected platform identifiers, and a "visitor" block for how they arrived (first-touch channel/network/source, or the app store for a first visit inside the app) with a "lastVisit" block (time, region, device, app or web of their MOST RECENT visit) and a "locationOnRecord" (city/country first learned, never updated, so not where their latest visit came from). Use when the business asks about a specific person (after finding them with queryContacts).

describeContact

Draft a Facebook Page post (text/link, single image, multi-image, or reel) as a DRAFT campaign. ALWAYS call listSocialPosts first to recall recent posts + performance. The draft is NOT published — after drafting, call requestCampaignLaunch (or requestCampaignSchedule for a later time) so the business approves or schedules it.

draftFacebookPost

Draft an Instagram post (single image, carousel, or reel) as a DRAFT campaign. ALWAYS call listSocialPosts first to recall recent posts + performance and avoid repeating a topic. Generate/attach the visual before drafting. The draft is NOT published — after drafting, call requestCampaignLaunch (or requestCampaignSchedule for a later time) so the business approves or schedules it.

draftInstagramPost

Draft a LinkedIn post (text-only, single image, 2-9 images, one video, or a PDF document carousel) as a DRAFT campaign. ALWAYS call listSocialPosts first to recall recent posts + performance and avoid repeating a topic. It is published as a personal profile or a company page: pass `account` to choose, and write in that author's voice. The draft is NOT published — after drafting, call requestCampaignLaunch (or requestCampaignSchedule for a later time) so the business approves or schedules it.

draftLinkedInPost

Draft a TikTok post (a video, or a 1-35 image photo post) as a DRAFT campaign. ALWAYS call listSocialPosts first to recall recent posts + performance and avoid repeating a topic. The post goes to everyone; pass privacyLevel only when the person asked to limit a photo post. If the result says to finish something by hand, tell them. The draft is NOT published — after drafting, call requestCampaignLaunch (or requestCampaignSchedule for a later time) so the business approves or schedules it.

draftTikTokPost

Draft an X post (text only, 1-4 images, or one video) as a DRAFT campaign. ALWAYS call listSocialPosts first to recall recent posts + performance and avoid repeating a topic. Keep it under 280 characters unless the account has X Premium and the person wants a long post (up to 25,000); a post too long for the account comes back refused with the reason. Leave links out unless the business asked for one or the post needs it, and then put the link in the thread, posted right under the post, never in the post itself. The draft is NOT published — after drafting, call requestCampaignLaunch (or requestCampaignSchedule for a later time) so the business approves or schedules it.

draftXPost

Copy one campaign into a new DRAFT. Does not activate or send the copy.

duplicateCampaign

Apply the supplied changes to one existing draft campaign. Updates its name, description, trigger, audience, message content, or ordered message steps using the declared input fields. addStep is channel message data, not an executable tool call. This operation does not execute channel steps, publish, schedule, or send messages. ACTIVE and SCHEDULED campaigns cannot be edited here; return the owner editor URL without retrying. Read getCampaignChannelReadiness before adding a follow-up channel, and getChannelSchema for its toolType.

editCampaign

Edit one of the business's own blocks: rename it, change where it auto-places, or give it new html. New html is a new version and refreshes every DRAFT design carrying the block; campaigns that are scheduled, active or paused keep their copy and are listed back so the business can decide. Hamla's ready-made blocks are read-only — save your own instead.

editDesignBlock

Update one of the business's OWN design templates — a new document (same rules and checks), a rename, or a new goal tag. Hamla's verified templates cannot be edited; to build on one, getDesignTemplate it, adapt, and saveDesignTemplate as a new row.

editDesignTemplate

Update a Hamla Link's draft — headline, questions (the array REPLACES the set: call getHamlaLink first and resend what stays), reward, notifications step, thank-you, template or canvas design. Publishing requires the business owner in the link editor; publish=true saves the draft and returns the editor link, but never makes the changes live. Publishing never launches the link's follow-up campaign.

editHamlaLink

Change a scheduled task: its wording, its schedule, whether it notifies, or pause and resume it. Call listScheduledTasks first to get the taskId. Only the fields you pass change. Changing the schedule recomputes the next run; resuming a paused task clears its failure count. Passing `schedule` makes a one-off repeat, and `runAt` makes a repeating task happen once more — that conversion is an edit, not a new task.

editScheduledTask

Update an existing customer segment: rename it, change its description/color, or replace its filter rules. Use this when the business wants to: - "Change the VIP threshold to 1000" - "Rename 'Test segment' to 'Riyadh buyers'" - "Make the at-risk segment stricter" Identify the segment by segmentId or its exact segmentName. When changing rules, pass the COMPLETE new rule set (rules are replaced, not merged) using the same fields/operators as createSegment. Membership recomputes automatically and the updated contact count is returned.

editSegment

Edit a DRAFT social post (Instagram, Facebook, LinkedIn or TikTok) by campaignId: replace the caption, the media list, the format, the proposed time, or who can see a TikTok photo post when the person asks. Only what you pass changes. A scheduled post cannot be edited here — it was approved as it is: call cancelSocialPost first, edit, then requestCampaignSchedule for a new approval. Editing never publishes anything.

editSocialPost

Change a video in Video Studio by editing a composition's HTML: text, colours, sizes, timing (data-start, data-duration, in seconds), order, and GSAP animations in its <script>. Copy each find text exactly from lookAtVideo. The editor the person has open updates by itself, and the change is one entry in its history. For a small clear edit, skip routine narration and confirm success briefly after saving; explain more only when asked or when a failure needs attention. For substantial changes, summarize the visible result concisely, and keep the entryId: undoVideoEdit takes the change back. After a material visual edit, use checkVideo with visual to inspect affected frames; the returned lint alone does not judge appearance. Example: shorten the hook by changing data-duration="3" to data-duration="2" on #hook and moving the next clip's data-start from 3 to 2.

editVideo

Generate a campaign inventory report: which campaigns exist, their status, channel, and launch dates, returned in the reply. It reads only: it creates no file and saves nothing. Use this when a business wants to: - "Give me a report of my campaigns" - "Export a list of what I'm running" - "Weekly campaign summary" This report does NOT contain performance data. It carries campaign counts and statuses only — never impressions, clicks, conversions, or revenue. Send any question about outcomes to queryAnalytics instead: "how did my campaigns perform", "how are we doing", "which campaign or channel did best", "what were my results", "was it worth it". Returns structured report data that the frontend renders.

exportReport

Generate images for this business and save them to its media library. Write the prompt the way a designer briefs a photographer: one idea that earns the stop, what the picture is of, where it is, the light, the composition for the format, and any text that must appear, exact and placed, in the language the audience reads. A photo is a paragraph of sixty to a hundred and twenty words; a finished ad («ad», «post», «banner») is labelled blocks — FORMAT, PRODUCT, COMPOSITION, SCENE, LIGHT, LAYOUT, STYLE — with headline, brand name and call to action placed. A brief the person pasted goes through faithfully, never shortened. The business's brand colours are accents only on its own product, never on another brand's. No bans the person did not ask for and no closing filler. The prompt is sent to the image model exactly as written. When a product photo exists (attached this turn, or in the media library) pass its mediaItemId as referenceImageIds so the product stays exactly itself; with no photo, describe the product from what the person said and generate — do not go looking for a different product's photo. Set includeLogo when the person wants the brand logo in the picture and say in the prompt how to use it. Returns media library items (id + URL) in the exact format asked for. Load the image-craft skill first; its references hold a recipe with example prompts per deliverable (ad creative, product hero, lifestyle, offer banner, story and reel cover, app and software showcase, ugc-style content, poster, cover and illustration, character sheet). One image unless the person asks for more; each image costs AI credits and the result says how many were charged.

generateImage

Read the connected business campaign timeline in a date range. Returns campaign names, statuses, and dates; does not change or schedule campaigns.

getCampaignCalendar

Read campaign channel readiness and compatibility for the connected business. With no arguments, returns readiness statuses and blockers. With triggerType and optional stepsSoFar, returns compatible channel content types for a draft. These types describe campaign data, not callable tools. This operation never executes a channel, invokes another tool, writes data, or sends messages. Only available_now is ready; blocked channels may be drafted with their unmet prerequisite explained. For app_event, provide connectionType and event.

getCampaignChannelReadiness

Fetch the COMPLETE canvas document a campaign step is running — the html, css, frame and steps as saved. Call this before editing a design that already exists: queryCampaigns summarises what it says and does, and a summary is not enough to change one word without rewriting the rest. Node ids come from queryCampaigns → designSteps. To save the result as a reusable template use saveDesignTemplate, and to change the campaign use editCampaign — this tool only reads.

getCampaignDesign

Read the exact shape of one campaign channel's step: its message (e.g. an email's sections, a popup's canvas, an ad's creative), its config and timing, as JSON Schema, with what the channel does. Call it for each channel before writing that step in createCampaign actions or editCampaign addStep. Reads nothing of the business and changes nothing.

getChannelSchema

Fetch one reusable block with its html and the ready-to-paste `element` (the html marked as a copy of the block). Put the element into a design AS IS — the mark is what lets the business update every design from the library later. Never rewrite a block's inside in a design; edit the block itself with editDesignBlock.

getDesignBlock

Fetch one design template with its COMPLETE canvas document (html, css, frame, steps). Use it as a base to adapt — brand colors, copy, offer — never present it as your own design. Called from outside Hamla it also returns authoringRules: the complete canvas rules for this design type. Follow them when you write or adapt the html; anything outside them is stripped.

getDesignTemplate

One Hamla Link's full draft setup: goal, questions (with their contact-field/tag mapping), reward, notifications step, thank-you, design. Call before editHamlaLink so an edit builds on what is there.

getHamlaLink

Get this business's real Hamla website snippet, ready to paste, plus whether the install has recorded a visit yet. Use this whenever someone asks to add Hamla to a site, install tracking, or set up the SDK — never write the script tag from memory, because the business id in it cannot be guessed and a wrong one fails silently. Returns no secret key.

getInstallSnippet

See every popup live on the business's website now — its trigger and timing, the pages and devices it shows on — plus the rules the site enforces (one popup per page view, a cap per visit, a cooldown, protected pages) and which live popups compete. Call this BEFORE creating or changing a popup: a new popup that fires on the same pages as a live one only shows when its trigger fires first. Pass excludeCampaignId when editing so the map shows what that campaign competes with. Read-only; change popups with editCampaign.

getOnsiteMap

Read one social post in full by its campaignId: the whole caption, every media URL, platform and account, status, when it goes or went out, the permalink, why the last attempt failed (if it did), and its reach, impressions, likes, comments, shares and views day by day. Use after listSocialPosts when the business asks about a specific post.

getSocialPost

Record that the business has permission to market to a set of contacts, in bulk. Use when contacts exist but campaigns cannot reach them because consent was never captured — typically right after an import, or when the business says a campaign is reaching nobody. Scope it with tag, segmentId, or contactIds; with no scope it covers every contact still lacking consent. ALWAYS preview with commit=false first and show the count. This records a legal assertion about real people: set attested=true ONLY when the business has said in their own words that they have permission. Never infer it from a request to send a campaign. Contacts who opted out directly are always excluded, and prior unsubscribes are never undone.

grantConsent

Show Hamla's home for the business: drafts waiting for the owner, open alerts, campaigns that are running, and visitors, goals reached and revenue over the last 30 days. Read-only; nothing is sent or changed. Call it when the person asks how their marketing is doing overall or what needs them.

openHamlaHome

Import the contact records from a saved previewContactImport snapshot after user confirmation. Requires its unexpired previewId and uses exactly its stored rows, mapping and options. May overwrite existing contact fields when the reviewed option is update. Does not grant marketing consent, send messages, launch campaigns or upload advertising audiences.

importContacts

Import the historical customer activity from a saved previewCustomerHistoryImport snapshot after user confirmation. Requires its unexpired previewId and uses exactly its stored rows, mapping and options. Records historical activity and paid amounts, not estimated customer values. Does not grant marketing consent, send messages, launch campaigns or upload advertising audiences.

importCustomerHistory