Custom Function Tools

Overview

Sulus allows you to create custom function tools that connect your assistant to external APIs, databases, or any custom logic you define. These tools enable your assistant to perform actions and retrieve information during live calls.

Custom function tools are defined as JSON schemas that describe a function the assistant can call. When the assistant determines it needs to use a tool, it sends a request to your configured server (webhook) with the relevant parameters, and your server returns a result that the assistant uses to continue the conversation.

You can define a custom tool either as a transient (inline) configuration or as a permanent stored tool.

Permanent Tool (stored on Sulus servers):

curl -X POST "https://api.sulus.ai/tool" \
  -H "Authorization: Bearer $CORE_SYSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function",
    "name": "update_crm_contact",
    "description": "Update contact information in the CRM system",
    "parameters": {
      "type": "object",
      "properties": {
        "contactId": {
          "type": "string",
          "description": "CRM contact ID"
        },
        "updates": {
          "type": "object",
          "description": "Fields to update"
        }
      },
      "required": ["contactId", "updates"]
    },
    "server": {
      "url": "https://api.yourcrm.com/contacts/update",
      "secret": "your-webhook-secret"
    }
  }'

Transient Tool (inline, per-call):

{
  "tools": [
    {
      "type": "function",
      "name": "check_inventory",
      "description": "Check product inventory for the customer's specific region",
      "parameters": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string",
            "description": "The product ID to check"
          },
          "region": {
            "type": "string",
            "description": "Customer's region code"
          }
        },
        "required": ["productId", "region"]
      },
      "server": {
        "url": "https://api.customer-integration.com/inventory",
        "secret": "customer-webhook-secret",
        "timeoutSeconds": 30
      }
    }
  ]
}

Once you've created a permanent tool and have its ID, reference it in your call like this:

curl -X POST "https://api.sulus.ai/call" \
  -H "Authorization: Bearer $CORE_SYSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "your-phone-number-id",
    "customer": {
      "number": "+1234567890"
    },
    "assistantId": "your-assistant-id",
    "assistantOverrides": {
      "toolIds": ["tool-id-1", "tool-id-2"]
    }
  }'

• Write a clear, specific description so the AI knows exactly when to invoke the tool
• Use required in your parameter schema to enforce mandatory fields
• Include error handling in your webhook server and provide fallback responses in the assistant's system prompt
• Treat server.secret as a credential and keep it secure
• For sensitive integrations, prefer permanent configurations which are stored securely on Sulus servers

Custom function tools are the primary way to extend your Sulus assistant with real-world capabilities, from CRM updates and inventory checks to any custom API your business relies on.