# 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
    }
  }'
```