Guides

AI agent

The heysteff AI agent answers your customers on WhatsApp, Instagram, Messenger, SMS and email with your instructions, your context files and your custom tools, and hands the conversation to your team when it should. It comes with all three developer plans: you pay your provider for tokens with your own key, or use the plan’s trial quota.

How it works#

1. A customer writes on any connected channel.
2. If the agent is on for that channel and that conversation, it reads the history, your instructions and your context files. When it needs to, it calls your custom tools.
3. It replies on the same channel and notifies you with agent.replied. When it should not continue, it hands the conversation to your team, pauses the bot and notifies you with agent.handoff.
4. Your team picks it up from the inbox, on the web or the mobile app, with the full history.

Turning it on and off#

There are four levels. The workspace one is the main switch: when it is off, the agent does not reply on any channel.

curl -X PATCH https://app.heysteff.com/api/v1/agent \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "anthropic",
    "model": "claude-haiku-5-5",
    "temperature": 0.3,
    "channels": [{ "id": "8a1f0c2e-5d3b-4c6a-9e7f-0a1b2c3d4e5f", "enabled": false }],
    "customers": [{ "id": "6f1c2a8e-3b4d-4e5f-9a0b-1c2d3e4f5a6b", "enabled": null }]
  }'

GET /v1/agent returns the full state: on or off, instructions, provider, model, temperature, saved keys (last 4 only), this month’s trial quota, each channel and customer with its agent_enabled, and the suggested models with their price. Every PATCH field is optional, but send at least one.

Instructions and knowledge base#

• instructions is the agent’s prompt, up to 10,000 characters: who it is, its tone, what it may promise and when it should hand the conversation to a person.
• temperature goes from 0 (precise) to 1 (creative).
• Context files: what the agent looks up to answer, such as prices, policies, opening hours or FAQs. For now you manage them from the MCP server (list_context_files, upsert_context_file, patch_context_file, delete_context_file) or by asking the console assistant; they have no endpoint in API v1.

Models and prices#

provider can be anthropic, openai, deepseek or openrouter, and model is the model id at that provider. The list below is a suggestion, not a closed catalog: with OpenRouter you can use any vendor/model. If you pick no provider or model, the agent uses the platform’s default model.

These are reference list prices, the same ones GET /v1/agent returns in models. With your key, what counts is your provider’s rate, billed to you directly.

Who pays: your key or the trial quota#

With your key (BYOK). Save your provider key with PUT /v1/agent/keys or in the console → Agent. It is stored encrypted and never comes back through the API: GET /v1/agent shows only the provider and its last 4. There is one key per provider; the agent uses the key for the provider you picked in provider. DELETE /v1/agent/keys/{provider} removes it. Your provider bills you for tokens and heysteff adds nothing on top.

curl -X PUT https://app.heysteff.com/api/v1/agent/keys \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "anthropic", "api_key": "sk-ant-..." }'

Without a key. Each reply comes out of the trial quota for the calendar month (UTC), using the heysteff key. The console assistant uses the same quota. See it in GET /v1/agent → quota (period, used, limit, remaining).

Without a key and without quota, the agent does not reply. It never switches to another provider on its own. Your webhook gets agent.failed with code: "ai_quota_exhausted" and the customer’s message stays in the inbox for your team. It replies again once you save your key, the next month starts or you upgrade. See Pricing.

Errors#

{
  "error": {
    "code": "ai_quota_exhausted",
    "message": "...",
    "fix": "...",
    "details": { "period": "2026-11", "used": 200, "limit": 200 }
  }
}

Custom tools#

A custom tool is an HTTP call to your backend that the agent makes mid-conversation: checking an order, looking up stock or booking a slot. The agent decides when to use it by reading its description, and fills in the arguments you declare in spec.parameters_schema. Every {{args.x}} in url_template, query_template, headers or body_template must be declared there.

