Ninjo

Queue mk1-tasks bootstrap for the influencer's Discord operator channel. This creates or repairs the stored Discord mapping asynchronously through mk1-tasks. The downstream bootstrap creates the role, private channel, and permanent invite when needed. Returns { status: "queued", taskId } on success.

bootstrap_discord_channel

Ownership: claim a conversation or pipeline record (subject) for the signed-in user. expectedRevision comes from get_crm_assignment (0 when nothing is assigned yet). Human claims are protected from ordinary automation.

claim_crm_ownership

Pipelines: close a pipeline record, with an optional outcome (SUCCESS or FAILURE) and closeReason, using the record's current revision. The closed record stays in history; add_crm_contact_to_pipeline starts a new cycle.

close_crm_pipeline_record

External CRM sync: map a connected Airtable account to a base and contacts table so Ninjo contacts sync there. Run refresh_crm_sync with airtableBaseId first to get table and field ids. fieldMappings needs the Ninjo contact id and first-name columns; stageFieldId must be a single-select field and monetaryValueFieldId a numeric one. Replaces any existing mapping and re-registers the Airtable webhook.

configure_crm_airtable_sync

Switch an existing GoHighLevel WhatsApp channel between GoHighLevel's official WhatsApp and an external provider (a WhatsApp QR/app integration registered inside GHL). Use this when create_messaging_channel was called with the wrong third_party_whatsapp value — the symptom is that inbound messages arrive but Ninjo's replies never send. The channel cannot simply be recreated (one WhatsApp channel per account), which is why this exists. Only applies to GoHighLevel WHATSAPP channels; Kommo and every other channel type are rejected. Returns { channel, third_party }. Check third_party, not channel: the flag lives on the connected account, so channel is byte-identical before and after — third_party is read back from the account after the write and is the only confirmation the flip landed.

set_messaging_channel_whatsapp_provider

Mint a one-time magic-link the account owner opens in a browser to authorize an integration: Instagram / Facebook, a CRM ('gohighlevel_crm', 'hubspot_crm', 'kommo_crm'), booking ('gohighlevel_booking', 'calendly') or the Google Calendar the agent books into ('google_calendar'). Connecting requires human OAuth consent at the provider — this tool cannot complete it. Hand the returned URL to the user and ask them to open it and authorize; do NOT open it yourself. The link needs no prior Studio login (it mints a short-lived, influencer-bound session on redeem), is single-use and expires after a few minutes. NEVER ask the user for an API key, token or password for these — none of them is used by this flow (in particular a GoHighLevel private-integration token is NOT needed). GoHighLevel has TWO separate integrations: 'gohighlevel_crm' (contact/opportunity sync, Studio screen automation/crm-sync) and 'gohighlevel_booking' (call tracking, Studio screen integrations/gohighlevel). Ask which one the user means instead of guessing. After the user authorizes, poll get_connection_status. Booking is NOT finished at that point — it reports pending_step:"select_calendars", so continue with list_booking_calendars + set_booking_calendars. CRM needs nothing more (pipelines/stages matter only when wiring a property action). Google Calendar ('google_calendar') is NOT booking tracking and has no calendars to select — never call list_booking_calendars / set_booking_calendars for it. It is the calendar the agent itself reads and books into (v5 agents only), one per workspace. After consent get_connection_status reports pending_step:"enable_for_agent_in_studio": finish it with set_google_calendar_agent for each agent that should book (the user can also do it in Studio at /studio/{influencer_id}/integrations/google-calendar). Then have them review the booking rules on that screen — left unset they default to Monday–Friday 9:00–18:00, 30-minute slots and a video call, which is wrong for most in-person businesses. ManyChat is not supported here: it has no OAuth. Send the user to /studio/{influencer_id}/integrations/manychat, where THEY fill in four things: the channel (WhatsApp / Instagram / Facebook), the API key, a shared webhook secret, and then they must COPY the webhook URL that screen shows them and paste it into ManyChat itself. Never ask for or echo the API key. Warn them that the last step happens inside ManyChat, so Ninjo cannot confirm it — get_connection_status only sees the first three. Returns { provider, url, expires_at }.

