Gambot WhatsApp Business API

Add and/or remove TAGS across MANY contacts at once (merging with each contact's existing tags). Choose the audience with `phones` (explicit list) and/or `fromTag` (apply to every contact that currently has that tag — e.g. re-tag a whole group). Provide `add` and/or `remove`. Returns { requested, updated, notFound }. Great for 'tag everyone in group A as B', 'remove tag X from these numbers', bulk segmentation, etc.

Check whether an organization already exists for a company + tax id (ח.פ/ת.ז), and whether an incomplete onboarding can be resumed. Use before creating a new trial.

Check whether the 24-hour WhatsApp customer-service window is OPEN for a contact BEFORE you message them. WhatsApp only allows free text while the window is open (i.e. the contact messaged you in the last 24h); once it's CLOSED you MUST use an approved template. Call this whenever you're about to send a one-off message and aren't sure the conversation is active — then route accordingly: windowOpen=true → gambot_send_text (or a template); windowOpen=false → gambot_send_template (list options with gambot_list_templates). Returns { phone, windowOpen, canSendFreeText, requiresTemplate, reason, rec…

Create a NEW Gambot AI brain. Only do this if the org has none (check gambot_list_ai first — most orgs already have one auto-built from their website). After creating, wire it to a botomation whose trigger is contactOwner == 'Gambot AI' (built in the Bot Builder app) and route contacts by assigning owner = 'Gambot AI'.

Advanced: create a bot from a full botomation object when the high-level builders aren't enough. steps[]: step 1 is the trigger (action 'IncomingMessage', …), the rest are actions ('SendMessage','switchCase','Condition','GambotAi','Delay','GambotAction',…). Use {{Step_1_PhoneNumber}} / {{Step_1_Message}} placeholders. ── STEP CONFIG FEATURES you can set (parity with the visual Bot Builder): • On a REGULAR IncomingMessage trigger config → aiContextGate:{enabled:true,prompt,model:'gpt-4o-mini',onExhausted:'advance'} for an on-topic CONTEXT check ('בדיקת הקשר'). • On a REGULAR SendMessage config …

Create a SAVED WhatsApp broadcast campaign. Use this whenever the send should be a campaign — i.e. ANY scheduled send (one-time OR recurring is ALWAYS a campaign), or a reusable CRM-segment broadcast. For a plain immediate send to a tag/list use gambot_send_campaign; for an Excel/CSV sheet use gambot_send_campaign_from_excel (which also saves a campaign). After creating, run it now with gambot_run_campaign (scheduled ones run automatically at runAt). For a template broadcast set messageType='Template' + wabaTemplateId; for free text set messageType='regular' + message (note: a 'regular' broadc…

Create a case (support ticket / פנייה). Accepts base fields plus a nested 'customFields' object.

Create a contact (returns the existing one if the phone is already known). Custom/dynamic fields go under 'customFields' (see gambot_get_contact_fields for keys). ── MARKETING COMPLIANCE — always consider these when creating a contact: • consent ('הסכמה לדיוור'): set consent=true ONLY when the person actually agreed to receive marketing (they ticked a box / said yes / signed up). Set consent=false to record an opt-out. If you don't know, OMIT it — never assume true. consent=false contacts are auto-excluded from every broadcast. • source ('מקור'): where the contact/consent came from (e.g. 'webs…

Generate a distributable fill link for a document template. A template has no single static link (each customer fills their own copy), so this creates a fill-only instance and returns its public /form/ URL to share with the customer. Optionally pre-fill variables via contactPhone/leadId/variables.

Create an email marketing campaign. Content: either a saved templateId, or inline subject+body. Audience: a CRM segment via contactFilters ({ filters:[…], logic:'AND' }) OR an explicit excelRecipients list ([{ email, name, variables }]). Pass run=true to create AND send immediately in one call. Sends on the same durable, resumable engine as the app (safe for large lists, no duplicates).

Create a bot that auto-replies the moment a new lead arrives from a Facebook/Meta lead form. Provide a connectionId (from gambot_list_facebook_lead_connections) and a reply (replyTemplateName or replyText). Optionally restrict to specific formIds (from gambot_list_facebook_lead_forms; blank ⇒ any form on the page). The reply is sent to the lead's WhatsApp; lead fields are available as placeholders like {{Step_1_facebook_lead_data_full_name}}.

Create an invoice draft. invoiceData holds the invoice fields.

Create a bot that automatically replies to an incoming WhatsApp message. Trigger on specific keyword(s) (matchType 'equals' or 'contains') or on ANY incoming message (anyMessage=true). The reply is an approved template (replyTemplateName) or free text (replyText — only delivers inside the 24h service window). ── OPTIONAL ENHANCEMENTS (regular/free-text replies only — full parity with the visual Bot Builder): • contextCheck: verify the incoming reply is on-topic before advancing ('בדיקת הקשר') — pass contextPrompt to define what counts as in-context (auto-defaulted if omitted). • aiCompose: ins…

Create a CRM lead (contact created if missing, optional template send). Accepts all base lead fields plus a nested 'customFields' object. See gambot_get_lead_fields for available fields.

Create a menu bot: an opening template with quick-reply buttons that route each tap to a reply. Provide openingTemplateName and options (each button + its reply template/text). Start the menu for a contact by sending the opening template (e.g. via a campaign). Each option's free-text reply can be enhanced (Bot Builder parity): aiCompose + aiComposePrompt (Gambot AI phrases it live) and outsideHoursMessage (different text outside business hours). Add reminders[] to send follow-ups on the primary/main flow if the contact goes quiet ('תזכורות בפלואו הראשי').

Create a store order. Body holds order fields (customer, items, total…).

Create a new organization that goes STRAIGHT TO PAID — no free trial month. A payment method is MANDATORY: pass a `card` object; the card is verified with the clearing provider, its token is saved, and billing starts immediately (first charge on the next billing run). Use this when an AI agent has the customer's card and should provision a paying account in one call. Same number options and the same graceful companyInfo.timezone/country handling as gambot_create_trial_account (neither hard-fails). The raw card is sent only to the PCI-compliant clearing provider and never stored.

Build a secure hosted payment link (Tranzila) to add a card for an organization. Card data is never handled by the API — share the URL with the customer; the card token is saved on success.

Create a price quote. quoteData holds the quote fields (title, items, total, contact…).

Create a task (optionally linked to a contact via contactPhone).

Create a new WhatsApp template (submitted to Meta for approval). Name must be English, lowercase_with_underscores. Components use the full Meta shape and support: a TEXT or media (IMAGE/VIDEO/DOCUMENT) HEADER, a BODY with {{1}} variables, a FOOTER, and BUTTONS (QUICK_REPLY / URL / PHONE_NUMBER). For a media header you can either put example.header_handle on the HEADER component yourself (upload it first with gambot_upload_template_media), or simply pass headerMediaUrl (a public URL) and let Gambot upload it and inject the handle. ── SMART GUIDANCE — Gambot enriches your template automatically,…

Create a bot that reacts when a contact taps a quick-reply BUTTON on a template you sent (e.g. after a campaign). For each button give the reply (template or text) — perfect for 'when they click X, send Y'. The button title must match the template's button exactly.

Create a new FREE-TRIAL organization + first user (no card required). Login credentials (temp password) are emailed & WhatsApp'd to the contact. WhatsApp/number options: useFreeNumber (Meta test number) · useCoexisting (existing WhatsApp Business number in simInfo.simNumberEntered) · BYO SIM (the customer's own number in simInfo.simNumberEntered) · Buy a SIM from us (simInfo.purchaseInTwilio=true + simInfo.selectedSimNumber from gambot_search_available_numbers). GLOBAL: send companyInfo.timezone (IANA) and companyInfo.country (ISO-3166 alpha-2) — they drive scheduling and locale. Neither hard-…

Create an organization user (team member). Sends a welcome email + WhatsApp invite.

Delete a bot/automation by id.

Delete a campaign by id.

Permanently delete an organization user (removes both the auth account and the profile). This is irreversible — prefer gambot_disable_user to just deactivate access.

Disable event forwarding (stop POSTing events to the registered URL). The URL/settings are kept on file, so re-enabling later is a single gambot_register_webhook call.

Deploy a WHOLE bot in one call — the way the Bot Builder does it — instead of wiring pieces separately. It creates, in order: (1) the MAIN bot, (2) its ACTIVATOR (מפעיל — the trigger that starts it), and (3) the HUMAN-INTERVENTION CANCEL (ביטול בוט בהתערבות אנושית — stops the bot the instant a human agent replies), all linked by one sourceFlowId so they turn on/off together. botType 'menu' = an opening template with quick-reply buttons routed to replies (needs openingTemplateName + options; the activator SENDS that opening template to start the bot). botType 'keyword' = reply to a keyword/any …

Disable a user (status = inactive).

Enable a user (status = active).

Complete Meta Embedded Signup by exchanging the authorization code returned by the Facebook popup. Registers the WABA, subscribes webhooks and registers the phone number.

Generate a unique organization name from a company name + tax id (adds a suffix if taken).

Get one Gambot AI brain with its full configuration (purpose, tone, instructions, language, Q&A).

Get a single bot/automation with its full step definition (trigger + actions).

Return every botomation deployed together with this one (they share a sourceFlowId): the main bot plus its activator (the trigger, מפעיל), the human-intervention cancel (ביטול בוט בהתערבות אנושית), the Gambot AI answerer and any return-to-menu helper. Use this to see the WHOLE bot before turning it on/off. If the bot has no sourceFlowId, returns just that bot.

Get a single campaign by id.

Get the run results/report for a campaign (sent/delivered/read/replies/clicks).

Get a single case by id.

Get case (פנייה) field definitions: { baseFields, customFields }. Custom case values are stored under a nested 'customFields' map — pass them the same way on create/update.

Fetch a contact by phone number. The response carries the contact's MARKETING-CONSENT status: • consent=true → opted-in to marketing ('הסכמה לדיוור'); consent=false → opted-out/unsubscribed ('ביקש/ה הסרה', auto-excluded from broadcasts); consent=null → unknown/never set (still mailable). • isSpam=true → marked as spam/blocked (also auto-excluded). It also returns the contact's tags (`keys`), conversation status (`lastConversationStatus`: Open/In Process/Closed) and category (`lastConversationCategory`). Use gambot_set_contact_consent to opt a contact in/out, and gambot_mark_contact_spam to fla…

Get contact field definitions (base + custom/dynamic). Contacts store custom values as top-level keys — pass them via 'customFields' on create/update.

Read the full message HISTORY (content) of ONE conversation, identified by the contact's phone, newest-first and paginated with before/after cursors. Use this to see everything said with a specific customer. For just the LIST of conversations/contacts (no content) use gambot_list_conversations; for message content across ALL conversations in a period use gambot_analytics_transcript.

Message-response SLA status for ONE conversation: is the customer currently waiting for a reply, for how many minutes, and at what level (ok/warn/breach). Returns { phone, name, lastMessageDirection, lastMessageTime, lastConversationStatus, waiting, waitingMinutes, level, ownerId, ownerName, config }.

Get a single document template.

Get fill-only submissions generated from a document template.

Get a single email campaign by id.

Read the notes (הערות) attached to a single record. entityType is 'contact', 'lead' or 'case': for 'contact' pass the contact's phone number as entityId; for 'lead'/'case' pass the record id. By default this follows the organization's 'Sync Notes Between Entities' setting (ON by default): a contact also returns the notes written on its leads and cases, and a lead/case also returns its contact's notes — exactly what the user sees in the app's timeline. Pass includeRelated=false to get ONLY the notes stored on that exact record. Returns the notes newest-first (each with id, note, createdOn, crea…

Get a single web form definition.

Get the stable public shareable link for a web form. Distribute it to customers via WhatsApp/email/SMS/QR; all submissions land in the form's submissions.

Get submissions (results) for a web form.

Get a single invoice by id.

Get a single lead by id.

Get lead field definitions: { baseFields, customFields }. Custom lead values are stored under a nested 'customFields' map — pass them the same way on create/update.

Check whether a message you sent was delivered. Pass the messageId returned by gambot_send_text / gambot_send_template (or per recipient from a campaign send) and, for a fast exact lookup, the recipient's phone. Returns { messageId, phone, status (sent|delivered|read|failed), time, errorMessage? }. Use it as the final step of 'send a first test message' and whenever a user says 'I don't see the message arrived'. If status=failed with Meta error 131042 the response carries a paymentIssue block: the WhatsApp Business API payment method is SEPARATE from the Meta Ads one — tell the user to add one…

Check where an organization is in onboarding: whether the account exists, a card is on file, and WhatsApp (WABA) is connected. Use this to POLL after create-trial (Meta Embedded Signup finishes in the browser, not in the agent). Returns { accountCreated, cardOnFile, wabaConnected, status (not_found|account_created|connected), wabaConnectUrl, paymentUrl, nextStep }. Public — works without a token.

Get a single order by id.

Get a single quote by id.

Get a single e-signature document, including its signing results.

Get the signing link(s) to distribute for an existing signature document (one per signer). Share with signers via WhatsApp/email/SMS.

Get a single task by id.

Get a single template by id, including Meta approval status.

Return the list of contact phone numbers for a TEMPLATE, segmented by how each contact interacted with a button — measured ACROSS ALL SEND SOURCES (bot flows, campaigns/broadcasts, manual agent sends, and the API/MCP). THIS is the tool for 'send to everyone who clicked button X on template T', 'who received T but never pressed X', or 'who did we send T to'. It unifies URL/CTA button clicks (tracked links) AND quick-reply button replies (the common bot case), so you don't have to know which send channel or button type was used. modes: 'clicked' = pressed the button; 'not_clicked' = received the…

Get the dynamic variables of a template.

Get a single payment transaction by id (Firestore document id or the provider transactionId), including the full amount breakdown (amount, amountBeforeVat, vatInclusive, discount), status, customer details, linked record and items[].

Get a single user by id.

Get the hosted page URL where the customer completes Meta Embedded Signup (the Facebook popup) to connect their WhatsApp Business account. REQUIRES AN EXISTING ACCOUNT: call gambot_create_trial_account FIRST (no key/form needed) and pass the exact organizationName it returned — never invent one (a non-existent organization is refused with ORGANIZATION_NOT_FOUND). The create call already returns wabaConnectUrl, so you normally don't need this tool right after creating.

Return the organization's current event-forwarding webhook: whether it's enabled, the destination url, whether an auth header is set, and which event types are forwarded.

Issue an invoice — locks it and assigns the official document number.

List the organization's Gambot AI 'brains' (how the AI answers: purpose, tone, language, Q&A count). Most orgs already have one auto-built from their website at signup — find it here before creating a new one. Pair a brain with its botomation via gambot_list_bots (role 'gambot_ai').

List the organization's bots & chat automations (botomations). Pass botsOnly=true for only the visual menu/AI bots. Each item includes role (main_bot | activator | gambot_ai | human_intervention_cancel | return_to_menu | automation), triggerKind, sourceFlowId and linkedBotomationId — botomations sharing a sourceFlowId form ONE deployed bot 'package' (main bot + activator + human-intervention cancel + Gambot AI).

List calendar events in a date range from a connected Google/Microsoft calendar (Settings → Connections). Pass provider ('google'/'microsoft' or a connection id; blank ⇒ first connected calendar) and an optional startDate/endDate (ISO-8601; default = current month).

List all broadcast campaigns for the organization.

List cases (פניות / support tickets) ranked by their per-stage SLA — i.e. cases that have sat in their current stage longer than the stage's target (or are about to). Use this to answer 'which cases breached SLA / are at risk / are overdue'. 'breached' = past the stage deadline; 'at_risk' = within the last 20% of the allotted time; 'ok' = within target; 'none' = the current stage has no SLA; 'resolved' = closed/resolved (clock stopped). Deadlines are business-hours-aware when enabled. status: open (default = breached+at_risk) | all | breached | at_risk | ok | none | resolved. Returns { status,…

List cases (paginated).

List the organization's connected integrations (the same as Settings → Connections): email & calendar OAuth accounts (Google/Microsoft), Facebook/Meta lead-ads pages, shop/CRM links, plus the org's WhatsApp numbers. Only non-secret metadata is returned (ids, providers, status, account email). Use a connection's id as the connectionId elsewhere (e.g. gambot_list_facebook_lead_forms, gambot_create_facebook_lead_bot) and its provider ('google'/'microsoft') to pick a mailbox/calendar.

List or SEARCH the org's contacts directory (all contacts — CRM + chat), paginated and ordered by most-recent activity. THIS is the tool for 'who are my contacts', 'find the contact named/phoned/emailed X', 'contacts tagged VIP', 'contacts with conversation status Open', 'contacts owned by agent Y'. Each item: phoneNumber, name, email, tags, conversationStatus (Open/In Process/Closed), conversationCategory, ownerId, ownerName, consent, isSpam, isCtwa, lastMessage (preview), lastMessageTime, createdOn. The response also includes a `summary` aggregated over the WHOLE filtered set (not just the c…

List the organization's conversation CATEGORIES (labels). A contact has AT MOST ONE category (lastConversationCategory) — a single classification for routing/pipeline, unlike tags which are many-to-many. Use before gambot_set_contact_category.

List WhatsApp conversations ranked by how long the customer has been WAITING for a reply (the message-response / chat SLA). The clock starts at the customer's last inbound message and stops on ANY reply (human or bot). Levels come from the org's settings: 'warn' (amber) and 'breach' (red), and — when business hours are enabled — only working time is counted. Use this to answer 'who is waiting / which chats breached SLA / who hasn't been answered'. level: open (default = warn+breach, the actionable ones) | all | ok | warn | breach. Returns { level, config:{ warnMinutes, breachMinutes, statuses,…

List the org's conversations = CONTACTS, ordered by most recent message. This returns WHO you've been talking to with per-contact METADATA only — name, phone, last-message time and a short last-message preview, plus status/tags/owner. It does NOT return the message history/content. To read the messages of ONE conversation use gambot_get_conversation_messages; to read message CONTENT across ALL conversations for a period (e.g. 'today') use gambot_analytics_transcript.

List the contacts that were created from a Click-to-WhatsApp (CTWA) ad / Meta referral — i.e. people who messaged the business by tapping an ad on Facebook/Instagram — each enriched with the originating ad info. Filter by a single ad (adId = referralSourceId), by sourceType ('ad' | 'post'), and/or a creation date range (dateFrom/dateTo, yyyy-MM-dd). Paginated. Each item includes: phoneNumber, name, email, ownerId, ownerName, createdOn, keys, and a 'ctwa' object { adId, sourceType, headline, body, sourceUrl, platform, ctwaClid }. Use gambot_analytics_ctwa for aggregate CTWA performance and the …

List document templates.

List all email marketing campaigns for the organization.

List the organization's connected Facebook/Meta Lead Ads pages. Each item's connectionId is what you pass to gambot_list_facebook_lead_forms and gambot_create_facebook_lead_bot.

List the leadgen forms of a connected Facebook page. Pass a connectionId (from gambot_list_facebook_lead_connections; blank ⇒ the org's first Facebook Lead Ads connection). Returns [{ id, name, status }].

List web forms.

List invoices (paginated).

List leads (paginated).

Read the human-written notes (הערות) from across the CRM — the same feed as the in-app 'Notes Hub'. Aggregates notes attached to contacts (from the chat timeline), leads and cases (פניות). Filter by source ('contact' | 'lead' | 'case'), a date range (dateFrom/dateTo, yyyy-MM-dd; defaults to the last 30 days), the author (userId), or a free-text search inside the note body. Paginated. Each item includes: note, entityType, entityId, contactId, contactName, entityName, createdOn, createdById, createdByName. Use gambot_get_entity_notes to read the notes of ONE specific contact/lead/case.

List the organization's connected WhatsApp SENDER numbers. Use this in a multi-number org to discover which line you can send FROM: pass the returned `phoneNumberId` (or `displayNumber`) as `from` on gambot_send_text / gambot_send_template, or as `fromNumberId` on the campaign tools. When omitted, the org's PRIMARY number is used. Returns { count, items:[ { phoneNumberId, displayNumber, label, isPrimary, status, defaultTemplateId } ] }.

List orders (optionally filtered by status / store / date range).

List price quotes (paginated).

List scheduled campaigns that are waiting to run.

List the concrete SCHEDULED RUNS (occurrences) of a scheduled/recurring/block campaign — every future date it will fire, with each occurrence's runAt, status, and (for split campaigns) the recipient batch range. Works for ALL scheduled types: a one-time scheduled campaign (single occurrence), a recurring campaign (e.g. 'every Tuesday'), auto-split blocks, and manually-timed blocks. Use this FIRST to get the exact runAt values, then pass one to gambot_skip_scheduled_run (turn a single date off) or gambot_reschedule_scheduled_run (move a date). If `runs` is empty the campaign is pattern-only (si…

List e-signature documents (newest first).

List the organization's contact TAGS (aka keys/lists) — the many-to-many labels a contact can carry and that campaigns target via the `keys` audience filter. Use this to resolve/validate a tag name before tagging or broadcasting. (Tags are different from a conversation CATEGORY, which is a single label per contact — see gambot_list_conversation_categories.)

List tasks for the organization.

List all WhatsApp templates for the organization.

List payment / clearing transactions (עסקאות), newest first. Use this to answer 'what did this customer pay/owe' or to give a transaction breakdown. Each item includes amount, status (pending/paid/failed), customerName, customerPhone, description, entityType (quote/invoice/order/lead/case…), vatInclusive, amountBeforeVat, provider, paymentUrl, items[] and createdAt/paidAt. Filter by contactPhone, status or entityType.

List organization users (excluding system bots).

Mark a contact as spam (isSpam=true) or clear the flag (isSpam=false). Marking as spam also opts the contact out of marketing (consent=false), so they are excluded from broadcasts and hidden from the active chat list. Unmarking spam does NOT automatically restore marketing consent — use gambot_set_contact_consent for that.

Register (or update) a WEBHOOK so Gambot POSTs every matching WhatsApp event to your server as it happens. Each delivery is a JSON 'envelope': { type, event, types[], organization, receivedAt, meta_obj } where meta_obj is Meta's raw payload, plus request headers X-Gambot-Organization and X-Gambot-Event. Provide the destination `url` (https recommended); optionally an `authHeader` we send verbatim as the Authorization header on every call, and `events` toggles to choose which event types to receive (all on by default). This is the programmatic equivalent of Settings → Event Forwarding, so it al…

MOVE a single occurrence of a scheduled/recurring campaign to a new date/time, leaving every other occurrence untouched (e.g. 'push this Tuesday's send to Wednesday'). Pass `runAt` (the existing occurrence from gambot_list_scheduled_runs, matched to the minute) and `newRunAt` (the new datetime). The campaign's timezone is preserved.

Run an existing (saved) campaign by id now (resolves recipients and executes).

Run (send) a saved email campaign now. Uses the durable, resumable engine — safe for large audiences, no duplicates.

List phone numbers available to purchase for a country (via Twilio), so you can pick one to buy as the account's SIM/number. Pass the chosen phoneNumber to gambot_create_trial_account / gambot_create_paid_account as simInfo.selectedSimNumber with simInfo.purchaseInTwilio=true.

IMMEDIATE 'run to a group' — send an ad-hoc broadcast NOW to a tag/segment/phone-list, WITHOUT saving a campaign. Use this ONLY for an immediate one-off send to CONTACTS. Do NOT use it for: a schedule (once or recurring) or an Excel/CSV sheet — those are ALWAYS saved as a campaign (use gambot_create_campaign for scheduled/recurring or CRM-segment campaigns, and gambot_send_campaign_from_excel for a sheet). TWO things are required: (1) an AUDIENCE and (2) the MESSAGE. AUDIENCE — pick ONE: `keys` (send to everyone with these tags/lists, e.g. keys:['מכבי חיפה'] — the most common request 'send to …

Broadcast a WhatsApp TEMPLATE to everyone in an Excel/CSV the user gave you — the easiest way to do a mail-merge blast. An Excel/CSV broadcast is ALWAYS saved as a campaign (this matches the Gambot web app — there is no unsaved Excel send). If you send it immediately, this tool SAVES the campaign and then RUNS it right away; if you schedule it, it just saves it and the scheduler runs it. YOU (the agent) read the sheet and pass: `rows` (one object per row, keyed by the column header), `phoneColumn` (which column holds the phone), and the variable mapping — either `variableColumns` (ordered: 1st…

Send a single email over a connected Google/Microsoft mailbox (Settings → Connections). Provide to, subject and body. Set isHtml=false for plain text. Optionally cc/bcc and a provider ('google'/'microsoft' or a connection id; blank ⇒ first available).

Send a 6-digit verification code to the customer's email AND WhatsApp. Public (no token). Required ONLY before creating a self-serve account that BUYS a phone number (proves the customer owns the email/phone, so we don't buy numbers for fake accounts). Returns { verificationId } — collect the code from the customer, then call gambot_verify_onboarding_code. Free number / co-existence / bring-your-own do NOT need this.

Send an approved WhatsApp template with variables to ONE recipient. Can initiate a conversation even outside the 24-hour window. Required: to (E.164) and templateId (id or name from gambot_list_templates — it must be APPROVED by Meta). Pass variables[] in body order; if the template has variables, call gambot_get_template_variables first and ask the user for values you do not have. Returns { success, data:{ messageId } } — verify delivery with gambot_get_message_status. Likely errors: TEMPLATE_NOT_APPROVED / TEMPLATE_NOT_FOUND (→ gambot_list_templates), MISSING_TEMPLATE_VARIABLES (→ gambot_get…

Send a free-text WhatsApp message to ONE recipient. Works ONLY inside the 24-hour customer-service window (the contact messaged you in the last 24h). If the window is CLOSED this returns a 409 'conversation_closed' error — do NOT retry free text; send an approved template with gambot_send_template instead. If unsure whether the conversation is open, call gambot_check_window first. Required: to (E.164) and text. Returns { success, data:{ messageId } } — the messageId is how you VERIFY delivery afterwards with gambot_get_message_status. Likely errors: CONVERSATION_WINDOW_CLOSED (→ gambot_send_te…

Turn a bot on (active) or off (inactive). By default this toggles ONE botomation. Set includePackage=true to toggle the WHOLE bot — every botomation sharing its sourceFlowId (the main bot + its activator/trigger + the human-intervention cancel + the Gambot AI answerer) — which is what a user usually means by 'turn the bot on/off'. Use gambot_get_bot_package first if you're unsure what will be affected.

Set a contact's conversation CATEGORY (single label). Pass an empty string to clear it. See gambot_list_conversation_categories for the available labels. This is distinct from tags (use gambot_update_contact_tags for many-to-many tags).

Set a contact's marketing-consent status ('הסכמה לדיוור'). consent=true opts the contact IN (mailable); consent=false opts them OUT / unsubscribes them — after which they are automatically excluded from ALL future broadcasts (campaigns). Use this to record an opt-out the customer requested off-platform (phone call, email, web form), or to re-enable a contact who gave fresh consent. Recipients can also opt out themselves by replying הסר/stop/unsubscribe. Optionally pass a 'source' note for the audit trail.

Set a contact's conversation STATUS — one of 'Open', 'In Process', 'Closed'. This is the same status the chat sidebar and status filters use (setting it also syncs the underlying conversation). Use to close/reopen a conversation or move it into processing from an external workflow.

START HERE when a user says things like "add WhatsApp to my app", "I need the official WhatsApp Business API" or "connect WhatsApp". Gambot is the OFFICIAL WhatsApp Business (Cloud) API through a Meta Business Solution Provider — not WhatsApp Web / QR-session automation. This tool only READS state and tells you the single next step and WHO must do it. It works with or without an API token: without a token it follows the public onboarding road (account → Meta Embedded Signup in a browser → API token); with a token it verifies the sender number, approved templates and webhook. Returns { state, s…

Cancel a SINGLE upcoming occurrence of a scheduled/recurring campaign (e.g. 'skip this coming Tuesday but keep the weekly schedule'), or cancel ALL upcoming occurrences at once. Pass `runAt` (an exact value from gambot_list_scheduled_runs, matched to the minute) to skip just that date, OR scope='upcoming' to cancel every future run (already-sent runs are always kept). The rest of the schedule is re-armed automatically and untouched. To remove the whole campaign entirely use gambot_delete_campaign.

Send a single-recipient TEST of a template or free-text message. Great for previewing before a full broadcast.

Fire a synthetic sample 'incoming_message' envelope (flagged test:true) at the registered webhook URL — or at an override `url` passed here — and return the delivery result: { delivered, statusCode, durationMs, responsePreview }. Use this to confirm your endpoint actually receives Gambot's calls. The attempt is recorded in the delivery log.

Update/upgrade an existing Gambot AI brain. PATCH semantics — only the fields you pass change; everything else (including learned Q&A, style examples and the knowledge-base file) is kept. Use this to refine the auto-built AI: sharpen its purpose/instructions, set the tone or language, add Q&A, or toggle escalate-to-human.

Update a campaign (send the full campaign object).

Update a case — only the provided fields are changed. Accepts base fields plus a nested 'customFields' object (merged with existing custom values).

Update a contact — only the provided fields are changed. Custom fields go under 'customFields'.

Add and/or remove TAGS on ONE contact, MERGING with its existing tags (safe — it never wipes the others). Provide `add` and/or `remove` (arrays). New tags are auto-created org-wide. To overwrite the entire tag list instead, use gambot_update_contact with `keys`.

Update invoice fields (blocked once issued/locked).

Update a lead — only the provided fields are changed. Accepts any base field plus a nested 'customFields' object (merged with existing custom values).

Replace the text of an existing note (הערה). Pass the note's id plus the entityType/entityId of the record the note is STORED on — both are returned with every note by gambot_get_entity_notes / gambot_add_note (a lead note read via its contact still reports the lead as its origin). Only user notes can be edited (never system events). The edit is stamped with the update time and 'Gambot MCP'. Returns { id, entityType, entityId, note, updatedOn }.

Update order fields (merge).

Update quote fields (partial).

Update a task — only the provided fields are changed.

Update user fields — only the provided ones are changed.

Upload a public media URL (image/video/document) to Meta and get a reusable header_handle for a template's media HEADER. Use the returned headerHandle inside a HEADER component: {type:'HEADER',format:'IMAGE',example:{header_handle:[headerHandle]}}.

Verify the 6-digit code the customer received (from gambot_send_onboarding_verification). Public (no token). On success returns { verified:true }; pass the same verificationId to gambot_create_trial_account to create an account that buys a phone number.