curl -X POST https://app.heysteff.com/api/v1/agent/tools \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "order_status",
    "name": "Order status",
    "description": "Looks up an order by its number. Use it when the customer asks where their purchase is.",
    "spec": {
      "method": "GET",
      "url_template": "https://api.your-company.com/orders/{{args.number}}",
      "parameters_schema": {
        "type": "object",
        "properties": { "number": { "type": "string", "description": "Order number" } },
        "required": ["number"]
      },
      "timeout_ms": 8000
    }
  }'

• GET /v1/agent/tools and GET /v1/agent/tools/{id} list and show them (without secrets).
• PATCH /v1/agent/tools/{id} edits one; spec is replaced as a whole, so send the full spec with your change. "is_active": false turns it off without deleting it.
• DELETE /v1/agent/tools/{id} deletes it.
• The credential for your backend (a bearer token, for example) is set in the console: no third-party secrets travel through the API.

Agent webhooks#

They only reach developer workspaces, with the same envelope and signature as the rest of the webhooks. Subscribe to them when you create the webhook.

{
  "event": "agent.replied",
  "data": {
    "conversation_id": "c0a8012e-...",
    "trigger_message_id": "5b7e...",
    "message_ids": ["9f2c..."],
    "mode": "sent",
    "text": "...",
    "channel_type": "whatsapp_cloud",
    "channel_connection_id": "8a1f0c2e-...",
    "provider": "anthropic",
    "model": "claude-haiku-5-5",
    "credential": "byok"
  }
}

{
  "event": "agent.failed",
  "data": {
    "conversation_id": "c0a8012e-...",
    "trigger_message_id": "5b7e...",
    "code": "ai_quota_exhausted",
    "message": "...",
    "provider": "anthropic",
    "quota": { "period": "2026-11", "used": 200, "limit": 200, "remaining": 0 }
  }
}

Insights#

On Developer and Developer Platform, heysteff analyzes your conversations and shows you three lists: frustrated customers (frustrated), what the agent could not answer or answered wrong (agent_gaps) and unresolved conversations (unresolved). Each list has total and items.

• In the console, under Insights.
• With GET /v1/insights?days=30&limit=10 (scope insights:read): days goes from 1 to 90 and limit from 1 to 50. On Developer Free it returns included: false.
• With the insight.detected webhook, once a week when the analysis finds something.

Use insights to improve the instructions and context files: what shows up in agent_gaps is usually an answer missing from the knowledge base.

Console assistant#

The console has a side assistant you can ask about your workspace in plain language: why a webhook failed, what happened in a conversation, how much quota you have left. It also takes actions with the same tools as the MCP server, and before any change or message to a person it shows you what it is about to do and waits for your confirmation.

It uses the agent’s provider key if you saved one; otherwise, the same trial quota. Without either it returns 402 ai_quota_exhausted.

From your AI (MCP) and the SDK#

• get_developer_agent and update_developer_agent: see and configure the agent, with the same fields as PATCH /v1/agent.
• delete_developer_ai_key: removes a provider key. The key is not saved through MCP because it is a secret: save it in the console or with PUT /v1/agent/keys.
• get_developer_insights: the insights.
• list_custom_tools, create_custom_tool, update_custom_tool and delete_custom_tool: custom tools.
• set_conversation_bot: pauses or resumes the bot in a conversation.

With the TypeScript SDK:

import { Heysteff } from '@heysteff/sdk';

const heysteff = new Heysteff(); // reads HEYSTEFF_API_KEY

await heysteff.agent.setKey({ provider: 'anthropic', api_key: process.env.ANTHROPIC_API_KEY! });
const agent = await heysteff.agent.update({ enabled: true, model: 'claude-haiku-5-5' });
console.log(agent.quota, agent.keys); // keys: provider and last 4 only

const tools = await heysteff.agent.tools.list();
const insights = await heysteff.insights.get({ days: 7 });
console.log(insights.agent_gaps.total);

Every endpoint with its fields is in the API reference, under AI agent.