Kanal

Creates a dynamic audience segment from conditions (format: see get_segment_capabilities; check the count first with preview_segment). The segment is calculated asynchronously right after creation and then kept up to date; use list_segments_and_groups to read its contact count. Fails if a segment with the same name already exists.

create_segment

Creates a magic link: a short getkanal.com link (short_url, generated by Kanal, not choosable) that opens a WhatsApp conversation with the team number and pre_filled_message already typed; the customer only taps send. It is the entry point of a kanal_v2_keyword flow: write a pre_filled_message that contains the flow keyword (or is exactly the keyword for a match keyword) and check matching_automations in the answer. Give the user short_url to publish (bio, QR code, ad, email). Deleting a link is done in Kanal; to retire one from MCP, deactivate it with update_magic_link.

create_magic_link

Creates an empty static group (a manually managed contact list, usable as a campaign audience). Fill it with add_contacts_to_group. Fails if a group with the same name already exists. Optional color as a hex code (default #3B82F6).

create_group

Creates an INACTIVE automation draft with its trigger node pre-configured; then add_nodes with after = trigger_node_id. Trigger types and their trigger_config: see get_automation_capabilities (welcome/keyword flows → kanal_v2_keyword with keywords; post-purchase → shopify_order_created; abandoned cart → shopify_abandoned_checkout; shipping → shopify_shipment_updated). Several automations may share a trigger; the result lists the active ones already on it so you can tell the user. Abandoned-checkout flows stop by themselves as soon as the customer orders: never add a 'has ordered' condition. Fails if an automation with the same name exists. Activation is a separate confirmed step (prepare_automation_activation).

create_automation

Turns an automation OFF: new trigger events are ignored from then on. Side effect to tell the user before calling: a wait that expires or a reply received while the flow is off ends the contact's session; the others resume on reactivation. The result reports contacts_waiting = {total, waiting_for_delay: {total, by_node: {wait node id: contacts}}, waiting_for_reply: contacts asked a question (wa-input) who have not answered yet}; contacts sent buttons they have not tapped are not counted. Idempotent: an inactive automation is left as it is.

deactivate_automation

Describes everything the flow tools accept: trigger types (with their trigger_config), node types available through MCP with their fields, default output handle and branch handles, the conditions DSL, the variables syntax, the campaign rules (a campaign must send an approved template before any session message) and worked examples. Call it once before create_automation / create_campaign / add_nodes. Pass node_type for one type in full.

get_automation_capabilities

Discover what query_stats can do: available targets, metrics, filterable fields and periods. Call this before your first query_stats.

get_stats_capabilities

Describes the conditions format accepted by preview_segment and create_segment: condition types (contact_events, properties, group_membership), events, operators, time intervals and their options, AND/OR semantics, with examples. Call this before building your first segment. Segments target WhatsApp-reachable contacts only — an Instagram-only profile is never part of one; use a group to collect those.

get_segment_capabilities

Estimates what sending a flow campaign to its current audience would cost in Meta conversation fees (EUR): cheapest and most expensive path through the flow, per-contact maximum, and the templates involved with their approval status. Zero until set_campaign_audience has been called. Read-only.

get_campaign_cost_estimate

Returns the connected Kanal team: name, subscription plan, the messaging channels it has connected — WhatsApp phone numbers (with Meta quality rating) and Instagram accounts (username, connected/disconnected) — the attribution settings (basis, window, timezone) that all metric tools use, the quiet hours (business hours + the out-of-hours auto-reply switch), the UTM tracking of the links and the opt-out keyword detection. A phone number with whatsapp_connected=false is an empty channel line created at signup, not a broken number: the team never finished WhatsApp onboarding, and the line may still carry an Instagram account. Call this first to understand the account context, in particular which channels exist before reading the inbox. Credits, balance and AI consumption are in get_billing.

get_account

Daily time series of one metric (revenue, orders, conversations, cost, delivered, read, roas, conversion_rate) over a period, using the team attribution settings. Ideal to analyse trends or build charts. For weekly or monthly trends, aggregate the daily points (or use query_stats with target=attribution.* and group_by=week|month).

get_performance_chart

Global WhatsApp marketing performance for the team over a period: attributed revenue, cost, cost_marketing, ROAS, orders, engagement funnel (delivered/read/interacted/converted), revenue split by mechanism (campaigns vs automations vs AI), and top campaigns/automations. cost = spend across ALL WhatsApp conversation categories, marketing AND utility (the ROAS denominator — marketing is routinely routed as utility for Meta pricing); cost_marketing = the marketing-only slice of that spend. Uses the team's configured attribution window and basis (see get_account). Data may lag ~30 minutes.

get_performance_overview

Money + engagement stats for a single automation flow (attributed revenue, cost, cost_marketing, ROAS, orders, delivered/read/clicked) over a period, plus a per-node breakdown, using the team attribution settings. cost = spend across ALL WhatsApp conversation categories, marketing AND utility (the ROAS denominator — marketing is routinely routed as utility for Meta pricing); cost_marketing = the marketing-only slice of that spend. Find automation ids with list_automations.

get_automation_stats

Money + engagement stats for a single campaign (attributed revenue, cost, cost_marketing, ROAS, orders, delivered/read/clicked) over a period, using the team attribution settings. cost = spend across ALL WhatsApp conversation categories, marketing AND utility (the ROAS denominator — marketing is routinely routed as utility for Meta pricing); cost_marketing = the marketing-only slice of that spend. Find campaign ids with list_campaigns.

get_campaign_stats

Recommendations written by the Kanal team: how to write WhatsApp templates that get approved and read, campaign timing and audience rules, flow patterns that convert, opt-in and compliance. Read them before designing a campaign, a flow or a template, and follow them unless the user asks otherwise. Categories: whatsapp, templates, campaigns, automations, audience, kanal.

get_best_practices

Lists the Kanal teams (brands, shops) this connection can act on: id, name, MCP access (full = read and write, read = read only, none = plan without MCP) and whether it is the team used when a call names none. An agency or a Kanal staff member reaches several teams: call this first, pass the team id as team_id on every other call, and say which team you are working on before any change. Kanal staff reach every team: search them with query (name or id).

list_teams

Lists the team's WhatsApp campaigns, most recent first: id, name, status (CREATED, SENDING, SCHEDULED, PAUSED, SENDED), scheduled date. Use the id with get_campaign_stats. Optional status filter and limit (default 25, max 100).

list_campaigns

Lists the team's WhatsApp message templates with their Meta approval status (DRAFT, PENDING, APPROVED, REJECTED) — a template must be APPROVED before it can be sent in a campaign. Also returns category (MARKETING, UTILITY, AUTHENTICATION) and language. Use it to check approval status or to find a template the user names, then get_template for its content (text, media, buttons); for a new flow, write the message with create_template instead of picking an unrelated approved template.

list_templates

Lists the team's audience building blocks with contact counts: segments (dynamic, condition-based) and groups (static lists). Both can be used as a campaign audience. Counts are WhatsApp-reachable contacts, exactly like the Kanal UI: a group can also hold Instagram-only profiles, which are not counted here and are skipped when a WhatsApp campaign is sent to that group.

list_segments_and_groups

Lists the team's automations (visual flows): id, name, trigger type (kanal_keyword, shopify_order_created, shopify_abandoned_checkout…), active status. Use the id with get_automation_stats. Optional is_active filter and limit (default 25, max 100). `system` marks the flows Kanal manages from the team settings (quiet_hours: the out-of-hours auto-reply, see get_account; opt_out): their active state follows the setting, not a toggle.

list_automations

Lists the team's inbox conversations across channels, most recent first: contact id, name, the channels that conversation uses, phone number and/or Instagram username (shown in full — the merchant owns these conversations and the inbox permission was granted separately at connect time), the last message (preview, channel, direction in/out, date), an unread flag, and whether the conversation is flagged for a human. Read-only. Note: "all" is broader than the in-app inbox default — it includes closed conversations and ones the business has not replied to yet. Optional channel (all, whatsapp, instagram; default all), filter (all, unread, human_needed; default all) and limit (default 20, max 50). Unread means: manually marked unread, or the last WhatsApp message is an unanswered inbound one; on Instagram there is no inbound read receipt, so it means the last Instagram message is an inbound one (the business has not replied since). Pass a contact id to get_conversation to read the full thread.

list_conversations

Lists the magic links (Settings > Magic links): short links that open WhatsApp with a pre-filled message, used in bios, QR codes, ads and emails to start a keyword flow. For each: id, name, slug, pre_filled_message, is_active, click_count, short_url (the link to publish), whatsapp_url (the wa.me target) and matching_automations, the flows whose keyword the message triggers (with is_active: an inactive flow answers nothing).

list_magic_links

Returns the {{...}} tokens a flow can render: contact fields ({{recipient.name}}…), trigger payload fields mapped by Kanal ({{variables.shopify_abandoned_checkout_url}}…), and values produced upstream (wa-input answers, vouchers, api-call mappings) when after_node_id is given. Any other token is refused when the node is written. Call it before writing a message that uses variables.

get_available_variables

Runs every pre-send check on a flow campaign (audience set, templates submitted, flow valid), prices it, and returns a summary with a confirmation_token valid 10 minutes. NOTHING IS SENT OR SCHEDULED by this call. Show the summary (audience, date, cost) to the user and only call confirm_campaign_send after they explicitly confirm, or when they click Confirm on the card. scheduled_at is "now" or an ISO 8601 date; without a UTC offset it is read in `timezone` (default: the connected user's timezone).

prepare_campaign_send

Runs every check the activation applies (graph valid, every node configured, templates submitted to Meta, 24h window, plan, Instagram ad welcome message) and returns a summary with a confirmation_token valid 10 minutes. NOTHING IS ACTIVATED by this call. Show the summary (trigger, warnings, other active automations on the same trigger) to the user, and only call confirm_automation_activation after their explicit yes.

prepare_automation_activation

Free-form stats query engine (the same one Kanal's built-in assistant uses). Call get_stats_capabilities first to discover available targets, metrics, filters and periods, then query e.g. target=attribution.global or attribution.top_campaigns. group_by day/week/month on attribution targets returns a revenue time series (data[] of {period, ...}); group_by=hour is rejected (attribution is daily) and top_* stays a ranked list. Results follow the team's attribution settings and match the Kanal dashboard.

query_stats

Returns the full content of one template from list_templates: header (text, or the media URL), body text with its {{n}} placeholders and the variables they map to, footer, quick replies, URL buttons (and the button types the MCP cannot write), carousel cards. Use it to show a template to the user, to check whether an existing one already says what a flow needs, or to recreate it: `recreatable` says whether create_template can take this content as is, and `unsupported_by_create_template` lists what it cannot. `category` is the category submitted to Meta (Meta may have reclassified it) and `language` defaults to fr on old templates.

get_template

Returns the most recent messages of one conversation in chronological order (oldest first), with a contact header (name, phone number and/or Instagram username shown in full, channels, opt-in status). When the contact talks on both channels the two threads are merged into one timeline; each message carries its channel. Each message has: direction (in/out), type, a text body (media and interactive replies collapse to a bracketed placeholder like "[image]" or "[button: Yes]", a deleted Instagram message to "[deleted message]"), who sent it (source: on WhatsApp human = a team member from the inbox, ai = the Kanal AI agent, automation = a flow (with automation_id), campaign = a campaign blast or its follow-ups (with campaign_id), integration = a helpdesk relay such as Gorgias or this connector (via: gorgias, crisp, mcp…); on Instagram, kanal or instagram_app for messages the team sent from Meta's own apps), an Instagram reaction emoji when there is one, and the timestamp. To answer, use send_message. Find contact ids with list_conversations. Args: contact_id (required), channel (all, whatsapp, instagram; default all), limit (default 50, max 100).

get_conversation

Returns an automation (or the flow behind a campaign): name, trigger, status, graph_version, every node with its data, label, output handles and outgoing edges, and the builder_url. Use it before update_node / connect_nodes and after any error to see the current state.

get_automation_graph

Removes one edge by id (ids come from add_nodes, connect_nodes and get_automation_graph). The nodes stay in place.

remove_edge

Removes a node and every edge attached to it. Trigger nodes cannot be removed. Downstream nodes stay in the graph, disconnected — reconnect them with connect_nodes or remove them too (orphaned_node_ids lists them).

remove_node

Removes contacts from a static group (the contacts themselves are kept). Idempotent: contacts not in the group are reported as not_in_group, ids that do not belong to the team as unknown_contact_ids. Returns the number actually removed.

remove_contacts_from_group

Changes the name, the pre_filled_message or is_active of a magic link; omitted fields are kept. The short_url never changes, so a published QR code or bio link keeps working after the message is rewritten. is_active=false retires a link without deleting it (the URL shows an error page instead of opening WhatsApp): use it instead of deleting when the link may already be printed or posted. Check matching_automations in the answer after changing the message.

update_magic_link

Sends one text message to a contact, as a reply in the inbox (WhatsApp or Instagram). Session message only: WhatsApp needs the contact to have written in the last 24h; when that window is closed and the number has an approved invitation template, the message is queued and the contact receives an invitation, the text leaves when they answer (status queued). Instagram needs the window open, nothing is queued. get_conversation on this contact is REQUIRED first (within 30 minutes, and again if the contact wrote since): the call is refused otherwise. Write in the contact's language, and only send what the user asked to send: this reaches a real customer and cannot be unsent. Args: contact_id, text (max 1000 characters), channel (whatsapp or instagram; required when the contact has both).

send_message

Call this when the user asks for something no Kanal tool covers (a setting, an action, a piece of data), BEFORE telling them it is not possible here. It records the request for the Kanal team and changes nothing in the account. Then answer the user honestly: say it is not available through this connector today, and point them to the Kanal app when it can be done there. Args: request (the user's words), missing (what would be needed, one sentence), category.

report_unsupported_request

Finds contacts of the team whose name, phone number or Instagram username contains the query (min 2 characters), most recently active first: contact id, name, the channels the contact is reachable on, phone number (in full, null for an Instagram-only profile), Instagram username, opt-in status. Use the ids with add_contacts_to_group, remove_contacts_from_group and set_contact_variable. Limit default 20, max 50.

search_contacts

Finds products in the team's Shopify store(s) by title or SKU fragment, live from Shopify (no query = the first products of the catalogue): product_id, title, status (ACTIVE, DRAFT, ARCHIVED), image_url, store_domain and the variants (variant_id, title, price). Use product_id as the value of a filter_on_product_ids condition (with store_domain when the team has several stores), image_url as a template header_media_url, and the price in a message. Never guess a product id: search first. Limit default 20, max 50 per store.

search_products

Progress and report of an import_contacts run: status (pending, importing, completed, failed), rows imported, skipped (invalid numbers) and duplicates. Poll every few seconds until completed.

get_contact_import_status

Sends a DRAFT template to Meta for review. IRREVERSIBLE: name, category and language are locked by Meta once submitted, and the review takes minutes to hours. Always show the user the template text and get their explicit go-ahead before calling this. Returns status PENDING; list_templates shows APPROVED / REJECTED later. A rejection keeps the template editable in Kanal.

submit_template

Changes the UTM tracking of the team: enabled (Kanal appends utm_source, utm_medium and utm_campaign to every button and CTA link it sends), utm_source and utm_medium (defaults kanal / whatsapp; an empty string goes back to the default). utm_campaign is always the campaign or flow name and cannot be set. Omitted fields are kept. Read the current state in get_account.utm_tracking first.

update_utm_tracking