Gambot WhatsApp Business API

Verify a card with the clearing provider (Tranzila) and save its token to an organization, so an AI agent with the customer's card can put a payment method on file without the hosted page. The raw card is sent only to the PCI-compliant clearing provider and never stored. For a hosted alternative (customer types the card), use gambot_create_payment_link.

WhatsApp bot / automation performance for a period: totalRuns, completedRuns, activeRuns, failedRuns, completionRate (%), uniqueContacts engaged, and a per-bot breakdown (byBot: botId, name, status, runs, completed, active, failed, uniqueContacts) sorted by run volume. Also reports botsConfigured (total/active/bots). Use for 'how are my bots doing', 'which bot ran the most', 'bot completion rate this month'. Use gambot_list_bots for the bot catalog and gambot_get_bot for one bot's full definition.

Support tickets / פניות for the period: created, closed, resolved, still-open, SLA compliance and a breakdown by stage. ('cases' is Gambot's internal name for פניות / inquiries / tickets.)

New contacts in the period, how many came from CTWA (Click-to-WhatsApp ads), and a breakdown by creation method (manual / incoming_message / api / ...).

Click-to-WhatsApp ad performance: the unique ads that drove conversations (id + headline), and how many new contacts in the period came from CTWA ads.

A day-by-day time series of inbound / outbound / AI messages across a range (default: last 30 days). Ideal for charts and trends.

Sales pipeline snapshot: open / won / lost this month, total pipeline value, and breakdowns by stage, source and user (salesByUser).

WhatsApp message volume for a period: total, incoming, outgoing, how many were sent by bots vs humans, and a per-agent breakdown (byAgent) — how many messages each user sent. Use for 'how many messages went out today', 'inbound vs outbound this month', 'who sent the most messages'.

Lifetime WhatsApp totals (total / sent / received / delivered / read / failed) plus a last-6-months trend. Cheap (served from a cached view). Use for all-time totals or a monthly trend chart; for a specific period use gambot_analytics_messages.

One-shot KPI snapshot for a period: WhatsApp message volume (incoming/outgoing + per-agent breakdown), new contacts (incl. from CTWA ads), leads (created/won/open), support tickets (פניות: created/closed/open), tasks (created/completed/open/overdue) and bots (runs/completed/active/failed/completionRate). USE THIS to answer 'how are we doing today / this month', 'how many messages did we send', 'how many new leads', etc. Set userId to scope to a single team member; omit it to get the whole org (the per-agent breakdown still shows each user).

Task KPIs: totals, open / in-progress / completed / overdue, and breakdowns by priority, category and assignee. Set userId to scope to one assignee.

Read the ACTUAL message CONTENT across ALL conversations for a time window (default: today) as a flat, time-ordered feed. Each message has: time, phone, contactName, direction (incoming=from the customer / outgoing=from the team or bot), sender (customer name, agent name, 'Gambot AI', 'Gambot MCP', …), senderId, type, messageType and text. THIS is the tool for QUALITATIVE questions about conversations — e.g. 'how did my employees reply today?', 'which customers seem upset / frustrated?', 'summarize today's chats', 'did anyone ask about prices / cancel?', 'how did agent X handle their chats?'. After calling it, analyze the returned messages yourself to answer. For pure COUNTS use gambot_analytics_messages instead (cheaper). Filter by direction, by userId (one agent's replies), or by phone (a single conversation). Returns up to `limit` most-recent messages (truncated=true means older ones were dropped — narrow the window or raise limit).

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, recommendation, defaultTemplateId }.

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 → aiCompose:{enabled:true,prompt,assignToGambotAiAfter:true} to have Gambot AI phrase it live, and businessHoursAlternative:{enabled:true,outsideHoursMessage:'...'} for a different text outside business hours. • On the botomation itself → primaryFlowSettings:{reminderEnabled:true,reminders:[{afterMinutes,message,action}]} for follow-up reminders. Prefer gambot_create_keyword_autoreply / _template_button_autoreply / _menu_bot / _deploy_bot_package for common cases — they expose contextCheck, aiCompose, outsideHoursMessage and reminders as simple params.

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' broadcast only reaches recipients whose 24h window is open — prefer a Template for cold audiences). Audience: recipientSource='Excel' + ExcelData, or ContactFilters (CRM segment), or legacy ContactsQuery. Scheduling: campaignTrigger='Scheduled' + scheduleType ('once' with runAt+timezone, or 'repeated' with interval/intervalNumber/endCondition). PENDING TEMPLATES: a SCHEDULED campaign MAY reference a template that is NOT yet approved (status PENDING) — it only needs to be APPROVED by Meta before runAt. So the flow 'send this to these people on Thursday' works as: gambot_create_template → then this tool with campaignTrigger='Scheduled' + the new template id, even while it's still pending. The response includes a non-blocking `templateStatusWarning` when the template isn't approved yet; relay it to the user (a REJECTED template will never send).

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. 'website form', 'landing page', 'phone call', 'in-store', 'imported list'). Pass it whenever known — it's the audit trail for the opt-in and is stored as both the contact's source and the consent source. To change consent later use gambot_set_contact_consent.

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: instead of a fixed replyText, let Gambot AI phrase the reply in real time from a short instruction (aiComposePrompt); sent as 'Gambot AI'. • outsideHoursMessage: send a DIFFERENT reply text outside the org's business hours. • reminders: follow-up reminders on the primary flow if the contact doesn't respond.

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, so lean on it: (1) LINK BUTTONS: whenever the message refers to a link/CTA (book, track, open, pay, view), ADD a URL button ({type:"URL",text:"...",url:"https://..."}) instead of pasting the raw link in the body — one-tap buttons convert far better. (2) CLICK TRACKING (tracking link): STATIC url-button links are auto-wrapped in a Gambot tracked short link so clicks are logged (and can fire botomations). It's ON by default for MARKETING; you always pass the REAL destination url — Gambot swaps in the tracker. Set "trackClicks":false on a URL button to keep the raw link, or "trackClicks":true to force tracking on a non-marketing template. (3) MARKETING / BROADCAST (דיוור): use category 'MARKETING' for any promotional broadcast. Its opt-out FOOTER is MANDATORY and OWNED by Gambot — DO NOT add your own FOOTER for MARKETING; Gambot adds a localized opt-out footer (Hebrew 'להסרה יש להשיב הסר', else 'Reply STOP to unsubscribe') and OVERRIDES any non-opt-out footer you passed. An existing opt-out footer or a 'הסר'/'STOP' QUICK_REPLY button is respected. The new template starts as PENDING (awaiting Meta approval). You do NOT have to wait for approval to SCHEDULE with it: you can immediately call gambot_create_campaign with campaignTrigger='Scheduled' and this template's id — it just has to be APPROVED before the scheduled runAt.

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-fails: a missing/invalid timezone is derived from country (else defaults to Asia/Jerusalem). For a paid account with a card on file (no trial) use gambot_create_paid_account instead. After creating, connect WhatsApp via the returned wabaConnectUrl or gambot_exchange_waba_token.

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 message (self-activating — its own keyword IS the activator, so no separate activator is made). Choose how the menu bot STARTS with activator.type: 'keyword'/'any_message' (a contact texts in), 'inactivity' (no message in noContactDays days), or 'campaign_lead' (a lead arrived from an ad/campaign). AI / combined bots (Gambot AI) are built in the Bot Builder app because they need a Gambot AI configuration. After deploy, toggle the whole thing with gambot_set_bot_status(includePackage=true) or inspect with gambot_get_bot_package.

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).