create_connect_link

Create a new Ninjo agent with its initial system prompt. Creates the Agent, AgentConfig, and first AgentPromptVersion atomically, with safe humanization defaults (message chunking on, MEDIUM delay split, 2–6s response delay — all overridable). Returns { agent_id, agent_config_id, prompt_version_id, completeness }. completeness is the deterministic build/wiring audit of the new agent: a fresh agent reports critical gaps by design (no terminal stop, not linked to a connected account) — wire them with scaffold_agent_activation before treating it as done.

create_agent

Create contact: add one native contact with Studio's validation and duplicate detection; returns contactId. Fill the identity fields you know, then set properties with set_crm_contact_property and tags with replace_crm_contact_tags. After a timeout, look the contact up before retrying.

create_crm_contact

Create a messaging channel on a connected GoHighLevel or Kommo account, so a Ninjo agent can answer conversations that live inside the CRM. WHEN THIS IS THE RIGHT ANSWER: a WhatsApp number can only be connected in ONE place at a time. If the number already lives in GoHighLevel/Kommo, it CANNOT also be connected directly to Ninjo — this channel is how you get around that: the number stays in the CRM and Ninjo replies THROUGH the CRM. For Instagram and Facebook you usually do NOT need this: they can be in the CRM and in Ninjo simultaneously, so create_connect_link with 'instagram'/'facebook' is the better path. PREREQUISITES, in order: 1. The CRM account is connected — create_connect_link with 'gohighlevel_crm' or 'kommo_crm'. 'gohighlevel_booking' does NOT work for this; it is a different integration on a different table. 2. The channel ALREADY EXISTS inside the CRM. Ninjo attaches to a channel that is set up in GoHighLevel/Kommo; it does not create one there. If it doesn't exist yet, the user must add it in the CRM first. There is NO manual webhook step in either CRM — do not ask the user to paste a webhook URL anywhere, and never ask for an API key or private-integration token. third_party_whatsapp (GoHighLevel + WHATSAPP only): set true when the number reaches GHL through an EXTERNAL provider (a WhatsApp QR/app integration) rather than GoHighLevel's own official WhatsApp. GHL rejects official-WhatsApp sends for those numbers, so a wrong value silently breaks outbound. ASK the user which of the two they have; do not guess. If it turns out wrong afterwards, fix it with set_messaging_channel_whatsapp_provider — the channel cannot simply be recreated. The channel is created ENABLED. Pass agent_id here to route it in one step; assigning later via set_agent_crm_channel needs a user JWT and fails for API-key callers. Common failures: 409 "already exists" (one channel per type per account), 409 asking for connected_account_id (more than one account of that CRM — take it from a list_crm_connections row for that provider, NOT from list_connected_accounts, which lists Meta sub-accounts from another table), 409 telling you to reconnect (the CRM account predates OAuth). A connected_account_id from the wrong table comes back as "No GoHighLevel account connected" — that error means the id did not match, not that the CRM is unconnected, so re-read it before telling the user to reconnect anything. Returns { channel, webhook_registered? }. On Kommo, webhook_registered: false means the channel exists but receives nothing — retry with register_messaging_channel_webhook before telling the user it is live.

create_messaging_channel

Pipeline automations: create a rule that moves, adds or transfers pipeline records when a record enters a stage or a contact property changes. Read get_crm_pipeline_automations for stages, property definitions and operators first. actionReason is recorded on the records it acts on. Enable only the configuration you intend.

create_crm_pipeline_automation

Products: create a product with its first price. amount is a decimal string in major units ("19.95") in the given ISO currency.

create_crm_product

Create property: add a typed property (string, integer, boolean, datetime or option) in a fact scope (contact, conversation or pipeline record). Scoped facts need the workspace rollout. Options are comma-separated labels; defaults and evaluation settings are validated. The codename is generated.

create_crm_property

Quotes: create a quote for a contact. Lines use either immutable productPriceId versions or productId with a custom unitAmount in minor units, all lines the same way. It does not message the contact.

create_crm_quote

