Chatbot API Integration: REST, Zapier & Webhooks Explained

A chatbot API is an HTTP interface that lets you send messages to an AI chatbot and receive responses programmatically — without using a visual widget. Instead of a user typing into a chat bubble, your code sends a request, gets a reply, and does something with it: renders a custom UI, logs the answer, triggers an action, or routes the result to another system.

This guide covers what a chatbot API is, when to use one over an embedded widget, the three main connection methods (REST, Zapier, and webhooks), and practical patterns for building real integrations.

What is a chatbot API?

A chatbot API exposes your trained AI chatbot as a service that any code can call over HTTP. You send a user message in the request body, and the API returns the chatbot's answer — drawn from whatever sources (website content, documents, Q&A pairs) you used to train it.

The key distinction from a pre-built widget: the API returns raw data. Your application decides how to present it. That means you can embed the same chatbot in a mobile app, a Slack bot, an internal dashboard, and a backend automation pipeline — all using the same trained knowledge base.

Most chatbot APIs follow a similar pattern:

1. Authenticate — include an API key in the Authorization header.
2. POST a message — send the user's text, a chatbot ID, and optionally a conversation ID for multi-turn context.
3. Handle the response — parse the reply, optionally stream tokens for a real-time feel, and store the conversationId for the next turn.

For teams comparing chatbot options before committing to a platform, this overview of the best AI chatbots for websites covers what to look for across tools.

When to use the API vs. the widget

The embedded widget handles the majority of website use cases. The API is the right choice when you need something the widget cannot provide.

If your use case falls in the right column, the API is the right tool. For full embed options — widget, React component, iframe, and WordPress plugin — see the chatbot integration guide.

Connection methods and plan availability

There are three ways to connect your chatbot to external systems. They serve different purposes and are available on different plans.

The REST API gives you the most control. Zapier is faster to set up if you do not need custom code. Webhooks complement both — they push data to you rather than waiting for you to pull it.

For a full breakdown of what each plan includes, see the chatbot cost and pricing guide.

Plan requirements

Annual billing reduces each plan price by approximately 20%. API messages count against your monthly quota the same way widget messages do.

Authentication

Every API request requires a Bearer token. You generate API keys from the workspace settings in your Agentkit dashboard.

Generating an API key

1. Open your Agentkit workspace.
2. Navigate to Settings then API Keys.
3. Click Create API Key.
4. Give it a descriptive name (e.g., "Slack Bot Production").
5. Copy the key immediately. It will not be shown again.

Using the key in requests

Include your API key in the Authorization header:

Authorization: Bearer ak_live_your_api_key_here

All requests must be sent over HTTPS. Requests without a valid token return a 401 Unauthorized response.

Key management best practices

• Store API keys in environment variables, never in client-side code.
• Rotate keys periodically, especially after team changes.
• Create separate keys for separate integrations so you can revoke one without affecting others.
• Delete keys you no longer use.

For full authentication details, see the authentication documentation.

The chat endpoint

The core of the API is a single endpoint that sends a user message to your chatbot and returns the AI response.

Request

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer ak_live_your_api_key_here

Request body:

{
  "chatbotId": "your-chatbot-id",
  "message": "What are your shipping options?",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id",
  "metadata": {
    "page": "/products/shoes",
    "userTier": "premium"
  }
}

Response

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "message": "We offer three shipping options: Standard (5-7 business days, free over $50), Express (2-3 business days, $9.99), and Overnight ($24.99). All orders include tracking.",
  "sources": [
    {
      "title": "Shipping Policy",
      "url": "https://example.com/shipping"
    }
  ],
  "createdAt": "2026-02-22T14:30:00Z"
}

The conversationId in the response is important. Store it and pass it back in subsequent requests to maintain conversation context. Without it, each message starts a new conversation and the chatbot loses the thread.

Error responses

For the complete endpoint reference, see the API documentation.

Streaming responses

For real-time applications where you want to display the response as it is generated (the typewriter effect users expect from AI chat), use Server-Sent Events (SSE).

