> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/api/services/hbf-bot/events.md).

# Events

Send messages to AI Agents and receive responses

## Health check

> Returns a simple status object to verify the service is running.

```json
{"openapi":"3.0.3","info":{"title":"Helvia.ai Bot API","version":"1.0.0"},"tags":[{"name":"Events","description":"Send messages to AI Agents and receive responses"}],"servers":[{"url":"https://bot-v5.helvia.ai","description":"Production"}],"paths":{"/api/events":{"get":{"tags":["Events"],"summary":"Health check","description":"Returns a simple status object to verify the service is running.","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}}}}
```

## Send a message to an AI Agent

> Send a text or postback message to an AI Agent and receive the agent's response(s) synchronously. Use this endpoint for all conversational interactions.\
> \
> \*\*Usage flow:\*\*\
> 1\. Trigger the greeting with a postback message (\`type: "node"\`, \`data: "greeting"\`) to start a new session\
> 2\. Send text messages for each conversation turn\
> 3\. Use a consistent \`sender.id\` to maintain session context across messages

```json
{"openapi":"3.0.3","info":{"title":"Helvia.ai Bot API","version":"1.0.0"},"tags":[{"name":"Events","description":"Send messages to AI Agents and receive responses"}],"servers":[{"url":"https://bot-v5.helvia.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API Token from the console (Designer → Deployments → API → API Token)"}},"schemas":{"EventRequest":{"type":"object","required":["handle","message"],"properties":{"handle":{"type":"string","description":"Agent deployment identifier (from console: Designer → Deployments → API → Identifier)"},"message":{"$ref":"#/components/schemas/Message"},"sender":{"$ref":"#/components/schemas/Sender"},"timestamp":{"type":"number","description":"Unix timestamp in milliseconds"},"language":{"type":"string","description":"Language code override (e.g. \"EN\", \"EL\", \"DE\")"},"tagOperations":{"$ref":"#/components/schemas/TagOperations"},"options":{"$ref":"#/components/schemas/RequestOptions"}}},"Message":{"type":"object","description":"Either a text message (with `text`) or a postback message (with `payload`). Exactly one must be provided.","properties":{"text":{"type":"string","description":"User's text message"},"payload":{"$ref":"#/components/schemas/Postback"},"contexts":{"type":"array","items":{"type":"string"},"description":"Optional context strings"}}},"Postback":{"type":"object","required":["type","data"],"description":"Trigger a specific flow node, intent, or action","properties":{"type":{"type":"string","enum":["node","intent","action"],"description":"Type of postback trigger"},"data":{"description":"Target identifier — node ID (e.g. \"greeting\"), intent name, or action object","oneOf":[{"type":"string"},{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object"}}}}]}}},"Sender":{"type":"object","description":"Identifies the end user. Use a consistent ID per user to maintain conversation context. If omitted, an auto-generated ID with prefix `api_subscriber_` is used.","properties":{"id":{"type":"string","description":"Unique user identifier (required if sender is provided)"},"name":{"type":"string","description":"User display name"},"email":{"type":"string","description":"User email address"}}},"TagOperations":{"type":"object","description":"Add or remove tags on the current session. At least one of `add` or `remove` must be present.","properties":{"add":{"type":"array","items":{"type":"string"},"description":"Tags to add to the session"},"remove":{"type":"array","items":{"type":"string"},"description":"Tags to remove from the session"}}},"RequestOptions":{"type":"object","properties":{"includeMetadata":{"type":"boolean","description":"Include `responsesIds` and `nodesIds` arrays in the result"},"includeStrippedMarkdownTextResponses":{"type":"boolean","description":"Include `responsesStrippedMarkdownText` array with Markdown-stripped plain text"}}},"EventResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"result":{"type":"object","properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/AgentResponse"}},"responsesIds":{"type":"array","items":{"type":"string"},"description":"Response IDs (only when `includeMetadata` is true)"},"nodesIds":{"type":"array","items":{"type":"string"},"description":"Flow node IDs that generated responses (only when `includeMetadata` is true)"},"responsesStrippedMarkdownText":{"type":"array","items":{"type":"string"},"description":"Plain text responses without Markdown (only when `includeStrippedMarkdownTextResponses` is true)"}}}}},"AgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"Response ID (e.g. \"TX_<uuid>\")"},"type":{"type":"string","description":"Response type (text, buttons, cards, etc.)"},"options":{"type":"array","items":{"type":"string"},"description":"Response content"},"altText":{"type":"string","description":"Plain-text version of the response"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Error message"}}}}},"paths":{"/api/events":{"post":{"tags":["Events"],"summary":"Send a message to an AI Agent","description":"Send a text or postback message to an AI Agent and receive the agent's response(s) synchronously. Use this endpoint for all conversational interactions.\n\n**Usage flow:**\n1. Trigger the greeting with a postback message (`type: \"node\"`, `data: \"greeting\"`) to start a new session\n2. Send text messages for each conversation turn\n3. Use a consistent `sender.id` to maintain session context across messages","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventRequest"}}}},"responses":{"200":{"description":"Agent response(s) returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token handle mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.helvia.ai/api/services/hbf-bot/events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.