Chatbot API: How to Add a Business AI Assistant to Your Own App

A chatbot API lets you talk to a chatbot from your own code instead of through a ready-made chat window. Your app sends the user's message to the API and gets the chatbot's answer back; you decide where and how to show it. That means the same assistant that answers on your website can also work inside your mobile app, a bot you built, or your internal tools.

This guide covers when an API is the right choice over a widget, how to send your first request with the Helovo Chatbot API, and the security rules to follow.

Widget or API?

If you want to chat with visitors on your website, the widget is always simpler. You need the API when the conversation has to live inside your own product instead.

What you can build with a chatbot API

• In-app support: an assistant on your app's Help screen that answers with your business's information.
• Your own messaging bot: answers for a Telegram or Discord bot you wrote yourself.
• Agencies: connect the assistants you build for clients to your own dashboard or product.
• Help desk tools: draft replies to incoming emails or tickets from the assistant's knowledge.
• Kiosks and internal tools: an assistant on in-store screens or your intranet that answers with company information.

The biggest advantage is that the API separates the assistant's knowledge from your code. When a price changes or you want a new rule, you update the instructions in the dashboard; your code stays the same.

How the Helovo API works

Every Helovo chatbot works through both the widget and the API:

1. Create an account, build your chatbot, write its instructions and test it in the dashboard.
2. Create a key on the API page of the dashboard. Scope it to all chatbots or just the ones you choose. The key is shown only once.
3. Keep the key in an environment variable on your server and send requests to POST /v1/chat.

The API is available on the paid plan: 5,000 API requests a month and 60 a minute. See the pricing page for current options.

Your first request

curl https://api.helovo.com/v1/chat \
  -H "Authorization: Bearer $HELOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bot_id": "bot_…", "message": "Are you open on Saturday?", "user": "customer-42" }'

Response:

{
  "id": "msg_01J…",
  "conversation_id": "conv_01J…",
  "answer": "Yes, we're open 10 am to 4 pm on Saturdays.",
  "model": "standard",
  "finish_reason": "stop",
  "usage": { "input_tokens": 142, "output_tokens": 18 }
}

bot_id is the chatbot's ID, shown on its Install tab. user is optional; send your own user ID and conversations show up with it in the dashboard.

Continuing a conversation

For the assistant to remember earlier messages, pass the conversation_id from the first answer in later requests. You don't have to store the history yourself.

// Node.js 18+ (server side)
let conversationId;

async function ask(message) {
  const res = await fetch("https://api.helovo.com/v1/chat", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.HELOVO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ bot_id: "bot_…", message, conversation_id: conversationId }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error.message);
  conversationId = data.conversation_id;
  return data.answer;
}

console.log(await ask("How long does shipping take?"));
console.log(await ask("And what about returns?"));

Streaming

To let users read the answer as it's written, send "stream": true. The answer arrives as Server-Sent Events: meta (with the conversation ID), then delta events with pieces of text, and finally done or error.

import json, os
import requests

with requests.post(
    "https://api.helovo.com/v1/chat",
    headers={"Authorization": f"Bearer {os.environ['HELOVO_API_KEY']}"},
    json={"bot_id": "bot_…", "message": "Hello", "stream": True},
    stream=True,
    timeout=90,
) as res:
    event = None
    for line in res.iter_lines(decode_unicode=True):
        if line.startswith("event: "):
            event = line[7:]
        elif line.startswith("data: ") and event == "delta":
            print(json.loads(line[6:])["text"], end="", flush=True)

Security rules

• Never put the key in browser or mobile app code. Have your app call your own server, and your server call the Helovo API. The Helovo API refuses browser (CORS) requests anyway.
• Scope your keys: create a separate key for each integration and give it access only to the chatbots it needs.
• Keep keys in environment variables, never in your repository. If you suspect a leak, revoke the key in the dashboard and create a new one.

Errors and limits

Errors come back as {"error": {"code": "…", "message": "…"}}. The ones you'll see most:

• 401 invalid_api_key: the key is wrong, revoked or expired.
• 404 chatbot_not_found: the chatbot doesn't exist or the key can't access it.
• 429 rate_limited or quota_exceeded: the per-minute limit or monthly quota is reached. Wait for the time in the Retry-After header.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. See all fields and error codes in the developer docs, or the machine-readable OpenAPI spec.

The assistant follows the same rules over the API

Messages through the API follow the same rules as the website widget: the assistant answers only from what you wrote, turns down off-topic requests and introduces itself as your business's assistant. For help writing its instructions, see our chatbot instruction templates.

Frequently asked questions

Which programming languages can I use?

Any language that can send an HTTP request: JavaScript (Node.js), Python, PHP, Go, Java, C# and more. There's no SDK to install.

Can I see API conversations in the dashboard?

Yes. API conversations are listed in the dashboard too, and you can filter by source.

Can I try the API for free?

You can build and test your chatbot in the dashboard for free; API requests are available on the paid plan.