Tool Types Reference

The exact payload for each toolType. These fields apply to create and update. You can also fetch this reference (with a valid example) live from GET /v2.0/tools/schema.

Common fields (all types)

Parameter	Type	Required	Description
name	string	Required	Lowercase letters/numbers/underscores, starts with a letter. Unique per organization.
description	string	Required	When the AI should call this tool. Be specific about the trigger.
toolType	string	Required	One of the 8 types below. Immutable after creation.
isActive	boolean	Optional	Enabled state. Defaults to true on create.Default: `true`
pixelEvent	string	Optional	Optional conversion event: Purchase \| LeadSubmitted \| QualifiedLead.
tags	array	Optional	Optional array of ToolTag ids for dashboard grouping.

function

Calls an external HTTP endpoint. The AI fills the declared parameters; Sendiee makes the request and feeds the response back to the AI.

Parameter	Type	Required	Description
serverUrl	string	Required	http(s) endpoint. Use {{param}} placeholders in the path.
requestMethod	string	Optional	GET \| POST \| PUT \| PATCH \| DELETE.Default: `POST`
auth	object	Optional	{ type: none\|bearer\|api_key\|basic, ... }. bearer→token; basic→username+password; api_key→apiKeyIn/apiKeyName/apiKeyValue.
headers	array	Optional	Array of { key, value, enabled }. Duplicate keys (case-insensitive) are rejected.
bodyMode	string	Optional	auto \| custom \| none. custom requires customPayload.Default: `auto`
customPayload	string	Optional	JSON string with {{variable}} placeholders. Required when bodyMode = custom.
parameters	object	Optional	JSON-schema the AI fills: { type:'object', properties:{...}, required:[...] }. Property names must be lowercase/underscore.
timeout	number	Optional	Seconds, 1–300.Default: `30`
strict	boolean	Optional	Enforce strict parameter validation.
async	boolean	Optional	Fire-and-forget; the AI continues without waiting.

Example

{
  "name": "get_order_status",
  "description": "Look up the delivery status of an order by its order number.",
  "toolType": "function",
  "serverUrl": "https://api.yourstore.com/orders/{{order_id}}",
  "requestMethod": "GET",
  "auth": { "type": "bearer", "token": "sk_live_xxx" },
  "headers": [{ "key": "Content-Type", "value": "application/json", "enabled": true }],
  "bodyMode": "none",
  "parameters": {
    "type": "object",
    "properties": { "order_id": { "type": "string", "description": "Customer order number, e.g. 1001" } },
    "required": ["order_id"]
  },
  "timeout": 30
}

static_tool

Returns a fixed message. Supports {{current_date}}, {{current_time}}, {{current_datetime}}, {{phone_number}} placeholders.

Parameter	Type	Required	Description
response	string	Required	The message returned when the AI calls this tool.
isStrict	boolean	Optional	When true the response is sent verbatim; when false the AI may rephrase it.

Example

{
  "name": "store_hours",
  "description": "Tell the customer the store opening hours.",
  "toolType": "static_tool",
  "response": "We are open 9am–9pm daily. Today is {{current_date}}.",
  "isStrict": false
}

media_attachments

Sends 1–5 media files. Files must already exist in Sendiee (upload via the dashboard); reference them by File id. The caption is sent with the first file.

Parameter	Type	Required	Description
mediaIds	array	Required	1–5 Sendiee File ids (24-char hex).
response	string	Optional	Caption/message accompanying the media.
isStrict	boolean	Optional	Send the caption verbatim when true.

Example

{
  "name": "send_brochure",
  "description": "Send the product brochure PDF when the customer asks for details.",
  "toolType": "media_attachments",
  "mediaIds": ["64f0c0ffeeb0c0ffeeb0c0ff"],
  "response": "Here is our latest brochure!"
}

message_templates (WhatsApp)

A WhatsApp interactive message. templateType is one of: button, list, cta_url, product, product_list, catalog_message, flow, carousel. The components object is the exact Meta interactive JSON and is sent to Meta verbatim.

Parameter	Type	Required	Description
templateType	string	Required	One of the 8 WhatsApp interactive types above.
components	object	Required	Meta interactive payload: { type, header?, body:{text}, footer?, action }.
headerType	string	Optional	'text' or 'media'. Derived from components.header when omitted.
mediaId	string	Optional	Sendiee File id for a media header you uploaded (alternative to a public link).