Routing: create an assignment routing rule that assigns matching conversations or pipeline records to a team or person. Read get_crm_routing for criteria, targets and options first. Pass a fresh createRuleId and reuse it with the same payload when retrying. FORCE needs forceReason and permission.

create_crm_routing_rule

External CRM sync: create a stage trigger that sets a contact property when the contact reaches a stage in the external CRM. syncConnectionId and stageId come from get_crm_sync; customPropertyId must be a GENERIC property (list_crm_properties); value is the text to set, after delayMinutes (0 to 525600). It keeps acting on live contacts until deleted with delete_crm_sync_trigger.

create_crm_sync_trigger

Tags: create a reusable contact tag with a name and an optional six-digit hex color (for example #336699). Assign it to contacts with replace_crm_contact_tags.

create_crm_tag

Teams: create a team with a name and an optional description. Repeating the same create is deduplicated; reload get_crm_teams for its id and revision.

create_crm_team

Upload a context document for a Ninjo agent. If file_base64 is provided, uploads to S3 at agents/{influencer_id}/context/{uuid}/{file_name}. Returns the created document row.

create_document

Step 1 of reporting feedback (optional, only when a log excerpt is needed to reproduce the problem). Returns a short-lived presigned S3 PUT URL + s3_key. Write ONLY the tool calls and error responses involved in the failing task to a file and PUT it to upload_url (no special headers needed) — never the user's messages or the rest of the chat; the bytes never pass through the tool-call payload or model context. Then call report_feedback with the returned s3_key as session_s3_key. Returns { upload_url, s3_key }.

create_feedback_upload_url

Step 1 of uploading an agent-sendable audio/image clip. Returns a presigned S3 PUT URL + s3_key — the file bytes are NOT sent through this tool. AUDIO must be M4A/AAC (MP3 rejected); IMAGE must be JPG/PNG/GIF. Next: PUT the file to upload_url with the same Content-Type header (e.g. `curl -T file.m4a -H 'Content-Type: audio/mp4' '<upload_url>'`), then call register_creator_resource with the s3_key. Returns { upload_url, s3_key }.

create_resource_upload_url

Create a new Cortex thread (conversation between the influencer and their AI agent). Returns the new conversation object with id, title, status, created_at. Uses JWT for RLS when available; with API key/admin, pass influencer_id.

create_thread

Create a trigger for a Ninjo agent. `type` selects the variant and which fields apply: • keywords — DM keyword trigger: keyword (required), match_mode (KEYWORD_ONLY|ANYWHERE), allow_typo. • all-messages — fires on every DM or comment: keyword must be ALL_DM or ALL_COMMENTS; prompt_evaluator optional; AI public-reply settings are supported only with ALL_COMMENTS. An active ALL_COMMENTS trigger starts DMing every commenter immediately, and the runtime does not honor negative configs for ALL_COMMENTS — only create it when that behavior should be live. • comments — comment keyword trigger: keyword (required), match_mode, allow_typo, responses (public reply templates), optional AI public-reply settings. A match sends a private DM automatically; use sync_trigger_canned_responses for fixed DM text. AI is not required. When AI public replies are active, the private DM is AI-generated and canned DM text is used only when processing falls back to the non-AI path. • ads — ad referral trigger: ad_id (required). • outgoing-messages — fires on an outgoing message keyword: keyword (required), assign_unpaused. • instagram-story — story reply trigger: story_id (required), story_created_at. Returns { trigger } — the created trigger row. To edit an existing comment trigger's saved public reply text, use update_trigger_comment_response with a response ID from list_triggers.

create_trigger

Create a new WhatsApp message template and submit it to Meta for review (via mk1-chat). This SENDS NOTHING — it registers a template that can be broadcast later, once Meta approves it. Creation is asynchronous, so plan for the wait: 1. Call this tool. It returns { templateId, status } — status is normally PENDING, which means NOT usable yet. 2. Meta review usually takes minutes but can take up to 24h. Poll list_whatsapp_templates with includeAllStatuses:true and find this template by name/templateId: watch its status go PENDING → APPROVED. (The default listing shows APPROVED only, so on that path the template simply appears once approved — but includeAllStatuses:true lets you see it the whole time, including while PENDING.) 3. If it comes back REJECTED, the same includeAllStatuses:true listing carries its rejectedReason (why Meta rejected it) — no need to wait for Meta's email. Fix the wording that reason points at and create it again under a NEW name (a rejected name stays taken). 4. Once APPROVED, MARKETING/UTILITY can be broadcast the normal way: preview_whatsapp_template_recipients → confirm with the user → send_whatsapp_template. headerType decides which header field travels with it, and the two must agree: TEXT needs headerText, IMAGE needs headerImageUrl, the default NONE takes neither. A mismatch (an image URL on a NONE/TEXT header, a headline on a NONE/IMAGE one) is refused here before the call leaves, because headerType is what builds the template — a stray headerImageUrl would otherwise be dropped and the template created with no picture at all. For an IMAGE header, the headerImageUrl passed here is the sample Meta reviews. When you broadcast, pass the SAME headerImageUrl to send_whatsapp_template — that is what the contacts actually receive. AUTHENTICATION uses preset wording and a COPY_CODE OTP button. Omit bodyText/bodyExamples/headers/footerText/buttons; use authentication options for security disclaimer, expiry minutes and optional button label. After approval, your authentication backend sends one code per login attempt through POST /api/n8n/send-template with template.variables: [code] and a new idempotencyKey. send_whatsapp_template is a broadcast tool and cannot deliver authentication codes. The backend generates, expires and verifies codes. A template lives inside one WhatsApp Business Account, so pass fromWhatsAppAccountId (from list_whatsapp_templates) when the influencer has more than one number connected, and send it later from that same account. Returns { ok, influencerId, templateId, status, name, languageCode, category }.

create_whatsapp_template

Products: deactivate a product price (productPriceId from get_crm_commerce) so it can no longer be used. Existing quotes and sales keep their price snapshots.

deactivate_crm_product_price

Permanently delete a Ninjo agent and all its associated data (triggers, prompt versions, documents, workflow relations, config). Cannot delete agents with active conversations — will return an error with the count. Returns { success: true }.

delete_agent

Delete contact note: remove one note from a contact's notes. It stops appearing in list_crm_contact_notes.

delete_crm_contact_note

Delete property: permanently delete a property after reviewing preview_crm_property_delete. Can remove stored values; this is not archiving. Dependency blockers still apply.

delete_crm_property

External CRM sync: delete a stage-to-contact-property trigger (triggerId from get_crm_sync). Values it already set on contacts are kept.

delete_crm_sync_trigger

Delete a contact limit by id. Returns { success: true }.

delete_contact_limit

Delete a creator resource (removes the S3 object and the DB row). Returns { deleted, resource_id }.

delete_creator_resource

Delete a custom notification by id. Returns { success: true }.

delete_custom_notification

Delete a custom property by id, with its stored values and the conditions, effects and property actions that reference it. Refused (409) while the property has CRM history or an enabled pipeline automation triggered by it; to retire such a property, set includeInLlm: false with upsert_custom_property. Returns { success: true }.

delete_custom_property

Delete a context document from a Ninjo agent. If the document has an S3 file_key, deletes it from S3 as well. Returns { success: true }.

delete_document

Delete a notification destination by id. Returns { success: true }.

delete_notification_destination

Delete a property action by id. Its subtype row (http / crm_*) is removed too. Returns { success: true }.

delete_property_action

Delete a Cortex thread and all its messages.

delete_thread

Delete a trigger by ID and type. type must be one of: keywords, all-messages, comments, ads, outgoing-messages, instagram-story. Cascades to trigger_negative_config if present. Returns { success: true }.

delete_trigger

Remove the negative config from a trigger. The trigger itself is not affected.

delete_trigger_negative_config

Delete a WhatsApp template definition by id (via mk1-chat). Refused with 409 if any notification destination still references it (detach or delete those first) — the definition is never silently orphaned. Returns { ok, influencerId, id }.

delete_whatsapp_template_definition

Delete a workflow by id. Returns { success: true }.

delete_workflow