Setup Custom Tools

Custom Tools let Wik AI call your external APIs during conversations—so it can check warranty status, verify service coverage, or fetch data from your own services without handing off to a human agent.

When a customer asks a question, Wik AI extracts the relevant values from the conversation, inserts them into your API request, and uses the response to form its reply.

---

Creating a Tool

Navigate to Wik AI → Tools and click Create a new tool.

Fill in the following fields:

• Tool Name: A short name like "Warranty Lookup" or "Service Area Check" (max 55 characters).

• Description: Tell Wik AI when to use this tool. This is the most important field. Write it like you are briefing a support agent: "Checks the warranty status of a product by its serial number." Vague descriptions like "Warranty API" will cause Wik AI to miss opportunities to use the tool.

• Method: Choose GET (for fetching data) or POST (for submitting data).

• Endpoint URL: Your API's URL. Use {{ parameter_name }} to insert values extracted from the conversation:

  https://api.yourcompany.com/v1/warranty/{{ serial_number }}

  The URL must use HTTPS, must be a hostname (not an IP address), and cannot point to localhost or private networks.

• Authentication: Choose how your API authenticates requests:

  • None: No authentication required.
  • Bearer Token: Sends your token in the Authorization header.
  • Basic Auth: Sends a username and password.
  • API Key: Sends a custom header name and value (e.g. X-API-Key).

  Authentication credentials are only visible to account administrators.

• Parameters: Define what Wik AI should extract from the customer's message. Each parameter needs a name, type, and description. For example: serial_number (String) — "The product serial number, found on the back of the device."

• Request Template (POST only): A JSON body template using Liquid syntax.

• Response Template: Controls what Wik AI sees from your API's response. If left blank, Wik AI receives the raw JSON. Use Liquid to extract relevant fields, for example:

  Serial {{ response.serial_number }}: {{ response.warranty_status }}. Expires: {{ response.expiry_date }}.

  Use response to access the parsed JSON body. Response templates help Wik AI focus on relevant data and avoid internal fields like database IDs or debug info.

---

Testing Your Tool

Click Test connection before saving to verify your endpoint is reachable. The test reports the HTTP status code. A green result (HTTP 200–299) means the connection and authentication are working. Note that the test sends the URL without filling in parameter values, so it only verifies that your endpoint is reachable and your credentials are accepted.

If the test fails, check the following:

• 401 Unauthorized: Your authentication credentials are incorrect. Double-check your bearer token, API key, or username/password.
• 403 Forbidden: Your API is rejecting the request. If you require identity verification, note that test requests don't include contact headers.
• 404 Not Found: The endpoint URL is wrong. Verify the path and ensure your API is running.
• Timeout: Your API took too long to respond. Custom tools have a 30-second timeout; make sure your endpoint responds within that window.

---

Context Sent with Every Tool Call

When Wik AI calls your API, it includes metadata headers so your backend knows the context:

• X-Chatwik-Account-Id: Your account ID
• X-Chatwik-Conversation-Id: The conversation ID
• X-Chatwik-Contact-Email: The customer's email (if available)
• X-Chatwik-Contact-Inbox-Verified: Whether the customer's identity is HMAC-verified
• X-Chatwik-Assistant-Id: The Wik AI assistant making the call
• X-Chatwik-Tool-Slug: The tool's internal identifier
• X-Chatwik-Contact-Id: The customer's contact ID
• X-Chatwik-Contact-Phone: The customer's phone number (if available)
• X-Chatwik-Conversation-Display-Id: The conversation's display number

You can use these headers to look up the customer in your own system, log which conversations triggered API calls, and verify request authenticity.

---

Security

• Built-in Protections:
  • All endpoints must use HTTPS.
  • Requests to private IP ranges, localhost, and .local domains are blocked.
  • HTTP redirects are not followed.
  • Responses are capped at 1 MB.
  • Auth credentials are only visible to administrators.
• Identity Verification: If your tool returns customer-specific data (orders, billing, account details), your API should check the X-Chatwik-Contact-Inbox-Verified header. Without HMAC verification enabled on your inbox, a visitor could set any email address in the chat widget. Only return sensitive data when this header is true. For tools that return public data, this check is not needed.
• Prompt Injection: If your API returns user-generated content (reviews, forum posts), malicious text could influence Wik AI's behavior. Use response templates to extract only structured fields, and sanitize content on your API side.

---

Limits

• Max tools per account: 15
• Recommended: 10 or fewer. A warning appears above 10; more tools make it harder for Wik AI to pick the right one.
• Tool name length: 55 characters maximum
• Response size: 1 MB max
• Request timeout: 30 seconds

---

When to Use Custom Tools

Custom tools are best suited for structured lookups with predictable inputs — checking system status, fetching schedules, or looking up records by ID. If you already have a dedicated Chatwik integration for your use case (e.g., Shopify for e-commerce), use that instead — dedicated integrations handle search, fuzzy matching, and data sync more reliably than a single API call.

---

Examples

1. Warranty Lookup

When a customer asks whether their product is still under warranty, Wik AI can check it using the serial number.

• Tool Name: Warranty Lookup
• Description: Checks the warranty status of a product by its serial number. Use when a customer asks if their product is covered, when the warranty expires, or what type of coverage they have.

2. Service Area Check

For businesses that operate in specific regions — customers ask whether service is available at their location.

• Tool Name: Service Area Check
• Description: Checks whether service or delivery is available in a specific area using the customer's zip code or city name.

Custom Tools work best when the inputs are straightforward and the API response is predictable — status checks, lookups, and other structured queries are a great fit.