Add the stream: true parameter to your request:

{
  "chatbotId": "your-chatbot-id",
  "message": "Explain your return policy",
  "conversationId": "conv_xyz789",
  "stream": true
}

The response arrives as a stream of SSE events:

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "token", "content": " allows"}
...
data: {"type": "sources", "sources": [{"title": "Return Policy", "url": "https://example.com/returns"}]}
data: {"type": "done", "conversationId": "conv_xyz789", "messageId": "msg_def456"}

Handling the stream in JavaScript

const response = await fetch('https://api.agentkit.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ak_live_your_api_key_here'
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    message: 'Explain your return policy',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'token') {
      appendToUI(data.content);
    }
  }
}

Streaming is recommended for any user-facing integration. It makes the chatbot feel responsive even when generating long answers.

Webhooks

While the chat endpoint lets you send messages to the chatbot, webhooks let the chatbot send data to you. When specific events happen, Agentkit sends an HTTP POST request to a URL you configure. Webhooks are available on the Hobby plan and above.

Setting up webhooks

1. Go to your workspace Settings then Webhooks.
2. Enter your endpoint URL (must be HTTPS).
3. Select which events to subscribe to.
4. Save. Agentkit sends a verification request to confirm your endpoint is reachable.

Available events

Webhook payload

Every webhook POST includes a JSON body with a consistent structure:

{
  "event": "lead.captured",
  "timestamp": "2026-02-22T15:45:00Z",
  "chatbotId": "your-chatbot-id",
  "conversationId": "conv_xyz789",
  "data": {
    "name": "Alex Chen",
    "email": "[email protected]",
    "message": "Interested in the enterprise plan"
  },
  "signature": "sha256=abc123..."
}

Always verify the signature field against your webhook secret to confirm the request came from Agentkit, not a third party.

Retry behavior

If your endpoint returns a non-2xx status code, Agentkit retries with exponential backoff: after 1 minute, 5 minutes, 30 minutes, then stops. Failed deliveries are visible in the webhook logs in your dashboard.

Common integration patterns

Pattern 1: Slack bot

Forward customer questions from your website chatbot into a Slack channel, and let your team respond when the AI cannot answer.

1. Create a Slack app with incoming webhooks enabled.
2. Set up an Agentkit webhook for conversation.completed events.
3. In your webhook handler, check if the conversation was resolved or escalated.
4. If escalated, POST a formatted message to your Slack webhook URL with the conversation transcript.

This gives your support team visibility without requiring them to monitor the Agentkit dashboard.

Pattern 2: Custom chat UI

Replace the default widget with a chat experience built into your application.

1. Build your chat interface with your preferred framework.
2. On message submit, call the chat endpoint with stream: true.
3. Render tokens as they arrive for real-time feedback.
4. Store the conversationId in local state to maintain context across messages.

This is the right approach for mobile apps, desktop applications, or any product where the floating widget does not fit the design. For teams that want to stay in the widget but need more control over placement, the guide to embedding a chatbot on your website covers all four embed options.

Pattern 3: Backend automation

Use the chatbot as an AI layer in a larger workflow, no chat UI involved.

Example: Processing support tickets.

1. New ticket arrives in your ticketing system.
2. Your backend sends the ticket content to the chat endpoint.
3. The chatbot generates a suggested response based on your trained knowledge base.
4. Your system either auto-replies (if confidence is high) or queues the suggestion for human review.

This pattern works because the chatbot is trained on the same knowledge base your support team uses. The API gives you programmatic access to that intelligence. For more on what you can train a chatbot on — website crawls, PDFs, CSVs, Q&A pairs — see how to train a chatbot.

Pattern 4: Analytics pipeline

Capture every conversation for analysis.

1. Subscribe to message.received and message.sent webhook events.
2. Your webhook handler writes events to your data warehouse (BigQuery, Snowflake, etc.).
3. Build dashboards showing common questions, resolution rates, peak hours, and conversation trends.

