API

Interact with your agent programmatically over HTTP

The API deployment lets you connect your agent to any application. Instead of embedding a widget or relying on a messaging channel, you communicate with your agent directly through HTTP requests — send a message, get a response.

The endpoint is https://bot-v5.helvia.ai/api/events. Explore the full API specification:

HBF-Bot

Why Use the API

Custom Integrations

Embed your agent into mobile apps, internal tools, CRMs, or any software that speaks HTTP

Backend Automation

Trigger agent workflows from server-side processes without a user interface

Full Control

Manage sessions, pass user metadata, override language, and tag conversations programmatically

No UI Dependency

Unlike Webchat or messaging channels, the API gives you raw input/output with no rendering layer

Creating an API Deployment

1

Select the API Channel

Go to Designer > Deployments and click the API icon in the channel toolbar.

2

Configure General Settings

Give your deployment a Name, an optional Description so your team can identify it later and set the Language the agent will respond in.

3

Create the Deployment

Click Create Deployment. The platform generates your Identifier (Agent Handle) and API Token automatically.

Prerequisites

You need two credentials from your API deployment in Designer > Deployments:

• Deployment Identifier — The deployment's unique identifier (labeled Identifier in the console)

• API Token — A Bearer JWT for the Authorization header

Treat the API Token like a password. Do not expose it in client-side code, public repositories, or browser requests. Store it in environment variables or a secrets manager.

How To Use the API

CORS is fully open (origin: *), so browser-based clients can call the API directly.

Start a session by sending a greeting postback:

curl -X POST 'https://bot-v5.helvia.ai/api/events' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "handle": "<DEPLOYMENT_IDENTIFIER>",
    "message": {
      "payload": { "type": "node", "data": "greeting" }
    },
    "sender": { "id": "test-user-1" }
  }'

Then send a text message in the same session:

curl -X POST 'https://bot-v5.helvia.ai/api/events' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "handle": "<DEPLOYMENT_IDENTIFIER>",
    "message": {
      "text": "Hello, I need help with time management"
    },
    "sender": { "id": "test-user-1" }
  }'

A successful response:

{
  "status": "ok",
  "result": {
    "responses": [
      {
        "id": "TX_b8eb307f-cf33-48fb-bc51-a0e7e6a7d817",
        "type": "text",
        "options": ["Hi! I'm the Productivity Coach."],
        "altText": "Hi! I'm the Productivity Coach."
      },
      {
        "id": "TX_1bfda168-dd49-4dc0-b9fc-56ce9cb5d141",
        "type": "text",
        "options": ["How can I help you today?"],
        "altText": "How can I help you today?"
      }
    ]
  }
}

Each item in the responses array is one message from the agent. The type field indicates the response format (text, buttons, carousel, etc.) and altText contains the plain-text version.

Key Concepts

For the full request/response API schemas and detailed error codes, see the Bot API Reference.

Handle

The handle field is the deployment Identifier from your API deployment settings. It tells the platform which agent and configuration to use for the request.

Sender ID

The sender.id identifies the end user in the conversation. Use a consistent ID (e.g. a UUID) per user to maintain conversation context across messages. If you omit the sender object entirely, the system generates a default ID with the prefix api_subscriber_.

Sessions

Sessions group message exchanges into conversations. A new session is created when:

• A new sender.id sends its first message

• You send a greeting postback to explicitly start a new conversation

• A message arrives from an existing user but the inactivity timeout has elapsed since their last message. The timeout is configurable in Designer > Settings > Configuration.

Within a session, the agent maintains conversational context — collected variables, workflow state, and conversation history carry over between messages.

Text vs Payload

The message object can contain either a text or payload property, but not both. The text contains the users message and the payload is a postback message that triggers a specific flow node, intent, or action.

Advanced: Language Override

Pass a language field to override the deployment's default language for a specific request. The value is a language code like EN, EL, or DE.

Advanced: Tag Operations

Add or remove tags on the current session using the tagOperations field:

"tagOperations": {
  "add": ["vip", "returning-customer"],
  "remove": ["new-user"]
}

Advanced: Response Options

Include additional data in the response using the options field:

Option	Effect
includeMetadata: true	Adds responsesIds and nodesIds arrays to the response
includeStrippedMarkdownTextResponses: true	Adds a responsesStrippedMarkdownText array with plain-text versions (useful for text-to-speech)

Complete Example with All Options

curl -X POST 'https://bot-v5.helvia.ai/api/events' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "handle": "<DEPLOYMENT_IDENTIFIER>",
    "message": {
      "text": "Hello"
    },
    "sender": {
      "id": "user-123",
      "name": "John Doe",
      "email": "[e-mail]"
    },
    "language": "EN",
    "tagOperations": {
      "add": ["vip"]
    },
    "options": {
      "includeMetadata": true,
      "includeStrippedMarkdownTextResponses": true
    }
  }'