# API

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:

{% columns %}
{% column %}
{% content-ref url="../api/services/hbf-bot" %}
[hbf-bot](https://docs.helvia.ai/api/services/hbf-bot)
{% endcontent-ref %}

{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %}

{% endcolumn %}
{% endcolumns %}

### Why Use the API

<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th>Reason</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-webhook">:webhook:</i>  </h4><h4>Custom Integrations</h4></td><td>Embed your agent into mobile apps, internal tools, CRMs, or any software that speaks HTTP</td></tr><tr><td><h4><i class="fa-rectangle-terminal">:rectangle-terminal:</i></h4><h4>Backend Automation</h4></td><td>Trigger agent workflows from server-side processes without a user interface</td></tr><tr><td><h4><i class="fa-gears">:gears:</i> </h4><h4>Full Control</h4></td><td>Manage sessions, pass user metadata, override language, and tag conversations programmatically</td></tr><tr><td><h4><i class="fa-subtitles">:subtitles:</i></h4><h4>No UI Dependency</h4></td><td>Unlike Webchat or messaging channels, the API gives you raw input/output with no rendering layer</td></tr></tbody></table>

### Creating an API Deployment

{% stepper %}
{% step %}

#### Select the API Channel

Go to **Designer > Deployments** and click the **API** icon <i class="fa-code">:code:</i> in the channel toolbar.
{% endstep %}

{% step %}

#### Configure General Settings

Give your deployment a **Name** and optional **Description** so your team can identify it later. Set the **Language** the agent will respond in, and toggle **Enable User Language Detection** to automatically match the user's language.
{% endstep %}

{% step %}

#### Create the Deployment

Click **Create Deployment**. The platform generates your **Identifier** (Agent Handle) and **API Token** automatically.
{% endstep %}
{% endstepper %}

### 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

{% hint style="warning" %}
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.
{% endhint %}

### How To Use the API

{% hint style="success" %}
CORS is fully open (`origin: *`), so browser-based clients can call the API directly.
{% endhint %}

Start a session by sending a greeting postback:

```bash
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:

```bash
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:

```json
{
  "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.](https://docs.helvia.ai/api/services/hbf-bot/events)

<details>

<summary><strong>Handle</strong></summary>

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.&#x20;

</details>

<details>

<summary><strong>Sender ID</strong></summary>

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_`.&#x20;

</details>

<details>

<summary><strong>Sessions</strong></summary>

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.

</details>

<details>

<summary><strong>Text vs Payload</strong></summary>

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.

</details>

<details>

<summary><strong>Advanced: Language Override</strong></summary>

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`.

</details>

<details>

<summary><strong>Advanced: Tag Operations</strong></summary>

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

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

</details>

<details>

<summary><strong>Advanced: Response Options</strong></summary>

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) |

</details>

### Complete Example with All Options

```bash
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": "john@example.com"
    },
    "language": "EN",
    "tagOperations": {
      "add": ["vip"]
    },
    "options": {
      "includeMetadata": true,
      "includeStrippedMarkdownTextResponses": true
    }
  }'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helvia.ai/deploy/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.