The metadata field in the chat endpoint lets you attach context (page URL, user segment, A/B test variant) that enriches your analytics.

Rate limiting

The API enforces rate limits to ensure reliability for all users.

When you hit the limit, the API returns a 429 status code with a Retry-After header indicating how many seconds to wait. Build retry logic into your integration:

async function sendMessage(payload, retries = 3) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
  });

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendMessage(payload, retries - 1);
  }

  return response.json();
}

Security considerations

When building API integrations, keep these practices in mind:

• Never expose API keys in client-side code. If you are building a custom chat UI for a web app, proxy requests through your own backend.
• Validate webhook signatures. Always verify the HMAC signature before processing webhook payloads.
• Use domain restrictions. In your chatbot settings, restrict which domains can interact with your chatbot.
• Monitor usage. Check your API usage in the dashboard regularly to catch unexpected spikes that might indicate a leaked key.
• Use the principle of least privilege. If an integration only needs to send messages, do not give it a key with admin permissions.

For teams exploring how AI chatbot APIs connect to larger tool ecosystems, MCP (Model Context Protocol) is worth understanding — it is an emerging standard for giving AI models structured access to external tools and data.

Getting started

The fastest path from zero to a working integration:

1. Sign up for an Agentkit account and create your first chatbot.
2. Train the chatbot on your content (see how to train a chatbot).
3. Upgrade to the Hobby plan ($29.99/month) to enable API access.
4. Generate an API key in your workspace settings.
5. Send your first test request using cURL or Postman.
6. Build from there: custom UI, Slack bot, automation, or whatever your use case demands.

Frequently Asked Questions

What is a chatbot API key?

A chatbot API key is a secret token that authenticates your application when it makes requests to the chatbot API. You generate it in your workspace settings, include it in the Authorization: Bearer header of every request, and treat it like a password — store it in environment variables, never in client-side code, and rotate it if you suspect it has been exposed. Each key can be scoped to a specific integration so you can revoke one without affecting others.

Is there a free chatbot API?

Agentkit's Free plan ($0/month) does not include REST API access — that requires the Hobby plan at $29.99/month. The Free plan does include the embeddable JS widget, lead capture, and domain restrictions, which cover most website use cases without any code. If you need programmatic access from day one, the Hobby plan is the entry point, and you can test the full platform for free before upgrading.

Do I need to code to use a chatbot API?

Not always. If you need REST API access for custom integrations, you will need to write code — or use a tool like Postman to test calls manually. But if your goal is connecting the chatbot to other apps without code, the Zapier integration (available on the Hobby plan and above) connects to 7,000+ apps through a no-code interface. For website embedding, no code beyond pasting a <script> tag is required.

What AI models does the chatbot API support?

The underlying AI model is configured per chatbot in the dashboard. Agentkit supports models from three providers: OpenAI (GPT-5.6 Sol, GPT-5.6 Terra, GPT-6 Luna), Anthropic (Claude Opus 5, Claude Sonnet 5, Claude Haiku 4.5), and Google (Gemini 3.7 Flash, Gemini 3.1 Pro). New agents on every plan, including Free, start with GPT-6 Sol. In our evaluation, it was the most reliable at answering from your content and at running actions and multi-step tools. Existing agents keep their selected model. Your API calls use whichever model is selected for that chatbot — you do not specify the model at the API call level.

Can I use the chatbot API to embed chat on my website?

Yes, but the JS widget embed is usually simpler for website use cases. The widget loads asynchronously via a single <script> tag and handles UI, conversation state, and streaming automatically. Use the API when you need a fully custom UI, mobile app integration, or backend automation. For a side-by-side comparison of all embed options, see the guide to embedding a chatbot on your website.

A chatbot API turns a trained knowledge base into a callable service — the same AI answers that appear in the widget are available to any system that can make an HTTP request. Whether you are building a custom interface, automating a support workflow, or connecting your chatbot to a broader tool ecosystem, the API gives you the control a pre-built widget cannot.

Build your chatbot for free → No credit card required.