Meta limits (enforced)

body ≤ 1024 · header ≤ 60 · footer ≤ 60 · ≤ 3 reply buttons (unique titles) · list ≤ 10 sections / ≤ 10 rows total (unique row titles), section title ≤ 24, row title ≤ 24, row description ≤ 72 · CTA display ≤ 20 (valid http(s) url) · product_list ≤ 10 sections / ≤ 30 products · carousel 2–10 cards.

{
  "name": "order_actions",
  "description": "Offer the customer quick actions on their order.",
  "toolType": "message_templates",
  "templateType": "button",
  "components": {
    "type": "button",
    "body": { "text": "What would you like to do with your order?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "track", "title": "Track order" } },
        { "type": "reply", "reply": { "id": "cancel", "title": "Cancel order" } }
      ]
    }
  }
}

instagram_templates

An Instagram message. instagramComponents.message holds text, quick_replies, or an attachment template.

Parameter	Type	Required	Description
instagramComponents	object	Required	{ message: { text?, quick_replies?, attachment? } }. Must contain at least one of text / quick_replies / attachment.

Limits (enforced)

≤ 13 quick replies (each needs a title) · button card ≤ 3 buttons · generic carousel ≤ 10 elements (each needs a title, ≤ 3 buttons). Buttons are web_url (needs url) or postback (needs payload).

{
  "name": "ig_pricing",
  "description": "Share pricing options on Instagram with quick replies.",
  "toolType": "instagram_templates",
  "instagramComponents": {
    "message": {
      "text": "Which plan interests you?",
      "quick_replies": [
        { "title": "Basic", "payload": "PLAN_BASIC" },
        { "title": "Pro", "payload": "PLAN_PRO" }
      ]
    }
  }
}

messenger_templates

A Messenger message. messengerComponents.message holds text, quick_replies, a button/generic template, or a media attachment.

Parameter	Type	Required	Description
messengerComponents	object	Required	{ message: { text?, quick_replies?, attachment? } }. Must contain at least one of text / quick_replies / attachment.

Limits (enforced)

≤ 13 quick replies · button template ≤ 3 buttons · generic template ≤ 10 elements (each needs a title, ≤ 3 buttons) · media attachment needs a valid http(s) payload.url.

button template

{
  "name": "fb_welcome",
  "description": "Greet the customer on Messenger with menu buttons.",
  "toolType": "messenger_templates",
  "messengerComponents": {
    "message": {
      "attachment": { "type": "template", "payload": {
        "template_type": "button",
        "text": "Welcome! How can we help?",
        "buttons": [{ "type": "postback", "title": "Browse", "payload": "BROWSE" }]
      } }
    }
  }
}

sendiee_catalog

Built-in Sendiee Catalog action. The AI supplies only narrow args; the catalog (and optional collection) are pinned here.

Parameter	Type	Required	Description
catalogAction.type	string	Required	list_collections \| list_products \| get_product \| get_collection_products.
catalogAction.catalogId	string	Required	24-char Sendiee catalog id.
catalogAction.collectionId	string	Optional	Required when type = get_collection_products.
catalogAction.defaultLimit	number	Optional	1–20. Fallback result count.Default: `5`

Example

{
  "name": "search_products",
  "description": "Search the catalog when the customer asks about products.",
  "toolType": "sendiee_catalog",
  "catalogAction": { "type": "list_products", "catalogId": "64f0c0ffeeb0c0ffeeb0c0ff", "defaultLimit": 5 }
}

shopify

Built-in Shopify action. The org’s connected Shopify store is resolved server-side, so no store credentials are passed.

Parameter	Type	Required	Description
shopifyAction.type	string	Required	search_products \| get_product \| get_variants \| list_collections \| get_collection_products \| track_order \| get_order \| search_customer \| list_customer_orders \| create_draft_order \| send_invoice.
shopifyAction.defaultLimit	number	Optional	1–20. Fallback result count for list-style actions.Default: `10`

Requires a connected Shopify store

The tool fails at runtime if the organization has not connected Shopify. Connect it from the dashboard’s Integrations page first.

Example

{
  "name": "track_order",
  "description": "Look up the shipping status of a Shopify order by its order number.",
  "toolType": "shopify",
  "shopifyAction": { "type": "track_order", "defaultLimit": 10 }
}